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 ¶
- Variables
- func Insert(table string, cols []string) string
- func InsertIgnore(table string, cols, key []string) string
- func Migrate(ctx context.Context, db *sql.DB, d Dialect) ([]int, error)
- func MustSub(fsys fs.FS, dir string) fs.FS
- func Placeholders(n int) string
- func Rollback(ctx context.Context, db *sql.DB, d Dialect, target int) ([]int, error)
- func Upsert(table string, cols, key []string) string
- func Version(ctx context.Context, db *sql.DB, d Dialect) (current, latest int, err error)
- type Dialect
- type Migration
- type Options
- type Queryer
- type Store
- func (*Store) AfterCommit(ctx context.Context, fn func())
- func (s *Store) Archive() store.ArchiveStore
- func (s *Store) Blobs() store.BlobIndex
- func (s *Store) Builds() store.BuildStore
- func (s *Store) Bundles() store.BundleStore
- func (s *Store) Cleanup() store.CleanupStore
- func (s *Store) Close() error
- func (s *Store) Configs() store.ConfigStore
- func (s *Store) DB() *sql.DB
- func (s *Store) Dialect() Dialect
- func (s *Store) Distribution() store.DistributionStore
- func (s *Store) Federation() store.FederationStore
- func (s *Store) Groups() store.GroupStore
- func (s *Store) Instance() store.InstanceStore
- func (s *Store) Items() store.ItemStore
- func (s *Store) Keys() store.KeyStore
- func (s *Store) Leases() store.LeaseStore
- func (s *Store) Outbox() store.OutboxStore
- func (s *Store) Packages() store.PackageStore
- func (s *Store) Peers() store.PeerStore
- func (s *Store) Permissions() store.PermissionStore
- func (s *Store) Platform() store.PlatformStore
- func (s *Store) Projects() store.ProjectStore
- func (s *Store) Replicas() store.ReplicaIndex
- func (s *Store) Replications() store.ReplicationStore
- func (s *Store) Repos() store.RepoStore
- func (s *Store) Reseal(ctx context.Context) (int, error)
- func (s *Store) Settings() store.SettingsStore
- func (s *Store) Tokens() store.TokenStore
- func (s *Store) Trash() store.TrashStore
- func (s *Store) Tx(ctx context.Context, fn func(context.Context) error) error
- func (s *Store) Uploads() store.UploadStore
- func (s *Store) Users() store.UserStore
- func (s *Store) Webhooks() store.WebhookStore
- func (s *Store) WorkQueue() store.WorkQueue
- func (s *Store) Workers() store.WorkerStore
Constants ¶
This section is empty.
Variables ¶
var ErrMigration = errors.New("sqlcommon: migration")
ErrMigration reports a malformed or failing migration.
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.
var ErrTransaction = errors.New("sqlcommon: transaction failed")
ErrTransaction reports a transaction that could not begin or commit.
Functions ¶
func InsertIgnore ¶
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 ¶
Migrate applies every pending migration in order, each in its own transaction, and returns the versions applied.
func MustSub ¶
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 Rollback ¶
Rollback reverts applied migrations newer than target (0 reverts all), newest first, each in its own transaction, and returns the versions reverted.
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.
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 Open ¶
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 ¶
AfterCommit implements store.Store.
func (*Store) Archive ¶
func (s *Store) Archive() store.ArchiveStore
Archive implements store.Store.
func (*Store) Cleanup ¶
func (s *Store) Cleanup() store.CleanupStore
Cleanup implements store.Store.
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) Instance ¶
func (s *Store) Instance() store.InstanceStore
Instance implements store.Store.
func (*Store) Packages ¶
func (s *Store) Packages() store.PackageStore
Packages 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) Reseal ¶
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) Webhooks ¶
func (s *Store) Webhooks() store.WebhookStore
Webhooks implements store.Store.