sql

var (
	// UnknownDialect is returned by ParseDialect for a name that is in
	// neither the accepted nor the refused set.
	UnknownDialect = errs.Define(CodeUnknownDialect, "UNKNOWN_DIALECT",
		"The SQL dialect is not one this SDK supports",
		"core/data/sql: dialect name is not in the accepted set (postgres, mysql, sqlite); the field carries the name",
		errs.WithExitCode(exitConfig))

	// DialectRefused is returned by ParseDialect for an engine this SDK
	// recognises and declines. It is a DIFFERENT answer from UnknownDialect:
	// a caller debugging a refusal needs to know whether their engine is
	// unheard-of or known-and-declined, because only the second one comes
	// with a reason they can evaluate.
	DialectRefused = errs.Define(CodeDialectRefused, "DIALECT_REFUSED",
		"That SQL engine is recognised and deliberately not supported",
		"core/data/sql: the engine's savepoint grammar is a different algorithm, not a different string; the reason field says which",
		errs.WithExitCode(exitConfig))

	// NestedIsolation is returned when a nested Transact asks for non-zero
	// options. A nested scope is a SAVEPOINT inside an already-open
	// transaction, and a savepoint changes neither the isolation level nor
	// the read-only-ness of that transaction. Honouring the request is
	// impossible; ignoring it would hand the caller a weaker transaction than
	// the one they asked for, under a nil error.
	NestedIsolation = errs.Define(CodeNestedIsolation, "NESTED_ISOLATION",
		"A nested transaction cannot change isolation or read-only mode",
		"core/data/sql: a nested scope is a savepoint; open the outer transaction with the options instead",
		errs.WithExitCode(exitConfig))

	// InvalidMigration is returned for a migration that could never run. The
	// "missing" field names which half is absent.
	InvalidMigration = errs.Define(CodeInvalidMigration, "INVALID_MIGRATION",
		"The migration is not runnable and was refused",
		"core/data/sql: migration has version 0, an empty name, a nil Up or a nil Down; the missing field names which",
		errs.WithExitCode(exitConfig))

	// MigrationIrreversible is what the Irreversible step returns. It is the
	// caller's own declaration coming back at them, not a defect the SDK
	// found — which is why it reads as a statement about the migration rather
	// than about the runner.
	MigrationIrreversible = errs.Define(CodeMigrationIrreversible, "MIGRATION_IRREVERSIBLE",
		"That migration was declared irreversible and cannot be rolled back",
		"core/data/sql: Down is the Irreversible step; reversing it requires a new forward migration",
		errs.WithExitCode(exitConfig))

	// ConfigInvalid is returned by every constructor in
	// internal/service/data/sql for a Config that could never produce a
	// working port.
	ConfigInvalid = errs.Define(CodeConfigInvalid, "CONFIG_INVALID",
		"The SQL configuration is incomplete and was refused",
		"service/data/sql: Config has a nil DB or an unusable Dialect; the missing field names which",
		errs.WithExitCode(exitConfig))

	// PoolMisconfigured is returned when a pool field's zero value would be
	// read by database/sql as a policy nobody chose. MaxOpen is the case that
	// matters: database/sql reads 0 as UNLIMITED, and "as many connections as
	// the application happens to want" is a decision made by forgetting a
	// line, not by taking one (ADR 0031's refusal side).
	PoolMisconfigured = errs.Define(CodePoolMisconfigured, "POOL_MISCONFIGURED",
		"The connection-pool policy is not one this SDK will apply",
		"service/data/sql: a non-positive MaxOpen means unlimited in database/sql; state the ceiling explicitly",
		errs.WithExitCode(exitConfig))

	// BeginFailed is joined with the driver's error when a transaction could
	// not be opened. Nothing ran.
	BeginFailed = errs.Define(CodeBeginFailed, "BEGIN_FAILED",
		"The database refused to open a transaction",
		"service/data/sql: BeginTx failed; the driver error travels beside this one under errors.Join",
		errs.WithExitCode(exitTempFail), errs.WithHTTPStatus(httpUnavailable))

	// CommitFailed is joined with the driver's error when COMMIT was
	// rejected. It says the unit of work did NOT take effect, which is the
	// one fact a caller must not have to infer.
	CommitFailed = errs.Define(CodeCommitFailed, "COMMIT_FAILED",
		"The transaction could not be committed and had no effect",
		"service/data/sql: COMMIT was rejected; the driver error travels beside this one under errors.Join",
		errs.WithExitCode(exitTempFail), errs.WithHTTPStatus(httpUnavailable))

	// RollbackFailed travels ALONGSIDE the error that triggered the rollback,
	// never instead of it. A teardown that also breaks is a second defect,
	// and reporting only it would hide the first — the rule ADR 0050 wrote
	// for UnwindFailed, applied to the same shape one layer down.
	RollbackFailed = errs.Define(CodeRollbackFailed, "ROLLBACK_FAILED",
		"Rolling the transaction back did not complete cleanly",
		"service/data/sql: ROLLBACK was rejected; the connection is discarded by database/sql",
		errs.WithExitCode(exitTempFail))

	// SavepointFailed is returned when SAVEPOINT, RELEASE SAVEPOINT or
	// ROLLBACK TO SAVEPOINT is rejected. The "statement" field names which of
	// the three, because the consequences differ: a failed SAVEPOINT means
	// the nested scope never started, while a failed ROLLBACK TO means the
	// engine's state is unknown and the transaction is poisoned.
	SavepointFailed = errs.Define(CodeSavepointFailed, "SAVEPOINT_FAILED",
		"A savepoint statement was rejected by the database",
		"service/data/sql: the statement field names which of SAVEPOINT / RELEASE / ROLLBACK TO failed",
		errs.WithExitCode(exitTempFail))

	// TxPoisoned refuses every further operation on a transaction whose
	// savepoint rollback failed.
	//
	// This is the answer to "does a failed sub-transaction condemn the outer
	// one?". Normally NO: ROLLBACK TO SAVEPOINT is precisely the statement
	// that clears PostgreSQL's aborted state, so a caught inner failure
	// leaves a usable transaction. But when that statement ITSELF fails, the
	// engine's state is no longer known, and continuing would commit a
	// transaction containing work the SDK believes it undid.
	TxPoisoned = errs.Define(CodeTxPoisoned, "TX_POISONED",
		"The transaction is no longer usable and will not be committed",
		"service/data/sql: a savepoint rollback failed, so the engine state is unknown; the whole transaction is abandoned",
		errs.WithExitCode(exitTempFail))

	// TxClosed is returned when an Executor is used after the scope that lent
	// it returned. database/sql would answer ErrTxDone for a finished
	// transaction and would EXECUTE for a nested scope whose outer
	// transaction is still open — the second case is the one worth catching.
	TxClosed = errs.Define(CodeTxClosed, "TX_CLOSED",
		"That transaction handle is no longer valid",
		"service/data/sql: the Executor outlived its Transact scope; it is valid only for the duration of the call",
		errs.WithExitCode(exitConfig))

	// HealthCheckFailed is joined with the driver's error when the probe was
	// answered with a failure.
	HealthCheckFailed = errs.Define(CodeHealthCheckFailed, "HEALTH_CHECK_FAILED",
		"The database is not reachable",
		"service/data/sql: PingContext returned an error; the driver error travels beside this one under errors.Join",
		errs.WithExitCode(exitTempFail), errs.WithHTTPStatus(httpUnavailable))

	// HealthCheckTimeout is returned when the probe did not answer inside its
	// budget. It is a separate code from HealthCheckFailed because a database
	// that refuses is a different operational fact from one that hangs, and a
	// readiness endpoint routes on the difference.
	HealthCheckTimeout = errs.Define(CodeHealthCheckTimeout, "HEALTH_CHECK_TIMEOUT",
		"The database did not answer the health check in time",
		"service/data/sql: the probe budget expired; the ping goroutine is abandoned, never killed",
		errs.WithExitCode(exitTempFail), errs.WithHTTPStatus(httpUnavailable))

	// MigrationFailed is joined with the step's own error when a migration or
	// its bookkeeping row fails. The transaction was rolled back, so neither
	// the schema change nor the version row took effect — except on engines
	// with non-transactional DDL, which is stated in the package doc rather
	// than papered over.
	MigrationFailed = errs.Define(CodeMigrationFailed, "MIGRATION_FAILED",
		"A migration did not apply and was rolled back",
		"service/data/sql: version+direction fields; step error joined; on MySQL DDL commits implicitly, "+
			"so a failed step can leave the schema change applied WITHOUT its version row (ADR 0055 D8)",
		errs.WithExitCode(exitTempFail))

	// MigrationOutOfOrder refuses a pending migration whose version is lower
	// than one already applied. It is the two-branches-merged hazard: both
	// branches numbered from the same base, one shipped first, and the other
	// would now apply UNDER it — producing a schema that matches neither
	// branch's expectation and a version table that cannot express what
	// happened.
	MigrationOutOfOrder = errs.Define(CodeMigrationOutOfOrder, "MIGRATION_OUT_OF_ORDER",
		"A pending migration is older than one already applied",
		"service/data/sql: renumber the migration above the highest applied version; the fields carry both",
		errs.WithExitCode(exitConfig))

	// MigrationLockUnsupported is the refusal of a Migrator over a dialect
	// that offers no lock dying with its holder — never a run without one: a
	// runner that silently drops mutual exclusion is at its most dangerous
	// exactly when two instances start together, which is the case it exists
	// for.
	//
	// No dialect the SDK speaks answers it since ADR 0140: PostgreSQL and
	// MySQL serialise on the session's advisory lock, SQLite on the database
	// file's write lock. It stays defined because it is published, and a
	// caller matching it would otherwise stop compiling.
	MigrationLockUnsupported = errs.Define(CodeMigrationLockUnsupported, "MIGRATION_LOCK_UNSUPPORTED",
		"That dialect has no advisory lock, so migrations cannot be serialised",
		"service/data/sql: the dialect offers neither a session-scoped advisory lock nor a database-file lock; wire your own exclusion",
		errs.WithExitCode(exitConfig))

	// MigrationLockTimeout is returned when another holder kept the migration
	// lock for the whole budget. Nothing was applied.
	MigrationLockTimeout = errs.Define(CodeMigrationLockTimeout, "MIGRATION_LOCK_TIMEOUT",
		"Another process is running migrations and did not finish in time",
		"service/data/sql: the advisory lock was held throughout the budget; no migration was applied",
		errs.WithExitCode(exitTempFail))

	// MigrationUnknownVersion refuses a Down over a version the running
	// binary has no migration for. The database is ahead of the code, and
	// reversing a change whose Down is not present would be guessing.
	MigrationUnknownVersion = errs.Define(CodeMigrationUnknownVersion, "MIGRATION_UNKNOWN_VERSION",
		"The database records a migration this build does not carry",
		"service/data/sql: Down cannot reverse a version with no Step; deploy the build that owns it",
		errs.WithExitCode(exitConfig))

	// VersionTableInvalid refuses a version-table name that is not a bare SQL
	// identifier. A table name cannot be a bound parameter, so it is
	// interpolated — which makes validating it the only thing between a
	// configuration string and an injection.
	VersionTableInvalid = errs.Define(CodeVersionTableInvalid, "VERSION_TABLE_INVALID",
		"The version-table name is not a plain SQL identifier",
		"service/data/sql: an identifier cannot be bound as a parameter, so only [A-Za-z_][A-Za-z0-9_]* is accepted",
		errs.WithExitCode(exitConfig))

	// DuplicateMigration refuses two migrations declaring the same version.
	// The version IS the identity, so a duplicate makes "has this been
	// applied?" unanswerable.
	DuplicateMigration = errs.Define(CodeDuplicateMigration, "DUPLICATE_MIGRATION",
		"Two migrations declare the same version",
		"service/data/sql: a version identifies a migration; the field carries the duplicated value",
		errs.WithExitCode(exitConfig))
)