Documentation
¶
Overview ¶
Package admin is the database admin service: schema state, verification, correction, seeding, and diagnostics as operations over the sqlate library's functions, run once at startup and on demand from an administrative surface. The service owns the operations and their policy, such as when the seed runs, and none of the content it administers: the migration set, the seeder, the pattern catalog, and the statements registry are the consumer's, passed in at construction.
Construction ¶
New takes the pool's lifecycle object, the sqlate session over the same pool, the migrator the consumer built over its migration set, and the pattern catalog every statement compiles against. Options carries the optional collaborators: a Seeder, a Registry, a logger, and the seed switch. A nil required collaborator, or the seed switch without a seeder, is a wiring defect and panics, per the database package's wiring rule.
Startup ¶
Service.Register declares the service on a lifecycle coordinator at Stage, after the pool at stage 0 and before the domains verify their statements at stage 2. Service.Start verifies the migration history, applies a pending set under the migrator's lock and verifies again, verifies the seeder's statements, and seeds when the switch is on. A state the mechanism cannot correct, a dirty row or a history the set does not carry, fails startup; an operator resolves it through the verbs. Service.Ready reports a clean, complete schema as of the last operation, so a readiness probe aggregating the service reflects it.
Operations ¶
Every operation is a trigger over a library function. Service.Verify, Service.Status, Service.Up, Service.Down, Service.Steps, and Service.Force call the migrator's verb of the same name; the mutating verbs return the refreshed Status. Service.Seed runs the seeder when the switch is on and returns ErrSeedDisabled otherwise. Service.Catalog and Service.Statements read the pattern catalog and the statements registry without I/O. Service.Diagnose pings the pool, reads the server's version through the dialect's Versioner capability when it has one, and reports the pool's counters. The HTTP half, a route group over these methods, is application code.
Index ¶
- Constants
- Variables
- type Catalog
- type Diagnostics
- type DomainStatements
- type Entry
- type Inventory
- type MigrationInfo
- type Options
- type Pattern
- type Pool
- type Registry
- type Seeded
- type Seeder
- type Service
- func (s *Service) Catalog() Catalog
- func (s *Service) Diagnose(ctx context.Context) (Diagnostics, error)
- func (s *Service) Down(ctx context.Context, n int) (Status, error)
- func (s *Service) Force(ctx context.Context, version int) (Status, error)
- func (s *Service) Ready() bool
- func (s *Service) Register(lc *lifecycle.Coordinator)
- func (s *Service) Seed(ctx context.Context) (Seeded, error)
- func (s *Service) Start(ctx context.Context) error
- func (s *Service) Statements() Inventory
- func (s *Service) Status(ctx context.Context) (Status, error)
- func (s *Service) Steps(ctx context.Context, n int) (Status, error)
- func (s *Service) Up(ctx context.Context) (Status, error)
- func (s *Service) Verify(ctx context.Context) error
- type StatementInfo
- type Status
- type Versioner
Constants ¶
const Stage = 1
Stage is the lifecycle stage the schema correction runs in: after the pool at stage 0, before the domains verify their statements at stage 2.
Variables ¶
var ( // ErrSeedDisabled reports a seed request in an environment whose // options do not enable seeding. ErrSeedDisabled = errors.New("seeding is disabled") // ErrValidation classifies a rejected administrative request: a verb // argument outside its domain, refused before any I/O. ErrValidation = errors.New("validation failed") )
Functions ¶
This section is empty.
Types ¶
type Catalog ¶
type Catalog struct {
Namespaces []string `json:"namespaces"`
Patterns []Pattern `json:"patterns"`
}
Catalog is the pattern catalog as an operator reads it: every namespace the composition root registered and every pattern under them, in namespace then name order. It is build-time state; the read has no write.
type Diagnostics ¶
type Diagnostics struct {
Dialect string `json:"dialect"`
Ping time.Duration `json:"ping"`
ServerVersion string `json:"server_version,omitempty"`
Pool Pool `json:"pool"`
Namespaces []string `json:"namespaces"`
}
Diagnostics is one read of the database's health: the dialect, the ping latency, the server's version when the dialect supplies the statement, the pool's counters, and the pattern namespaces the catalog registered.
type DomainStatements ¶
type DomainStatements struct {
Name string `json:"name"`
Statements []StatementInfo `json:"statements"`
}
DomainStatements is one domain's compiled inventory.
type Entry ¶
type Entry struct {
Name string
Statements *query.Statements
}
Entry is one domain's compiled statements, registered under its name.
type Inventory ¶
type Inventory struct {
Domains []DomainStatements `json:"domains"`
}
Inventory is the statements registry as an operator reads it: every domain that registered its compiled statements, in the registry's order, each statement as the library holds it. Build-time state; no write.
type MigrationInfo ¶
type MigrationInfo struct {
Version int `json:"version"`
Name string `json:"name"`
Transactional bool `json:"transactional"`
Applied bool `json:"applied"`
}
MigrationInfo describes one migration of the set.
type Options ¶
type Options struct {
// Seed enables seeding: at every startup, and on demand. Seeds are
// development and test tooling; production leaves it off and carries
// reference data as migrations. Seed without a Seeder is a wiring
// defect.
Seed bool
// Seeder is the consumer's seed mechanism. nil means the consumer has
// none: Start verifies no seed statements, and Seed refuses.
Seeder Seeder
// Registry is the consumer's statements registry. nil means Statements
// reports no domains.
Registry Registry
// Logger receives the startup narrative. nil is silent.
Logger *slog.Logger
}
Options holds the collaborators and switches the composition root chooses.
type Pattern ¶
type Pattern struct {
Namespace string `json:"namespace"`
Name string `json:"name"`
Tier string `json:"tier"`
Native string `json:"native,omitempty"`
Slots []string `json:"slots"`
Text string `json:"text"`
}
Pattern is one catalog entry: its namespace and name, its tier and native note, the slots its body declares, and the body as the library composes or splices it.
type Pool ¶
type Pool struct {
Open int `json:"open"`
InUse int `json:"in_use"`
Idle int `json:"idle"`
MaxOpen int `json:"max_open"`
WaitCount int64 `json:"wait_count"`
WaitDuration time.Duration `json:"wait_duration"`
}
Pool is the connection pool's counters.
type Registry ¶
type Registry interface {
Registry() []Entry
}
Registry lists the statements every domain registered, in the order the inventory reports them.
type Seeder ¶
type Seeder interface {
Verify(ctx context.Context) error
Seed(ctx context.Context) (Seeded, error)
}
Seeder is the consumer's seed mechanism: Verify prepares its statements against the schema, and Seed loads the reference data idempotently and counts what it inserted.
type Service ¶
type Service struct {
// contains filtered or unexported fields
}
Service is the database admin service. Every operation is a trigger over the migrator, the session, the seeder, or the catalog; Start runs the same functions the on-demand verbs do. Ready reports a clean, complete schema and follows every operation.
func New ¶
func New(pool *database.DB, db *sqlate.DB, m *migrate.Migrator, c *query.Catalog, opts Options) *Service
New builds the service over pool, the lifecycle object it administers; db, the sqlate session over the same pool; m, the migrator the consumer built over its migration set; and c, the catalog every statement compiles against. A nil pool, db, m, or c panics, as does opts.Seed without opts.Seeder: each is a wiring defect at the composition root.
func (*Service) Catalog ¶
Catalog reads the pattern catalog: every namespace and every pattern, so an operator sees a pattern's text, tier, and slots as the library holds them. No I/O.
func (*Service) Diagnose ¶
func (s *Service) Diagnose(ctx context.Context) (Diagnostics, error)
Diagnose reads the database's health: the dialect, a timed ping through the pool's lifecycle object, the server's version when the dialect supplies the statement, and the pool's counters.
func (*Service) Force ¶
Force sets the history to version, clearing dirty state; 0 empties it. It never touches the schema: it exists to clear a dirty row after the operator has repaired the schema by hand, and it can just as well manufacture one, since a forced-down history re-applies files against objects that still exist.
func (*Service) Ready ¶
Ready reports whether the history is the set's clean head, as of the last operation.
func (*Service) Register ¶
func (s *Service) Register(lc *lifecycle.Coordinator)
Register declares the schema stage on lc: Start corrects the schema and Ready gates readiness on it.
func (*Service) Seed ¶
Seed runs the seeder when this environment enables it; off, or without a seeder, the request is refused with ErrSeedDisabled before any I/O.
func (*Service) Start ¶
Start brings the schema to the set's head: a pending history is applied under the migrator's lock; a clean, complete one passes. A state the mechanism cannot correct, a dirty row or a history the set does not carry, fails startup; an operator resolves it through the verbs (force, then up) on a process started against a corrected database, or from another replica. The seeder's statements are then verified against the schema, and with seeding enabled the seed runs.
func (*Service) Statements ¶
Statements reads the statements registry: every domain's compiled inventory, the counterpart of Catalog for authored files. No I/O; no registry reports no domains.
func (*Service) Steps ¶
Steps applies n pending migrations when n is positive, or reverts -n applied ones when it is negative; zero is rejected.
type StatementInfo ¶
type StatementInfo struct {
Name string `json:"name"`
Tier string `json:"tier"`
Native string `json:"native,omitempty"`
TransactionRequired bool `json:"transaction_required"`
Params []string `json:"params"`
Key string `json:"key,omitempty"`
Fields []string `json:"fields,omitempty"`
Text string `json:"text"`
}
StatementInfo is one compiled statement: its declarations, its parameters in position order, and the text the engine receives.
type Status ¶
type Status struct {
Version int `json:"version"`
Dirty bool `json:"dirty"`
Pending []int `json:"pending"`
Ready bool `json:"ready"`
Migrations []MigrationInfo `json:"migrations"`
}
Status is the schema's state against the migration set: the applied head, whether it is dirty, the versions still pending, whether the service reports ready (a clean, complete history), and every migration of the set with whether it is applied.
Source Files