migration

type Action int

type AuditContext struct {
	// Principal identifies who triggered the migration (operator username,
	// service account name, pipeline identifier). Empty values emit with
	// PrincipalUnspecified + a warning so the gap is itself auditable.
	Principal string

	// GitCommitSHA records the source-tree commit the migration was built
	// from. Useful for correlating an audit event to a specific deployment.
	GitCommitSHA string

	// PipelineRunID is an opaque CI/CD run identifier (e.g. a GitHub
	// Actions run ID, a Jenkins build number). Lets compliance reporting
	// trace an audit event back to a pipeline run.
	PipelineRunID string

	// Target overrides the audit event's Target field. Defaults to the
	// database name (db.Database) when empty. Useful for multi-tenant runs
	// where the tenant ID is more informative for compliance correlation
	// than the per-tenant schema name.
	Target string
}

type AuditEvent struct {
	Type               AuditEventType
	Target             string
	AppliedByPrincipal string
	StartedAt          time.Time
	CompletedAt        time.Time
	Outcome            AuditOutcome

	// Version is the Flyway version applied. Set on migration.applied.
	Version string

	// FromState / ToState describe a provisioning-state-machine transition.
	// Set on state.transitioned.
	FromState string
	ToState   string

	// ErrorClass is set when Outcome == failed; one of the published
	// constants above. Empty for success/skipped outcomes.
	ErrorClass ErrorClass

	// GitCommitSHA and PipelineRunID are optional but strongly recommended
	// for deployment-time runs; sourced from explicit caller input.
	GitCommitSHA  string
	PipelineRunID string

	// Attributes is a free-form extension point for callsite-specific
	// metadata. Keys SHOULD use dotted lowercase (e.g. "migration.vendor").
	Attributes map[string]string
}

type AuditEventType string

type AuditOutcome string

type AuditRecorder interface {
	Record(ctx context.Context, event *AuditEvent) error
}

type Config struct {
	FlywayPath    string        // Path to the Flyway executable
	ConfigPath    string        // Path to the configuration file
	MigrationPath string        // Path to migration scripts
	Timeout       time.Duration // Timeout for migration operations
	Environment   string        // Environment (development, testing, production)
	DryRun        bool          // Only validate, do not execute

	// Audit carries the per-call audit-event context required by ADR-019.
	// Populated by operators (CLI flags) or pipelines (env vars or library
	// call argument). The framework will NOT infer Principal from IAM/OS
	// context — empty values flow through with a warning log.
	Audit AuditContext
}

type Emitter interface {
	// Emit dispatches a single AuditEvent through the always-on OpenTelemetry
	// path and the optional AuditRecorder fan-out. Safe for concurrent use;
	// never blocks on the sink.
	Emit(ctx context.Context, ev *AuditEvent)
	// Close drains the optional AuditRecorder queue and tears down the
	// background consumer. Safe to call when no sink is configured (no-op).
	Close(ctx context.Context) error
}

type ErrorClass string

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

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

type MigrateAllOptions struct {
	// BaseConfig supplies Flyway timeout / paths. ConfigPath and
	// MigrationPath are auto-resolved per vendor when zero.
	BaseConfig *Config

	// ContinueOnError keeps iterating after the first per-tenant failure.
	// Default false (fail-fast).
	ContinueOnError bool

	// Parallelism caps concurrent tenant migrations. 0 or 1 = sequential.
	// Implementation caps the value to a reasonable maximum to avoid
	// connection storms.
	Parallelism int

	// Logger receives progress updates. May be nil.
	Logger logger.Logger

	// Hook is invoked after each tenant completes (success or failure).
	// Useful for streaming progress to the CLI / CI logs. May be nil.
	Hook func(TenantResult)

	// Quiesce, when set, gates tenant dispatch on the deployment quiesce flag:
	// once the flag is observed set, no further tenants are dispatched (in-flight
	// tenants drain) and MigrateAll returns ErrQuiesceBlocked with the partial
	// result. Nil disables the check (fully opt-in). Check errors fail open.
	Quiesce QuiesceGate
}

type MigrateAllResult struct {
	Action  Action
	Results []TenantResult
}

