Help us shape the future of Go! Take the 2026 Go Developer Survey

sqlc

package
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 20, 2026 License: MIT Imports: 9 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

View Source
var (
	ErrBatchAlreadyClosed = errors.New("batch already closed")
)

Functions

This section is empty.

Types

type AdvanceScheduleParams

type AdvanceScheduleParams struct {
	LastRun time.Time
	NextRun time.Time
	ID      uuid.UUID
}

type ClaimJobsOldestParams

type ClaimJobsOldestParams struct {
	Owner      string
	Ttl        pgtype.Interval
	QueueName  string
	BatchLimit int32
}

type ClaimJobsParams

type ClaimJobsParams struct {
	Owner      string
	Ttl        pgtype.Interval
	QueueName  string
	BatchLimit int32
}

type CompleteJobParams

type CompleteJobParams struct {
	ID    uuid.UUID
	Owner string
	Token int64
}

type DBTX

type DBTX interface {
	Exec(context.Context, string, ...interface{}) (pgconn.CommandTag, error)
	Query(context.Context, string, ...interface{}) (pgx.Rows, error)
	QueryRow(context.Context, string, ...interface{}) pgx.Row
	CopyFrom(ctx context.Context, tableName pgx.Identifier, columnNames []string, rowSrc pgx.CopyFromSource) (int64, error)
	SendBatch(context.Context, *pgx.Batch) pgx.BatchResults
}

type DueSchedulesParams

type DueSchedulesParams struct {
	Now        time.Time
	BatchLimit int32
}

type FailJobParams

type FailJobParams struct {
	Permanent bool
	RetryAt   time.Time
	Cause     *string
	ID        uuid.UUID
	Owner     string
	Token     int64
}

type GetJobByIdemParams

type GetJobByIdemParams struct {
	Queue          string
	IdempotencyKey string
}

type HeartbeatLeasesParams

type HeartbeatLeasesParams struct {
	Until  time.Time
	Owner  string
	Ids    []uuid.UUID
	Tokens []int64
}

type HeartbeatLeasesRow

type HeartbeatLeasesRow struct {
	ID              uuid.UUID
	LeaseToken      int64
	CancelRequested bool
}

type InsertJobEventParams

type InsertJobEventParams struct {
	JobID      uuid.UUID
	Queue      string
	Type       string
	FromStatus string
	ToStatus   string
	Attempt    int32
	Error      *string
	At         *time.Time
}

type InsertJobEventsBatchBatchResults

type InsertJobEventsBatchBatchResults struct {
	// contains filtered or unexported fields
}

func (*InsertJobEventsBatchBatchResults) Close

func (*InsertJobEventsBatchBatchResults) Exec

func (b *InsertJobEventsBatchBatchResults) Exec(f func(int, error))

type InsertJobEventsBatchParams

type InsertJobEventsBatchParams struct {
	JobID      uuid.UUID
	Queue      string
	Type       string
	FromStatus string
	ToStatus   string
	Attempt    int32
	Error      *string
	At         *time.Time
}

type InsertJobParams

type InsertJobParams struct {
	ID             uuid.UUID
	Queue          string
	Type           string
	Payload        []byte
	Priority       int16
	RunAt          *time.Time
	Delay          pgtype.Interval
	MaxAttempts    int32
	Backoff        []byte
	IdempotencyKey *string
	Traceparent    *string
}

type InsertJobsCopyParams

type InsertJobsCopyParams struct {
	ID             uuid.UUID
	Queue          string
	Type           string
	Payload        []byte
	Priority       int16
	RunAt          time.Time
	MaxAttempts    int32
	Backoff        []byte
	IdempotencyKey *string
	Traceparent    *string
}

type InsertProcessedEffectParams

type InsertProcessedEffectParams struct {
	Scope string
	Key   string
	JobID uuid.UUID
}

type InsertScheduleParams

