Error catalog

Generated rustdoc: https://docs.rs/babar/latest/babar/enum.Error.html

See also: Book Chapter 9 — Error handling.

Variants

Every babar::Error variant is matchable directly in application code.

Variant	Shape	When it fires
`Io`	`Io(std::io::Error)`	TCP, TLS, or socket I/O failure (DNS, refused, reset, EOF).
`Closed`	`Closed { sql: Option<String>, origin: Option<Origin> }`	The session was closed and the call lost its connection. `sql` and `origin` carry the in-flight statement.
`Protocol`	`Protocol(String)`	The server sent something babar cannot interpret as a valid protocol exchange.
`Auth`	`Auth(String)`	SCRAM rejected, password wrong, role cannot log in, or no password was configured.
`UnsupportedAuth`	`UnsupportedAuth(String)`	The server selected an authentication method babar does not implement.
`Server`	`Server { code, severity, message, detail, hint, position, sql, origin }`	A PostgreSQL `ErrorResponse`. `code` is the five-character SQLSTATE.
`Config`	`Config(String)`	Client-side configuration is invalid.
`Codec`	`Codec(String)`	An encoder or decoder rejected the bytes or the row shape.
`ColumnAlignment`	`ColumnAlignment { expected, actual, sql, origin }`	The decoder expected `expected` columns but `RowDescription` advertised `actual`.
`SchemaMismatch`	`SchemaMismatch { position, expected_oid, actual_oid, column_name, sql, origin }`	The decoder’s declared OID at `position` differs from the OID PostgreSQL returned.
`Migration`	`Migration(MigrationError)`	A migration step failed; the inner enum carries the migration-specific cause.

Closed, Server, ColumnAlignment, and SchemaMismatch carry an origin field. When a statement came from sql!, query!, command!, or a schema-scoped wrapper generated by schema!, that origin points back to the call site.

SQLSTATE patterns

The code field on Error::Server is a five-character SQLSTATE. This section is guidance for application code, not an exhaustive registry. The full list lives in the PostgreSQL documentation: https://www.postgresql.org/docs/current/errcodes-appendix.html.

Constraint and concurrency

SQLSTATE	Class	Common cause	Typical reaction
`23505`	unique_violation	Duplicate key on insert/upsert.	Map to a 409 in your service; consider `INSERT ... ON CONFLICT`.
`23503`	foreign_key_violation	Inserting a row whose parent does not exist.	422 / validation error.
`23502`	not_null_violation	Missing required column.	422 / validation error.
`23514`	check_violation	A `CHECK` constraint rejected the row.	422 / validation error.
`40001`	serialization_failure	Conflicting concurrent transactions at SERIALIZABLE.	Retry with backoff.
`40P01`	deadlock_detected	The deadlock detector aborted your transaction.	Retry; investigate the lock order.

Authentication and resource

SQLSTATE	Class	Common cause
`28P01`	invalid_password	Wrong password.
`28000`	invalid_authorization_specification	Role cannot log in or `pg_hba.conf` rejected the connection.
`53300`	too_many_connections	Server `max_connections` reached.
`57P03`	cannot_connect_now	Server is starting up or recovering.

Schema

SQLSTATE	Class	Common cause
`42P01`	undefined_table	Missing table, often a missing migration.
`42703`	undefined_column	Missing column or schema drift.
`42P07`	duplicate_table	Setup attempted to create an existing table.

Choosing what to retry

A practical starting policy:

Variant / code	Retry?
`Error::Io(_)`	Yes, with backoff. The connection is gone; the pool can reconnect.
`Error::Server { code: "40001", .. }`	Yes — retry the whole transaction.
`Error::Server { code: "40P01", .. }`	Yes — retry the whole transaction.
`Error::Server { code: "57P03", .. }`	Yes, after a delay.
`Error::Auth(_)` / `UnsupportedAuth(_)`	No. Surface to an operator.
`Error::Codec(_)` / `ColumnAlignment` / `SchemaMismatch`	No. Fix the code or schema expectations.
Other `Error::Server`	No by default; classify by SQLSTATE.

For codec shapes that can produce Error::Codec or SchemaMismatch, see codecs.md. For Config and PoolConfig settings that can produce Error::Config, see configuration.md.

The Book of Babar