type PGRoleSpec struct {
	// Schema is the per-tenant schema name (e.g. "tenant_a"). Owned by
	// MigratorRole after provisioning.
	Schema string

	// MigratorRole owns Schema and is used exclusively by the migration runner.
	// Must differ from RuntimeRole.
	MigratorRole string

	// MigratorPassword is optionally assigned to MigratorRole via ALTER ROLE
	// PASSWORD on every call. Useful for the one-time bootstrap and for
	// secret rotation. Leave empty when credentials are managed externally
	// (e.g., the role is created out-of-band and password set via a
	// privileged migration pipeline).
	MigratorPassword string

	// RuntimeRole is the per-tenant DML-only role consumed by the running
	// service. Must differ from MigratorRole.
	RuntimeRole string

	// RuntimePassword is optionally assigned to RuntimeRole. Same semantics
	// as MigratorPassword — passing it on every call makes secret rotation a
	// no-op rerun.
	RuntimePassword string
}

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

type QuiesceController interface {
	QuiesceGate

	// Set activates quiesce for opts.TTL (defaulted + ceiling-clamped).
	// Idempotent: calling Set on an already-active flag renews ExpiresAt
	// (a heartbeat for long deploys). Records By/Reason for visibility + audit.
	Set(ctx context.Context, opts QuiesceSetOptions) (*QuiesceStatus, error)
	// Clear deactivates the active flag (unconditional operator override; not
	// keyed on the setter's session, so it works even if the setter died).
	// Returns ErrQuiesceNotSet when nothing is active.
	Clear(ctx context.Context, by string) (*QuiesceStatus, error)
	// CreateTable provisions backing storage idempotently (no-op for the
	// in-memory controller).
	CreateTable(ctx context.Context) error
}

type QuiesceGate interface {
	// IsSet reports whether provisioning is currently quiesced. Returns false
	// for an expired (auto-released) or cleared flag.
	IsSet(ctx context.Context) (bool, error)
	// Query returns the full status for operator visibility.
	Query(ctx context.Context) (*QuiesceStatus, error)
}

type QuiesceSetOptions struct {
	By     string
	Reason string
	TTL    time.Duration
}

type QuiesceStatus struct {
	Active    bool       // cleared_at IS NULL AND now < expires_at
	SetAt     time.Time  // when the active/last flag was set
	SetBy     string     // principal that set it (visibility + audit)
	Reason    string     // operator-supplied "why" (deploy id, ticket)
	ExpiresAt time.Time  // TTL hard stop
	ClearedAt *time.Time // nil while uncleared; set when explicitly cleared
	Expired   bool       // cleared_at IS NULL AND now >= expires_at (stale, auto-released)
}

type Result struct {
	// Operation is the Flyway verb. Empty on the error envelope.
	Operation string

	// Success is false whenever Flyway emitted an error envelope, even if
	// the JSON parsed cleanly.
	Success bool

	// AppliedVersions enumerates the migration versions Flyway applied in
	// this run, in the order Flyway reported them. Empty on no-op reruns.
	AppliedVersions []string

	// StartingVersion is the schema version before this run (Flyway's
	// initialSchemaVersion). Empty when Flyway reported it as null —
	// typically on the first migrate against a fresh schema.
	StartingVersion string

	// EndingVersion is the schema version after this run. Flyway reports
	// targetSchemaVersion as null on no-op runs; the parser falls back to
	// StartingVersion in that case so callers always see a usable terminus.
	EndingVersion string

	// DurationMillis is Flyway's totalMigrationTime in milliseconds.
	DurationMillis int64

	// FlywayVersion is the engine version that produced this result.
	FlywayVersion string

	// DatabaseType is Flyway's databaseType field ("PostgreSQL", "Oracle").
	DatabaseType string

	// ErrorCode is Flyway's errorCode on the failure envelope (e.g.
	// "VALIDATE_ERROR" for a checksum mismatch). Empty when Success is true.
	ErrorCode string

	// ErrorMessage is the human-readable error message from Flyway when
	// Success is false. May contain embedded newlines from Flyway.
	ErrorMessage string
}

type SecretFetcher func(ctx context.Context, secretName string) ([]byte, error)

type SecretsProvider struct {
	// Prefix is prepended to each tenant ID when composing the secret name.
	// Empty defaults to DefaultSecretsPrefix at lookup time.
	Prefix string

	// Fetch resolves a secret name to its payload. Required.
	Fetch SecretFetcher
	// contains filtered or unexported fields
}

type TenantLister interface {
	ListTenants(ctx context.Context) ([]string, error)
}

type TenantResult struct {
	TenantID string
	Vendor   string
	Err      error
	Duration time.Duration

	// Result is the parsed Flyway outcome for ActionMigrate. Zero-valued
	// for Validate / Info, or when Flyway crashed before emitting JSON.
	Result Result
}