type InsertScheduleParams struct {
	ID          uuid.UUID
	Name        string
	Cron        string
	Timezone    string
	Queue       string
	JobType     string
	Payload     []byte
	Priority    int16
	MaxAttempts int32
	Backoff     []byte
	Enabled     bool
	NextRun     time.Time
}

type Job

type Job struct {
	ID              uuid.UUID
	Queue           string
	Type            string
	Payload         []byte
	Status          JobStatus
	Priority        int16
	RunAt           time.Time
	Attempts        int32
	MaxAttempts     int32
	Backoff         []byte
	LeaseOwner      *string
	LeaseUntil      *time.Time
	LastError       *string
	IdempotencyKey  *string
	CancelRequested bool
	CreatedAt       time.Time
	UpdatedAt       time.Time
	StartedAt       *time.Time
	FinishedAt      *time.Time
	LeaseToken      int64
	Traceparent     *string
}

type JobEvent

type JobEvent struct {
	ID         int64
	JobID      uuid.UUID
	Queue      string
	Type       string
	FromStatus *JobStatus
	ToStatus   JobStatus
	Attempt    int32
	Error      *string
	At         time.Time
}

type JobStatus

type JobStatus string
const (
	JobStatusQueued    JobStatus = "queued"
	JobStatusLeased    JobStatus = "leased"
	JobStatusSucceeded JobStatus = "succeeded"
	JobStatusFailed    JobStatus = "failed"
	JobStatusDead      JobStatus = "dead"
	JobStatusCancelled JobStatus = "cancelled"
)

func (*JobStatus) Scan

func (e *JobStatus) Scan(src interface{}) error

type ListJobsParams

type ListJobsParams struct {
	Queue          *string
	Status         *JobStatus
	Type           *string
	AfterCreatedAt *time.Time
	AfterID        uuid.NullUUID
	PageLimit      int32
}

type ListSchedulesParams

type ListSchedulesParams struct {
	AfterName string
	PageLimit int32
}

type NotifyReadyParams

type NotifyReadyParams struct {
	Channel string
	Queue   string
}

type NullJobStatus

type NullJobStatus struct {
	JobStatus JobStatus
	Valid     bool // Valid is true if JobStatus is not NULL
}

func (*NullJobStatus) Scan

func (ns *NullJobStatus) Scan(value interface{}) error

Scan implements the Scanner interface.

func (NullJobStatus) Value

func (ns NullJobStatus) Value() (driver.Value, error)

Value implements the driver Valuer interface.

type ProcessedEffect

type ProcessedEffect struct {
	Scope       string
	Key         string
	JobID       uuid.UUID
	ProcessedAt time.Time
}

type ProcessedEffectExistsParams

type ProcessedEffectExistsParams struct {
	Scope string
	Key   string
}

type PurgeJobsParams

type PurgeJobsParams struct {
	Statuses   []string
	Queue      *string
	OlderThan  pgtype.Interval
	BatchLimit int32
}

type Queries

type Queries struct {
	// contains filtered or unexported fields
}

func New

func New(db DBTX) *Queries

func (*Queries) AdvanceSchedule

func (q *Queries) AdvanceSchedule(ctx context.Context, arg AdvanceScheduleParams) (int64, error)

func (*Queries) CancelQueuedJob

func (q *Queries) CancelQueuedJob(ctx context.Context, id uuid.UUID) (Job, error)

func (*Queries) ClaimJobs

func (q *Queries) ClaimJobs(ctx context.Context, arg ClaimJobsParams) ([]Job, error)

One round trip = batch claim + lease + attempts++. The CTE takes the row locks (SKIP LOCKED, so concurrent claimers never wait on each other) and the UPDATE flips them to leased. started_at is the first claim; attempts counts starts; lease_token is bumped so every claim carries a fresh fencing token.

func (*Queries) ClaimJobsOldest

func (q *Queries) ClaimJobsOldest(ctx context.Context, arg ClaimJobsOldestParams) ([]Job, error)

