migration

var ErrDatabasePasswordTooShort = errors.New("migration: database password too short to safely redact Flyway output")

ErrDatabasePasswordTooShort is returned by the migrate path when a non-empty database password is shorter than minRedactablePasswordLength. Such passwords cannot be safely redacted from Flyway output, so the migration is rejected before running rather than suppressing the output and hiding the outcome. Match with errors.Is. Empty passwords (trust/IAM auth) are exempt.

var ErrEmptyTenantID = errors.New("migration: tenantID is empty")

ErrEmptyTenantID is returned when DBConfig is invoked with a blank tenant ID.

var ErrEnvFieldHasControlChar = errors.New("migration: env field contains forbidden control character (CR/LF/NUL)")

ErrEnvFieldHasControlChar is returned when a DatabaseConfig field destined for the Flyway subprocess environment contains a forbidden control character (CR, LF, or NUL). Go's exec.Cmd.Env passes strings to execve(2) verbatim and does not split on newlines, so this isn't a known injection path — but rejecting at the boundary prevents a compromised secret writer from propagating multi-line surprises into downstream logs or env-parsing tools.

var ErrFleetSplit = errors.New("migration: fleet split")

ErrFleetSplit is the Verdict of a run that dispatched at least one tenant but left at least one listed tenant failed or never dispatched: the fleet may be at mixed versions and needs a re-run.

var ErrFlywayCanceled = errors.New("migration: flyway canceled")

ErrFlywayCanceled marks a run the framework killed via parent-context cancellation (a fail-fast sibling abort in a parallel MigrateAll, or operator Ctrl-C) rather than its own deadline. Like a timeout, the SIGKILL can leave the schema partially applied — schema state is unknown; do not auto-retry blindly.

var ErrFlywayOutputUnparsed = errors.New("flyway output could not be parsed")

ErrFlywayOutputUnparsed wraps the underlying parse failure (errEmptyFlywayOutput or a JSON decode error) so a zero-exit run whose output is empty, malformed, or redaction-suppressed surfaces as a non-nil error instead of a silent success. Match with errors.Is.

var ErrFlywayReportedFailure = errors.New("flyway reported a failed migration")

ErrFlywayReportedFailure is returned when Flyway emitted a well-formed JSON envelope that itself reports failure (Result.Success == false), including when the subprocess exited 0. Match with errors.Is.

var ErrFlywayTimeout = errors.New("migration: flyway timed out")

