admin

package
v19.4.0 Latest Latest
Warning

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

 Go to latest Published: Sep 16, 2026 License: MIT Imports: 19 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var ErrDatabaseNotFound = errors.New("workflow database not found")

ErrDatabaseNotFound is returned by GetDatabase when no workflow database has the given ID.

Functions

This section is empty.

Types

type AddDatabaseParams 

type AddDatabaseParams struct {
	DBID     persistence.DBID
	ShardIDs []persistence.ShardID
	Probe    bool
	// IfNotExists makes an already registered db_id a no-op instead of an error when
	// its registered shards match the request, so a declarative deploy step can run
	// the registration on every rollout.
	IfNotExists bool
}

AddDatabaseParams describes a requested workflow-database registration. The db_id and the exact shard IDs are always provided by the operator; nothing is auto-allocated. The existing primary keys (workflow_database.db_id, shard.shard_id) and the shard.db_id foreign key are the collision safety net.

type AddDatabasePlan 

type AddDatabasePlan struct {
	DBID persistence.DBID
	// ShardIDs is the already registered shard set when AlreadyExists is set,
	// otherwise the set to write.
	ShardIDs []persistence.ShardID
	// AlreadyExists reports that the db_id was registered with the requested shards
	// before this plan and ApplyAddDatabase will write nothing.
	AlreadyExists bool
}

AddDatabasePlan is the resolved set of writes PlanAddDatabase would perform.

type Admin 

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

Admin performs administrative operations against an autocore central database.

Mutating operations are split into Plan*/Apply* pairs so callers can render a dry-run plan and only write when explicitly asked.

func New 

func New(ctx context.Context, runtime, migrate *pgtool.Connection, mp metric.MeterProvider, tp trace.TracerProvider, opts ...Option) (*Admin, error)

New opens a pool against the central runtime connection and returns an Admin that owns it; Close shuts it down. migrate points at the central DB under the role able to run DDL (used only by the Migrate* methods).

func NewWithPool 

func NewWithPool(pool *pgxpool.Pool, migrate *pgtool.Connection, opts ...Option) *Admin

NewWithPool returns an Admin backed by an existing pool. The caller retains ownership of the pool; Close does not close it. Used by tests and by callers that already hold a central pool.

func (*Admin) ApplyAddDatabase 

func (a *Admin) ApplyAddDatabase(ctx context.Context, plan AddDatabasePlan) error

ApplyAddDatabase writes the registry row and shard mappings in one transaction. It fails if the db_id already exists, unless the plan was made with IfNotExists.

func (*Admin) ApplyAssignShards 

func (a *Admin) ApplyAssignShards(ctx context.Context, plan AssignShardsPlan) error

ApplyAssignShards inserts the new shard mappings. The shard IDs must not already be mapped: a duplicate is a primary-key violation rather than a silent reassignment.

func (*Admin) Close 

func (a *Admin) Close()

Close releases the central pool if this Admin owns it.

func (*Admin) GetDatabase 

func (a *Admin) GetDatabase(ctx context.Context, dbID persistence.DBID) (DatabaseInfo, error)

GetDatabase returns one workflow database or ErrDatabaseNotFound.

func (*Admin) IsAllMigrationsApplied added in v19.4.0 

func (a *Admin) IsAllMigrationsApplied(ctx context.Context) (bool, error)

IsAllMigrationsApplied neither takes goose's session lock nor writes the version table, so a poll neither blocks behind a migration in progress nor creates the table under a role other than the one Relay migrates with.

func (*Admin) ListDatabases 

func (a *Admin) ListDatabases(ctx context.Context) ([]DatabaseInfo, error)

ListDatabases returns every registered workflow database with its shard allocation.

func (*Admin) ListShardMappings 

func (a *Admin) ListShardMappings(ctx context.Context) ([]persistence.ShardMappingRow, error)

ListShardMappings returns the central shard-to-database mappings, sorted by shard ID.

func (*Admin) MigrateDown 

func (a *Admin) MigrateDown(ctx context.Context) (MigrationResult, error)

MigrateDown rolls back the most recently applied central migration.

func (*Admin) MigrateStatus 

func (a *Admin) MigrateStatus(ctx context.Context) ([]MigrationStatus, error)

