Documentation
¶
Overview ¶
Package database exposes the minimum types the agentregistry server contract guarantees across builds: the sentinel errors every layer returns when input is malformed, a row is missing, etc., and the thin Store interface that AppOptions.DatabaseFactory wraps.
Production code reads and writes v1alpha1 envelopes via the generic v1alpha1store.Store against the v1alpha1.* PostgreSQL schema.
Package database wraps golang-migrate/migrate v4 with the schema-parameterized *migrate.Migrate factory the orchestrator and the arctl db migrate CLI consume. Dirty-state recovery is not attempted here — the orchestrator's idempotent-DDL convention and advisory lock are the production contract.
Index ¶
- Constants
- Variables
- func NewMigrator(ctx context.Context, dsn string, migrationsFS fs.FS, dir string, schema Schema) (*migrate.Migrate, error)
- func NewMigratorWithSearchPath(ctx context.Context, dsn string, migrationsFS fs.FS, dir string, schema Schema, ...) (*migrate.Migrate, error)
- type Schema
- type SchemaRegistry
- type Store
Constants ¶
const OSSSchema = "agentregistry"
OSSSchema is the Postgres schema name OSS tables live in. The `golang-migrate` pgx/v5 driver is configured with `SchemaName: OSSSchema`, so `schema_migrations` and every data table land in this schema.
Exposed as a constant for now; future work makes it env-driven so operators can point the binary at an operator-configured schema.
const OSSSourceName = "oss"
OSSSourceName is the registry key the OSS migration source registers under (orchestrator.Source.Name). Defined here so the migration source (legacymigrate) and the store layer (v1alpha1store) agree on the key without importing each other.
Variables ¶
var ( ErrNotFound = errors.New("record not found") ErrForbidden = errors.New("forbidden") ErrAlreadyExists = errors.New("record already exists") ErrInvalidInput = errors.New("invalid input") ErrDatabase = errors.New("database error") )
Common database errors surfaced by both the v1alpha1 generic Store and any downstream DatabaseFactory that wraps it.
Functions ¶
func NewMigrator ¶ added in v0.1.16
func NewMigrator(ctx context.Context, dsn string, migrationsFS fs.FS, dir string, schema Schema) (*migrate.Migrate, error)
NewMigrator constructs a *migrate.Migrate against `schema` for the embedded migration set at `migrationsFS`/`dir`. The migrator's `schema_migrations` bookkeeping table is created in `schema` (via `migratepgx.Config{SchemaName: schema}`).
The caller owns `mg.Close()` — it tears down both the iofs source and the underlying *sql.DB. A single dedicated connection (not a pool) is used because go-migrate's advisory lock is session-level and must not be shared.
`ctx` is accepted for API symmetry with the surrounding startup code; sql.Open is lazy (never pings) and go-migrate's API is synchronous and doesn't accept a context.
func NewMigratorWithSearchPath ¶ added in v0.4.0
func NewMigratorWithSearchPath(ctx context.Context, dsn string, migrationsFS fs.FS, dir string, schema Schema, additionalSchemas ...Schema) (*migrate.Migrate, error)
NewMigratorWithSearchPath constructs a migrator whose unqualified names resolve first in schema and then in additionalSchemas. Additional schemas let extension migrations call shared functions owned by an earlier source while keeping migration SQL schema-agnostic.
Types ¶
type Schema ¶ added in v0.4.0
type Schema struct {
// contains filtered or unexported fields
}
Schema is a validated Postgres schema name with its quoted identifier precomputed once. Pass a Schema where schema-qualified SQL or a search_path is built, so the raw-vs-quoted distinction lives in one place (see Name vs Quoted/Qualify) and Sanitize runs at construction rather than per query.
func MustNewSchema ¶ added in v0.4.0
MustNewSchema is NewSchema for a compile-time-known schema name (a const or an init-time registration value). It panics on an invalid name, surfacing the misconfiguration at startup rather than threading an error through a constructor. Use NewSchema where the name is runtime/operator input.
func NewSchema ¶ added in v0.4.0
NewSchema validates name as a plain identifier and precomputes its quoted form. Returns an error on an empty or non-identifier name.
func (Schema) Name ¶ added in v0.4.0
Name is the raw schema name. Use for the search_path connection parameter (libpq passes the literal value, unquoted), to_regclass text arguments, and log fields.
func (Schema) Qualify ¶ added in v0.4.0
Qualify returns `<Quoted>.<sanitized table>` — a schema-qualified, injection-safe table reference for SQL. Use for any query that must name the schema explicitly rather than rely on search_path (e.g. a cross-schema read, or a store that may run on a connection whose search_path points elsewhere).
type SchemaRegistry ¶ added in v0.4.0
type SchemaRegistry struct {
// contains filtered or unexported fields
}
SchemaRegistry resolves a migration source's name to its Schema. It is the single source of truth for the schemas a process knows about: built once at the composition root from the registered sources and injected where schema-qualified SQL is built. Not safe for concurrent Add; populate it fully during startup before serving.
func NewSchemaRegistry ¶ added in v0.4.0
func NewSchemaRegistry() *SchemaRegistry
NewSchemaRegistry returns an empty registry.
func OSSSchemaRegistry ¶ added in v0.4.0
func OSSSchemaRegistry() *SchemaRegistry
OSSSchemaRegistry returns a registry preloaded with the OSS source's schema (OSSSourceName → OSSSchema). The composition root injects it into the OSS stores; a multi-source build adds its own sources via Add before injecting. OSSSchema is a compile-time-valid identifier, so the Add cannot fail.
func (*SchemaRegistry) Add ¶ added in v0.4.0
func (r *SchemaRegistry) Add(source, schemaName string) error
Add validates schemaName, precomputes its quoted form, and registers it under source. Errors on an invalid schema name or a duplicate source.
func (*SchemaRegistry) Get ¶ added in v0.4.0
func (r *SchemaRegistry) Get(source string) (Schema, bool)
Get returns the Schema registered for source.
func (*SchemaRegistry) MustGet ¶ added in v0.4.0
func (r *SchemaRegistry) MustGet(source string) Schema
MustGet returns the Schema for source, panicking if absent. Use only where the source is statically known to be registered (e.g. the OSS store layer resolving OSSSourceName at construction); the panic surfaces a wiring bug at startup rather than a nil deref later.
type Store ¶ added in v0.4.0
Store is the root persistence contract AppOptions.DatabaseFactory wraps. The OSS implementation (internal/registry/database.PostgreSQL) is a pgxpool-backed Store; downstream builds layer authz / caching / secondary indices on top by wrapping a base Store.
The contract is intentionally thin: v1alpha1 consumers reach through Pool() to construct their own generic Stores via internal/registry/v1alpha1store.NewStores. Backends without a real PostgreSQL connection return nil from Pool(); callers must gate any pgx-specific functionality accordingly. Close() releases any pooled resources on shutdown.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package legacymigrate copies legacy OSS data from the prior `v1alpha1.*` schema into the orchestrator-owned `agentregistry` schema.
|
Package legacymigrate copies legacy OSS data from the prior `v1alpha1.*` schema into the orchestrator-owned `agentregistry` schema. |
|
Package migrationlint enforces the SQL conventions every migration source must follow, so the OSS set and any downstream set are held to the same contract.
|
Package migrationlint enforces the SQL conventions every migration source must follow, so the OSS set and any downstream set are held to the same contract. |
|
Package orchestrator drives `golang-migrate/migrate/v4` Up against one or more registered Sources behind a single advisory-lock-guarded startup path.
|
Package orchestrator drives `golang-migrate/migrate/v4` Up against one or more registered Sources behind a single advisory-lock-guarded startup path. |