ErrFlywayTimeout marks a run the framework killed on its own deadline. The schema state is UNKNOWN: Flyway may have applied part of a migration before the process group died, so this is not a clean failure and an automatic retry can race a partially applied change. Match with errors.Is — the audit ErrorClass cannot carry this (classifyFlywayError matches on Flyway's stdout, which a SIGKILLed JVM never gets to write), so the machine-readable signals are this sentinel and the migration.timed_out audit attribute.

var ErrIncompleteMigrationTarget = errors.New(
	"migration: PostgreSQL requires database.host and database.database (or database.connectionstring) " +
		"so the framework can build the Flyway JDBC URL; a partially filled database block, or any " +
		"database.tls setting the framework cannot put on a URL, is rejected rather than silently " +
		"deferring to the URL in flyway.conf, which the framework does not read")

ErrIncompleteMigrationTarget rejects a PostgreSQL config the framework cannot build a URL from when deferring to the conf would lose a guarantee: either the block is PARTIALLY filled (some identity field set, but not a usable host AND database — a target broken in transit, e.g. a tenant whose host arrived blank from a secret store), or database.tls is set and would silently fail to reach the connection, which is the whole of #1047. It covers the DISCRETE-FIELD shapes only: a database.tls block beside a connectionstring loses the same guarantee but has its own remedy — the DSN for the runtime, flyway.conf for the migration — so it gets its own sentinel, ErrMigrationTLSWithConnectionString. A block naming NO identity field and no TLS is conf-owned by construction and still defers. The error names the fields but never echoes a value; the per-tenant caller pairs it with TenantResult.TenantID. Match with errors.Is.

var ErrInvalidMigrationHost = errors.New("migration: database.host is not a valid hostname or IP address")

ErrInvalidMigrationHost rejects a database.host that is neither an IP literal nor a plain DNS name. The host is the one URL component that cannot be percent-encoded (it must stay a routable address), so it is validated instead: unescaped, a value like `h/?sslmode=disable&x=` ends the authority early and pgjdbc reads the injected parameters, turning a verify-full config into a cleartext connection to a host of the value's choosing. The error names the field but never echoes it — a misconfigured host can hold a whole DSN, password included. Match with errors.Is.

var ErrInvalidMigrationPort = errors.New("migration: database.port must be between 1 and 65535, or 0 for the driver default")

ErrInvalidMigrationPort rejects a database.port outside the TCP range. Zero is the documented "unset" case — urlAuthority omits the port and the driver takes its default — but a NEGATIVE port took that same branch, so a config that clearly meant a port silently connected to pgjdbc's 5432 instead, and nothing observed a port above 65535 either. config.validateOptionalDatabasePort applies the same `< 0 || > 65535` rule with the same zero-is-unset carve-out; this is the migrator's own copy, for the per-tenant configs that never passed it. The error names the field but never echoes the value. Match with errors.Is.

var ErrInvalidMigrationTLSMode = errors.New("migration: database.tls.mode is not a supported sslmode")

ErrInvalidMigrationTLSMode rejects a database.tls.mode that is not one of the libpq set once surrounding whitespace is trimmed. buildPostgresJDBCURL copies the mode onto the URL verbatim, so an unsupported one reached Flyway and failed inside the driver — or, worse, was ignored by it — instead of failing here as a typed error. config.Validate already refuses it (ADR-062); this is the migrator's own copy, for the per-tenant configs from a dynamic DBConfigProvider or the CLI's tenants.yaml that never passed it, the same reason the host, port and connectionstring rules have one. The offending MODE is echoed — it is a fixed keyword, not caller data — but nothing else from the config is, since a database block carries a password and a DSN. Match with errors.Is.

var ErrInvalidMigratorIdentity = errors.New("migration: invalid migrator identity")

ErrInvalidMigratorIdentity is returned when MigrateAllOptions.MigratorIdentity is set with an empty username or password, a password too short to redact from Flyway output, or a CR/LF/NUL in either.

var ErrInvalidPGIdentifier = errors.New("migration: PostgreSQL identifier rejected")

ErrInvalidPGIdentifier is returned by Validate when a role or schema name fails the safe-identifier check enforced by ProvisionPGRoles.

var ErrInvalidPrefix = errors.New("migration: invalid secrets prefix (must end with '/')")

ErrInvalidPrefix indicates the configured prefix is unusable.

var ErrInvalidQuiesceTTL = errors.New("migration: quiesce TTL must not be negative")

ErrInvalidQuiesceTTL is returned by Set when QuiesceSetOptions.TTL is negative. Zero is valid (means DefaultQuiesceTTL); negative is rejected rather than silently defaulted, so a bad operator input fails loudly instead of pausing provisioning for an unintended duration.

var ErrInvalidQuiesceTable = errors.New("migration: invalid quiesce table name")

ErrInvalidQuiesceTable is returned by NewPostgresQuiesceController when the supplied table name fails the safe-identifier check.

var ErrInvalidTenantID = errors.New("migration: tenantID contains characters outside [A-Za-z0-9_-] or exceeds 128 characters")

ErrInvalidTenantID is returned when DBConfig is invoked with a tenant ID that contains characters outside the [A-Za-z0-9_-] allowlist or exceeds the 128-character length bound.

var ErrMigrationMTLSUnsupported = errors.New(
	"migration: PostgreSQL client-certificate TLS (database.tls.cert/database.tls.key) is not supported for Flyway migrations: " +
		"the framework does not forward them as the JDBC sslcert/sslkey parameters, so it refuses rather than " +
		"migrating without the client certificate; use database.tls.mode + database.tls.ca for server-authenticated TLS, " +
		"or migrate outside the framework")

ErrMigrationMTLSUnsupported rejects a migration whose config asks for PostgreSQL client-certificate authentication. The limit is OURS, not pgjdbc's: the framework does not forward `database.tls.cert`/`key` as the JDBC `sslcert`/`sslkey` parameters, so it refuses rather than migrating without the client certificate the config asked for. Match with errors.Is.

var ErrMigrationTLSCARequiresVerify = errors.New(
	"migration: database.tls.ca requires database.tls.mode verify-ca or verify-full: pgjdbc reads sslrootcert " +
		"only under those two modes, so under require/allow/prefer (or an unset mode, which is prefer) the CA " +
		"would be ignored and the migration would not authenticate the server")

ErrMigrationTLSCARequiresVerify rejects a database.tls.ca that cannot actually authenticate the server. pgjdbc reads `sslrootcert` only under `verify-ca` and `verify-full`; `require`, `allow` and `prefer` all use a NON-VALIDATING socket factory, and an unset mode is `prefer`, which also falls back to plaintext. So a config naming a CA under any of those got an unverified — possibly unencrypted — migration while reading as though it pinned one.

This is deliberately STRICTER than config.Validate, which admits `require` beside a ca (ADR-062): pgx treats `require` + ca as verify-ca, a documented libpq inheritance, so the RUNTIME really does verify there. pgjdbc does not, and the migrator answers for pgjdbc. The divergence is the point — the same config is honored at runtime and refused for migration rather than silently unverified. Match with errors.Is.

var ErrMigrationTLSCASystemUnsupported = errors.New(
	"migration: database.tls.ca: system is not supported for Flyway migrations: it is a libpq/pgx sentinel for " +
		"the platform trust store and pgjdbc has no equivalent, treating the value as a file path; point " +
		"database.tls.ca at the CA certificate file itself for the migration configuration")

ErrMigrationTLSCASystemUnsupported rejects the `ca: system` sentinel for migrations. It is a libpq/pgx spelling meaning "the platform trust store", and pgjdbc has no equivalent: LibPQFactory special-cases nothing and treats the value as a FILE PATH, so `sslrootcert=system` names a file that does not exist (verified against pgjdbc REL42.7.12). Mapping it to the JVM's own default trust store would not be equivalent either — `cacerts` is a different trust set from the one pgx consults, so the migration would authenticate against CAs the runtime does not, which is the silent divergence ADR-085 exists to remove. Name a real CA file for the migration instead. Match with errors.Is.

var ErrMigrationTLSWithConnectionString = errors.New(
	"migration: database.tls is set alongside database.connectionstring: the framework does not parse DSNs, " +
		"so the TLS settings cannot reach the migration connection; remove the database.tls block, putting its " +
		"settings in the connection string for the RUNTIME pool, and set the migration's own TLS parameters on " +
		"the JDBC url in flyway.conf, which owns the migration connection for a connectionstring config; that " +
		"url must also name the same host and database as the connection string, or the migration is encrypted " +
		"but applied to the wrong target")

ErrMigrationTLSWithConnectionString rejects a PostgreSQL config that sets both `database.connectionstring` and `database.tls.*`. The framework does not parse DSNs, so it cannot lift the TLS material onto a URL it builds; deferring to the conf would run the migration on the DSN with the configured TLS silently dropped. config.Validate already refuses this shape (ADR-062), but a per-tenant DatabaseConfig can reach MigrateFor without ever passing through it — a dynamic DBConfigProvider, or the CLI's tenants.yaml — so the migrator fails closed on its own rather than trusting the caller to have validated. Match with errors.Is.

var ErrNameForFailed = errors.New("migration: NameFor failed to compose a secret name")

ErrNameForFailed indicates the custom NameFor hook returned an error or a blank (empty/whitespace-only) name for a validated tenant ID.

var ErrNoConfigProvider = errors.New("migration: database.DBConfigProvider is nil")

ErrNoConfigProvider is returned when MigrateAll is called without a DBConfigProvider.

var ErrNoFetcher = errors.New("migration: SecretsProvider.Fetch is nil")

ErrNoFetcher indicates the SecretsProvider was constructed without a Fetch function.

var ErrNoLister = errors.New("migration: TenantLister is nil")

ErrNoLister is returned when MigrateAll is called without a TenantLister.

var ErrNothingAttempted = errors.New("migration: no tenant attempted")

ErrNothingAttempted is the Verdict of a run that dispatched no tenant (empty listing, listing failure, context done or quiesce set before the first dispatch): no schema was touched.

var ErrPGRoleFloorViolated = errors.New("migration: role holds attributes above the provisioning floor")

ErrPGRoleFloorViolated is returned by CheckPGRoleFloor when a role holds an attribute the provisioning floor denies; the message names each one.

var ErrPGRoleNotFound = errors.New("migration: role not found")

ErrPGRoleNotFound is returned by CheckPGRoleFloor when no role has the name.

var ErrPGRolePasswordHasControlChar = errors.New("migration: role password contains forbidden control character (CR/LF/NUL)")

ErrPGRolePasswordHasControlChar is returned by Validate when a role password contains CR, LF, or NUL. Such a password cannot be carried log-safely through the provisioning path: summarizeStmt collapses a failing statement to its first line, so an embedded newline would split a redacted summary apart. PostgreSQL itself accepts these passwords — the rejection is ours, at this API's boundary. Mirrors ErrEnvFieldHasControlChar, which guards the Flyway subprocess environment.

var ErrPGRoleSkippedMigratorHasPassword = errors.New("migration: MigratorPassword must be empty when SkipMigratorRole is set")

ErrPGRoleSkippedMigratorHasPassword is returned by Validate when SkipMigratorRole is set together with a non-empty MigratorPassword, so a leftover password can never alter a migrator role managed out of band.

var ErrQuiesceBlocked = errors.New("migration: paused by deployment quiesce flag")

ErrQuiesceBlocked is returned by MigrateAll when the deployment quiesce flag is set: dispatch of not-yet-started tenants stops and the partial result is returned. Distinguish a paused run from a failed one via errors.Is.

var ErrQuiesceNotSet = errors.New("migration: no active quiesce flag")

ErrQuiesceNotSet is returned by Clear when no flag has ever been set, or it was already explicitly cleared. An expired-but-uncleared flag is still clearable and does not trigger this error.

var ErrReservedPGIdentifier = errors.New("migration: identifier is reserved by PostgreSQL")

ErrReservedPGIdentifier is returned by Validate when a spec field names something PostgreSQL reserves, matched case-insensitively: "public" or a "pg_"-prefixed name in any of the three fields, plus "information_schema" for Schema alone. It is always wrapped with ErrInvalidPGIdentifier, so a caller matching the identifier sentinel keeps matching, and no IdentifierPolicy can waive it. Such a name passes every charset check while landing the tenant's tables in the schema every role on the instance can read (Schema "public") or granting that tenant's DML to every role on the instance (a role named "public", which PostgreSQL's RoleSpec maps onto the PUBLIC pseudo-role).

var ErrSecretMalformed = errors.New("migration: secret payload malformed")

ErrSecretMalformed indicates the secret payload could not be parsed into a usable DatabaseConfig in either canonical or RDS-rotation form.

var ErrSharedMigratorSchemaRequired = errors.New(
	"migration: shared migrator requires an explicit database.postgresql.schema; the framework does not read " +
		"flyway.conf, so a conf-owned flyway.defaultSchema cannot aim this run")

ErrSharedMigratorSchemaRequired is returned by every verb when a runner built with WithSharedMigrator (see its godoc) targets a PostgreSQL DatabaseConfig whose database.postgresql.schema is empty. Match with errors.Is.