Documentation
¶
Overview ¶
Package admin is the database admin service: schema state, verification, correction, seeding, named states, 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 which set applies at startup, and none of the content it administers: the migration set, the seeder with its named sets, 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 name of the set that applies at startup. A nil required collaborator, or a startup set 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 applies the configured set when there is one: idempotent, so a deployment initializes its data at its first start and every later start leaves it as it is. 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.States lists the seeder's declared names; Service.Seed applies a named set, or the configured one, over the schema as it stands; Service.Reset reverts every applied migration, applies the whole set, and seeds the named state's set, the one transition that brings a database to a named state from any other. A seed operation without a seeder or a set is ErrSeedDisabled; an undeclared name is ErrUnknownState. Reset is destructive, in the class of Down and Force; the administrative surface decides who may call it. 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) Reset(ctx context.Context, state string) (Transition, error)
- func (s *Service) Seed(ctx context.Context, state string) (Seeded, error)
- func (s *Service) Start(ctx context.Context) error
- func (s *Service) Statements() Inventory
- func (s *Service) States() []string
- 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 Transition
- 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 the service cannot serve: no // seeder is wired, or the request names no set and the options // configure none. 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") // ErrUnknownState reports a state name the seeder does not declare, // refused before any I/O. ErrUnknownState = errors.New("unknown state") )
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 names the state whose set applies at every startup, once the
// schema is current, and on a seed request that names no set: the way
// a deployment initializes its data. Empty applies none at startup. A
// name without a Seeder is a wiring defect; a name the seeder does not
// declare is a configuration defect that fails startup.
Seed string
// Seeder is the consumer's seed mechanism. nil means the consumer has
// no sets: Start verifies no seed statements, and Seed and Reset
// refuse.
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
States() []string
Seed(ctx context.Context, state string) (Seeded, error)
}
Seeder is the consumer's seed mechanism over its named sets. A set is the data a deployment or a scenario starts from, declared by the consumer under a state name. Verify prepares the seeder's statements against the schema; States lists the declared names, sorted, without I/O; Seed applies one set 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 an opts.Seed name 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) Reset ¶ added in v0.5.0
Reset brings the database to the named state: every applied migration is reverted, the whole set is applied, and the state's set is seeded, each through the same function the verbs and Start run. The revert and the apply each hold the migrator's lock; the seed runs outside it, as Seed does. The request is refused before any I/O the way Seed refuses; a failure at any step leaves the schema where that step stopped, and the status is still read so Ready reflects it.
func (*Service) Seed ¶
Seed applies the named set idempotently over the schema as it stands, or the configured set when state is empty. Without a seeder, or with no set named or configured, the request is refused with ErrSeedDisabled; a name the seeder does not declare is refused with ErrUnknownState; both 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 the configured set, when there is one, is applied.
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) States ¶ added in v0.5.0
States lists the state names the seeder declares, sorted; no seeder declares none. No I/O.
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.
type Transition ¶ added in v0.5.0
type Transition struct {
State string `json:"state"`
Schema Status `json:"schema"`
Seeded Seeded `json:"seeded"`
}
Transition is the result of a reset to a named state: the state, the schema's status after the set was applied, and the rows the state's set inserted.
Source Files