ClaimJobs in pure age order (run_at, id), ignoring priority: the anti- starvation claim taken every CLAIM_FIFO_EVERY-th time (index jobs_ready_fifo).

func (*Queries) CompleteJob

func (q *Queries) CompleteJob(ctx context.Context, arg CompleteJobParams) (Job, error)

Owner- and token-guarded so a stale worker cannot resurrect a reaped job. A job whose cancel was requested while it ran ends cancelled, not succeeded. No row = ErrLeaseLost.

func (*Queries) DBNow

func (q *Queries) DBNow(ctx context.Context) (time.Time, error)

func (*Queries) DeleteSchedule

func (q *Queries) DeleteSchedule(ctx context.Context, id uuid.UUID) (int64, error)

func (*Queries) DueSchedules

func (q *Queries) DueSchedules(ctx context.Context, arg DueSchedulesParams) ([]Schedule, error)

Run inside a short transaction by the store: the row locks keep two leaders (or a retried tick) from materialising the same schedule at the same moment.

func (*Queries) FailJob

func (q *Queries) FailJob(ctx context.Context, arg FailJobParams) (Job, error)

retry_at is computed in Go from job.Policy (the single source of backoff truth). cancelled wins over dead wins over queued; a retry is queued with a future run_at.

func (*Queries) GetJob

func (q *Queries) GetJob(ctx context.Context, id uuid.UUID) (Job, error)

func (*Queries) GetJobByIdem

func (q *Queries) GetJobByIdem(ctx context.Context, arg GetJobByIdemParams) (Job, error)

func (*Queries) GetJobForUpdate

func (q *Queries) GetJobForUpdate(ctx context.Context, id uuid.UUID) (Job, error)

func (*Queries) GetSchedule

func (q *Queries) GetSchedule(ctx context.Context, id uuid.UUID) (Schedule, error)

func (*Queries) HeartbeatLeases

func (q *Queries) HeartbeatLeases(ctx context.Context, arg HeartbeatLeasesParams) ([]HeartbeatLeasesRow, error)

Returns the leases actually extended: (id, token) pairs zipped by the parallel unnest, guarded by owner and token. A lease that already expired is not revived (fencing: once lease_until has passed the reaper may take the job at any moment), and cancel_requested is returned so the store can report cancelled ids apart.

func (*Queries) InsertJob

func (q *Queries) InsertJob(ctx context.Context, arg InsertJobParams) (Job, error)

Every time comparison and default below uses the database clock (now()), never a value computed by the application; see internal/postgres/doc.go "The clock rule". run_at: an absolute client-supplied time, or NULL for now() + delay on the DB clock. The partial unique index jobs_idem_uniq makes the ON CONFLICT target; a NULL key never conflicts. No row returned means the (queue, idempotency_key) already exists.

func (*Queries) InsertJobEvent

func (q *Queries) InsertJobEvent(ctx context.Context, arg InsertJobEventParams) error

func (*Queries) InsertJobEventsBatch

Batch form for claims: the same row as InsertJobEvent, sent as one pgx batch.

func (*Queries) InsertJobsCopy

func (q *Queries) InsertJobsCopy(ctx context.Context, arg []InsertJobsCopyParams) (int64, error)

func (*Queries) InsertProcessedEffect

func (q *Queries) InsertProcessedEffect(ctx context.Context, arg InsertProcessedEffectParams) (int64, error)

func (*Queries) InsertSchedule

func (q *Queries) InsertSchedule(ctx context.Context, arg InsertScheduleParams) (Schedule, error)

func (*Queries) ListJobEvents

func (q *Queries) ListJobEvents(ctx context.Context, jobID uuid.UUID) ([]JobEvent, error)

func (*Queries) ListJobs

func (q *Queries) ListJobs(ctx context.Context, arg ListJobsParams) ([]Job, error)