MigrateStatus reports the applied/pending state of every central migration.

func (*Admin) MigrateUp 

func (a *Admin) MigrateUp(ctx context.Context) ([]MigrationResult, error)

MigrateUp applies all pending central migrations.

func (*Admin) PlanAddDatabase 

func (a *Admin) PlanAddDatabase(ctx context.Context, p *AddDatabaseParams) (AddDatabasePlan, error)

PlanAddDatabase validates the requested registration and, when p.Probe is set, verifies the runtime and migration DSNs are reachable. It performs no writes and reads nothing for allocation: the db_id and shard IDs are taken verbatim.

func (*Admin) PlanAssignShards 

func (a *Admin) PlanAssignShards(ctx context.Context, dbID persistence.DBID, shardIDs []persistence.ShardID) (AssignShardsPlan, error)

PlanAssignShards validates an explicit set of shard IDs to assign to an existing database. It errors with ErrDatabaseNotFound if the database is unknown. It performs no allocation: the shard IDs are taken verbatim.

func (*Admin) Seed 

func (a *Admin) Seed(ctx context.Context, dbID persistence.DBID, shardIDs []persistence.ShardID) error

Seed upserts a workflow-database row and its shard mappings. It is idempotent.

NOT for production use. Intended for integration tests and local development that need to set up central state quickly. Production registration goes through PlanAddDatabase/ApplyAddDatabase, which refuse to overwrite an existing db_id.

func (*Admin) Status 

func (a *Admin) Status(ctx context.Context, opts StatusOptions) (Status, error)

Status returns an overview of central schema state and the workflow-database registry. With opts.Live it also queries each workflow DB's shard_lease table.

type AssignShardsPlan 

type AssignShardsPlan struct {
	DBID     persistence.DBID
	ShardIDs []persistence.ShardID
}

AssignShardsPlan is the resolved set of new shard IDs ApplyAssignShards would map onto an existing workflow database.

type DatabaseInfo 

type DatabaseInfo struct {
	DBID       persistence.DBID
	ShardCount int
	MinShard   persistence.ShardID // 0 when ShardCount == 0
	MaxShard   persistence.ShardID // 0 when ShardCount == 0
}

DatabaseInfo describes one registered workflow database and its shard allocation.

type DatabaseStatus 

type DatabaseStatus struct {
	DatabaseInfo
	Reachable   bool
	OwnedShards int
}

DatabaseStatus augments DatabaseInfo with live ownership when requested.

type MigrationResult 

type MigrationResult struct {
	Path      string
	Version   int64
	Direction string
	Duration  time.Duration
	Empty     bool
}

MigrationResult is the outcome of applying or rolling back one migration.

type MigrationStatus 

type MigrationStatus struct {
	Path      string
	Version   int64
	Applied   bool
	AppliedAt time.Time
}

MigrationStatus is the applied/pending state of one central migration.

type Option added in v19.4.0 

type Option func(*Admin)

Option configures an Admin.

func WithWorkflowDBs added in v19.4.0 

func WithWorkflowDBs(w WorkflowDBOpener) Option

WithWorkflowDBs lets the operations that connect to a workflow database reach it the way Relay does at runtime. Without it those operations have nowhere to get a connection from.

type Status 

type Status struct {
	SchemaUpToDate    bool
	PendingMigrations int
	TotalShards       int
	Databases         []DatabaseStatus
}

Status is a high-level overview of the central database.

type StatusOptions 

type StatusOptions struct {
	// Live when true connects to each workflow database's runtime connection and
	// reports live shard ownership.
	// Best-effort: unreachable DBs are marked Reachable=false rather than failing the whole call.
	Live bool
}

StatusOptions controls how much Status gathers.

type WorkflowDBOpener added in v19.4.0 

type WorkflowDBOpener interface {
	OpenPool(ctx context.Context, dbID persistence.DBID, opts ...pgtool.PoolOption) (*pgxpool.Pool, error)
	OpenMigrationDB(ctx context.Context, dbID persistence.DBID) (*sql.DB, error)
}

WorkflowDBOpener opens connections on a workflow database. The two methods are the two credential sets a database has, so a caller can reach it under either.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.