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

sqlcommon

package
v0.1.0 Latest Latest
Warning

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

Go to latest
Published: Oct 19, 2026 License: MIT Imports: 17 Imported by: 0

Documentation

Overview

Package sqlcommon implements pkg/store over database/sql for any SQL dialect (decision 0004), following hostweave's dialect layer: one store implementation, a Dialect describing what differs between engines, and embedded per-dialect migrations.

Schema conventions shared by every table (research 15 section 4):

  • Times are BIGINT Unix microseconds, NULL for a zero time; durations are BIGINT milliseconds. Integers compare and sort identically on every engine, which keeps keyset pagination exact.
  • JSON documents are TEXT, so they round-trip byte for byte.
  • Sealed values are BLOB (BYTEA) columns of their own, never inside a document, sealed with the purpose and row id of decision 0017.
  • Text columns that lists sort by are byte-ordered (COLLATE "C" on PostgreSQL, SQLite's default), so every backend pages in the order inmem does.

Index

Constants

This section is empty.

Variables

View Source
var ErrMigration = errors.New("sqlcommon: migration")

ErrMigration reports a malformed or failing migration.

View Source
var ErrNoKeyring = errors.New("sqlcommon: value is sealed but no keyring is configured")

ErrNoKeyring reports a sealed value read by a store opened without a keyring: the server was started without the master key that sealed it.

View Source
var ErrTransaction = errors.New("sqlcommon: transaction failed")

ErrTransaction reports a transaction that could not begin or commit.

Functions

func Insert

func Insert(table string, cols []string) string

Insert renders an INSERT with one placeholder per column.

func InsertIgnore

func InsertIgnore(table string, cols, key []string) string

InsertIgnore renders INSERT ... ON CONFLICT (key) DO NOTHING, or ON CONFLICT DO NOTHING for any unique index when key is empty: a target must name a unique index's exact columns, and the property tables' differ between dialects (PostgreSQL migration 0013).

func Migrate

func Migrate(ctx context.Context, db *sql.DB, d Dialect) ([]int, error)

Migrate applies every pending migration in order, each in its own transaction, and returns the versions applied.

func MustSub

func MustSub(fsys fs.FS, dir string) fs.FS

MustSub returns the sub-tree dir of fsys and panics when it is missing. Backends use it to expose their embedded migrations as a Dialect value.

func Placeholders

func Placeholders(n int) string

Placeholders returns "?, ?, ?" for n values.

func Rollback

func Rollback(ctx context.Context, db *sql.DB, d Dialect, target int) ([]int, error)

Rollback reverts applied migrations newer than target (0 reverts all), newest first, each in its own transaction, and returns the versions reverted.

func Upsert

func Upsert(table string, cols, key []string) string

Upsert renders INSERT ... ON CONFLICT (key) DO UPDATE SET col = excluded.col for every non-key column; SQLite and PostgreSQL share the syntax.

func Version

func Version(ctx context.Context, db *sql.DB, d Dialect) (current, latest int, err error)

Version returns the highest applied version (0 when none) and the highest version the dialect knows, so callers can report a pending schema.

Types

type Dialect

type Dialect struct {
	// Name is used in errors.
	Name string
	// Dollar selects $1-style placeholders (PostgreSQL); otherwise "?".
	Dollar bool
	// ForUpdate is appended to row-locking SELECTs inside transactions, or
	// empty when the engine serialises writers (SQLite).
	ForUpdate string
	// Migrations holds NNNN_name.sql files with "-- +up" and "-- +down"
	// sections.
	Migrations fs.FS
	// IsUniqueViolation reports whether err is the engine's unique or
	// primary-key constraint error, so the store returns store.ErrConflict
	// instead of a driver error when two writers race for one key.
	IsUniqueViolation func(error) bool
}

Dialect describes what differs between SQL engines.

func (Dialect) Rebind

func (d Dialect) Rebind(query string) string

Rebind converts "?" placeholders to the dialect's form. A "?" inside a single-quoted literal is left alone.

type Migration

type Migration struct {
	Version int
	Name    string
	Up      []string
	Down    []string
}

Migration is one parsed migration file.

func LoadMigrations

func LoadMigrations(fsys fs.FS) ([]Migration, error)

LoadMigrations parses every NNNN_name.sql file in fsys, sorted by version.

type Options

type Options struct {
	// SkipMigrate opens without applying migrations.
	SkipMigrate bool
	// Keyring seals secret columns. Without one they are stored in plain
	// text, which only tests should do; the server always configures one.
	Keyring *crypt.Keyring
}

Options configures Open.

type Queryer

type Queryer interface {
	ExecContext(ctx context.Context, query string, args ...any) (sql.Result, error)
	QueryContext(ctx context.Context, query string, args ...any) (*sql.Rows, error)
	QueryRowContext(ctx context.Context, query string, args ...any) *sql.Row
}

Queryer is a pool or the transaction a context carries.

type Store

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

Store implements store.Store over database/sql for one Dialect.

func New

func New(db *sql.DB, d Dialect, keys *crypt.Keyring) *Store

New wraps an open, migrated pool.

func Open

func Open(ctx context.Context, db *sql.DB, d Dialect, o Options) (*Store, error)

Open pings db, applies pending migrations unless o.SkipMigrate, and wraps it. It closes db on failure. Each backend opens its pool and calls it.

func (*Store) AfterCommit

func (*Store) AfterCommit(ctx context.Context, fn func())

AfterCommit implements store.Store.

func (*Store) Archive

func (s *Store) Archive() store.ArchiveStore

Archive implements store.Store.

func (*Store) Blobs

func (s *Store) Blobs() store.BlobIndex

Blobs implements store.Store.

func (*Store) Builds

func (s *Store) Builds() store.BuildStore

Builds implements store.Store.

func (*Store) Bundles

func (s *Store) Bundles() store.BundleStore

Bundles implements store.Store.

func (*Store) Cleanup

func (s *Store) Cleanup() store.CleanupStore

Cleanup implements store.Store.

func (*Store) Close

func (s *Store) Close() error

Close implements store.Store.

func (*Store) Configs

func (s *Store) Configs() store.ConfigStore

Configs implements store.Store.

func (*Store) DB

func (s *Store) DB() *sql.DB

DB returns the pool, for tests and the migrate command.

func (*Store) Dialect

func (s *Store) Dialect() Dialect

Dialect returns the store's dialect.

func (*Store) Distribution

func (s *Store) Distribution() store.DistributionStore

Distribution implements store.Store.

func (*Store) Federation

func (s *Store) Federation() store.FederationStore

Federation implements store.Store.

func (*Store) Groups

func (s *Store) Groups() store.GroupStore

Groups implements store.Store.

func (*Store) Instance

func (s *Store) Instance() store.InstanceStore

Instance implements store.Store.

func (*Store) Items

func (s *Store) Items() store.ItemStore

Items implements store.Store.

func (*Store) Keys

func (s *Store) Keys() store.KeyStore

Keys implements store.Store.

func (*Store) Leases

func (s *Store) Leases() store.LeaseStore

Leases implements store.Store.

func (*Store) Outbox

func (s *Store) Outbox() store.OutboxStore

Outbox implements store.Store.

func (*Store) Packages

func (s *Store) Packages() store.PackageStore

Packages implements store.Store.

func (*Store) Peers

func (s *Store) Peers() store.PeerStore

Peers implements store.Store.

func (*Store) Permissions

func (s *Store) Permissions() store.PermissionStore

Permissions implements store.Store.

func (*Store) Platform

func (s *Store) Platform() store.PlatformStore

Platform implements store.Store.

func (*Store) Projects

func (s *Store) Projects() store.ProjectStore

Projects implements store.Store.

func (*Store) Replicas

func (s *Store) Replicas() store.ReplicaIndex

Replicas implements store.Store.

func (*Store) Replications

func (s *Store) Replications() store.ReplicationStore

Replications implements store.Store.

func (*Store) Repos

func (s *Store) Repos() store.RepoStore

Repos implements store.Store.

func (*Store) Reseal

func (s *Store) Reseal(ctx context.Context) (int, error)

Reseal re-seals every sealed value under the keyring's active version and returns how many values changed. Values already under the active version are left alone, and values stored before a keyring was configured are sealed for the first time, so running it again is harmless. Each value is replaced only if it still holds the bytes that were read, so a concurrent write is never overwritten with a stale secret.

func (*Store) Settings

func (s *Store) Settings() store.SettingsStore

Settings implements store.Store.

func (*Store) Tokens

func (s *Store) Tokens() store.TokenStore

Tokens implements store.Store.

func (*Store) Trash

func (s *Store) Trash() store.TrashStore

Trash implements store.Store.

func (*Store) Tx

func (s *Store) Tx(ctx context.Context, fn func(context.Context) error) error

Tx implements store.Store.

func (*Store) Uploads

func (s *Store) Uploads() store.UploadStore

Uploads implements store.Store.

func (*Store) Users

func (s *Store) Users() store.UserStore

Users implements store.Store.

func (*Store) Webhooks

func (s *Store) Webhooks() store.WebhookStore

Webhooks implements store.Store.

func (*Store) WorkQueue

func (s *Store) WorkQueue() store.WorkQueue

WorkQueue implements store.Store.

func (*Store) Workers

func (s *Store) Workers() store.WorkerStore

Workers implements store.Store.

Jump to

Keyboard shortcuts

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