Keyset page over (created_at, id) newest first; every filter is optional. The page limit is passed as limit+1 by the store to detect the next page.

func (*Queries) ListSchedules

func (q *Queries) ListSchedules(ctx context.Context, arg ListSchedulesParams) ([]Schedule, error)

func (*Queries) NotifyReady

func (q *Queries) NotifyReady(ctx context.Context, arg NotifyReadyParams) error

func (*Queries) ProcessedEffectExists

func (q *Queries) ProcessedEffectExists(ctx context.Context, arg ProcessedEffectExistsParams) (bool, error)

func (*Queries) PruneJobEvents

func (q *Queries) PruneJobEvents(ctx context.Context, olderThan pgtype.Interval) (int64, error)

func (*Queries) PurgeJobs

func (q *Queries) PurgeJobs(ctx context.Context, arg PurgeJobsParams) (int64, error)

Deletes finished jobs (and their events) matching queue/statuses/age, oldest first.

func (*Queries) QueueDepth

func (q *Queries) QueueDepth(ctx context.Context) ([]QueueDepthRow, error)

func (*Queries) RequestCancel

func (q *Queries) RequestCancel(ctx context.Context, id uuid.UUID) (Job, error)

func (*Queries) RequeueExpiredJob

Reaper step 2, one row per expired lease, sent as one pgx batch inside the reaper transaction. run_at is only applied to rows going back to queued.

func (*Queries) RetryJob

func (q *Queries) RetryJob(ctx context.Context, id uuid.UUID) (Job, error)

func (*Queries) SelectExpiredLeases

func (q *Queries) SelectExpiredLeases(ctx context.Context, arg SelectExpiredLeasesParams) ([]SelectExpiredLeasesRow, error)

Reaper step 1 (inside the reaper transaction). Step 2 is RequeueExpired with the per-id verdict computed in Go so the backoff policy has exactly one implementation.

func (*Queries) UpdateSchedule

func (q *Queries) UpdateSchedule(ctx context.Context, arg UpdateScheduleParams) (Schedule, error)

func (*Queries) WithTx

func (q *Queries) WithTx(tx pgx.Tx) *Queries

type QueueDepthRow

type QueueDepthRow struct {
	Queue       string
	Status      JobStatus
	N           int64
	OldestRunAt time.Time
}

type RequeueExpiredJobBatchResults

type RequeueExpiredJobBatchResults struct {
	// contains filtered or unexported fields
}

func (*RequeueExpiredJobBatchResults) Close

func (*RequeueExpiredJobBatchResults) Exec

func (b *RequeueExpiredJobBatchResults) Exec(f func(int, error))

type RequeueExpiredJobParams

type RequeueExpiredJobParams struct {
	Status string
	RunAt  time.Time
	Cause  string
	ID     uuid.UUID
}

type Schedule

type Schedule struct {
	ID          uuid.UUID
	Name        string
	Cron        string
	Timezone    string
	Queue       string
	JobType     string
	Payload     []byte
	Priority    int16
	MaxAttempts int32
	Backoff     []byte
	Enabled     bool
	NextRun     time.Time
	LastRun     *time.Time
	CreatedAt   time.Time
	UpdatedAt   time.Time
}

type SelectExpiredLeasesParams

type SelectExpiredLeasesParams struct {
	Now        time.Time
	BatchLimit int32
}

type SelectExpiredLeasesRow

type SelectExpiredLeasesRow struct {
	ID              uuid.UUID
	Queue           string
	Type            string
	Attempts        int32
	MaxAttempts     int32
	Backoff         []byte
	CancelRequested bool
}

type UpdateScheduleParams

type UpdateScheduleParams struct {
	ID          uuid.UUID
	Cron        string
	Timezone    string
	Queue       string
	JobType     string
	Payload     []byte
	Priority    int16
	MaxAttempts int32
	Backoff     []byte
	Enabled     bool
	NextRun     time.Time
}

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL