use std::{fmt, time::Duration};
use sqlx::migrate::MigrateError;
use thiserror::Error;
use crate::{
db::MigrationFailureKind,
result::{ClassifyError, Diagnostic, DiagnosticKind, ErrorDescriptor, ErrorKind},
};
use super::identity::database_name;
#[derive(Error)]
#[non_exhaustive]
pub enum PostgresPoolError {
#[error("PostgreSQL operation failed")]
Sqlx(#[from] sqlx::Error),
}
impl fmt::Debug for PostgresPoolError {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
formatter
.debug_struct("PostgresPoolError")
.field("error_code", &self.error_code())
.field("source", &"[REDACTED]")
.finish()
}
}
impl ClassifyError for PostgresPoolError {
fn error_kind(&self) -> ErrorKind {
ErrorKind::Dependency
}
fn error_code(&self) -> crate::result::ErrorCode {
crate::result::ErrorCode::internal("postgres_unavailable")
}
}
#[derive(Error)]
#[non_exhaustive]
pub enum PostgresBootstrapError {
#[error("migrate_on_startup requires a SQLx migrator")]
MissingMigrator,
#[error("failed to ensure PostgreSQL database exists: {diagnosis}")]
EnsureDatabase {
diagnosis: PostgresDiagnostic,
#[source]
source: Box<sqlx::Error>,
},
#[error("failed to connect to PostgreSQL: {diagnosis}")]
Connect {
diagnosis: PostgresDiagnostic,
#[source]
source: Box<PostgresPoolError>,
},
#[error("failed to run PostgreSQL migrations: {diagnosis}")]
Migration {
diagnosis: PostgresDiagnostic,
#[source]
source: Box<MigrateError>,
},
#[error("failed to acquire PostgreSQL schema-maintenance lock for migrations: {diagnosis}")]
MigrationLock {
diagnosis: PostgresDiagnostic,
#[source]
source: Box<sqlx::Error>,
},
#[error("timed out waiting for the PostgreSQL schema-maintenance lock: {diagnosis}")]
MigrationLockTimeout {
diagnosis: PostgresDiagnostic,
timeout: Duration,
},
#[error("timed out while running PostgreSQL migrations: {diagnosis}")]
MigrationTimeout {
diagnosis: PostgresDiagnostic,
timeout: Duration,
},
}
impl fmt::Debug for PostgresBootstrapError {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
formatter
.debug_struct("PostgresBootstrapError")
.field("error_code", &self.error_code())
.field("diagnosis", &self.diagnosis())
.field("source", &"[REDACTED]")
.finish()
}
}
impl ClassifyError for PostgresBootstrapError {
fn error_kind(&self) -> ErrorKind {
match self {
Self::MissingMigrator => ErrorKind::Validation,
Self::MigrationLockTimeout { .. } | Self::MigrationTimeout { .. } => ErrorKind::Timeout,
Self::EnsureDatabase { .. }
| Self::Connect { .. }
| Self::Migration { .. }
| Self::MigrationLock { .. } => ErrorKind::Dependency,
}
}
fn error_code(&self) -> crate::result::ErrorCode {
crate::result::ErrorCode::internal(match self {
Self::MissingMigrator => "postgres_migrator_required",
Self::EnsureDatabase { .. } => "postgres_ensure_database_failed",
Self::Connect { .. } => "postgres_connect_failed",
Self::Migration { .. } => "postgres_migration_failed",
Self::MigrationLock { .. } => "postgres_migration_lock_failed",
Self::MigrationLockTimeout { .. } => "postgres_migration_lock_timeout",
Self::MigrationTimeout { .. } => "postgres_migration_timeout",
})
}
fn error_descriptor(&self) -> ErrorDescriptor {
ErrorDescriptor::new(self.error_kind(), self.error_code(), self.to_string())
.with_retryable(self.diagnosis().is_some_and(PostgresDiagnostic::retryable))
}
}
impl PostgresBootstrapError {
#[must_use]
pub const fn diagnosis(&self) -> Option<&PostgresDiagnostic> {
match self {
Self::EnsureDatabase { diagnosis, .. }
| Self::Connect { diagnosis, .. }
| Self::Migration { diagnosis, .. }
| Self::MigrationLock { diagnosis, .. }
| Self::MigrationLockTimeout { diagnosis, .. }
| Self::MigrationTimeout { diagnosis, .. } => Some(diagnosis),
Self::MissingMigrator => None,
}
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[non_exhaustive]
pub enum PostgresOperation {
EnsureDatabase,
Connect,
Migrate,
MigrationLock,
ResetSchema,
}
impl PostgresOperation {
#[must_use]
pub const fn as_str(self) -> &'static str {
match self {
Self::EnsureDatabase => "ensure_database",
Self::Connect => "connect",
Self::Migrate => "migrate",
Self::MigrationLock => "migration_lock",
Self::ResetSchema => "reset_schema",
}
}
}
impl std::fmt::Display for PostgresOperation {
fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
formatter.write_str(self.as_str())
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[non_exhaustive]
pub enum PostgresDiagnosticKind {
InvalidConfiguration,
DatabaseMissing,
AuthenticationFailed,
PermissionDenied,
ConnectionUnavailable,
TooManyConnections,
MigrationSourceInvalid,
MigrationMissing,
MigrationChecksumMismatch,
MigrationDirty,
MigrationVersionConflict,
MigrationExecutionFailed,
MigrationLockUnavailable,
OperationTimeout,
Unknown,
}
impl PostgresDiagnosticKind {
#[must_use]
pub const fn as_str(self) -> &'static str {
match self {
Self::InvalidConfiguration => "invalid_configuration",
Self::DatabaseMissing => "database_missing",
Self::AuthenticationFailed => "authentication_failed",
Self::PermissionDenied => "permission_denied",
Self::ConnectionUnavailable => "connection_unavailable",
Self::TooManyConnections => "too_many_connections",
Self::MigrationSourceInvalid => "migration_source_invalid",
Self::MigrationMissing => "migration_missing",
Self::MigrationChecksumMismatch => "migration_checksum_mismatch",
Self::MigrationDirty => "migration_dirty",
Self::MigrationVersionConflict => "migration_version_conflict",
Self::MigrationExecutionFailed => "migration_execution_failed",
Self::MigrationLockUnavailable => "migration_lock_unavailable",
Self::OperationTimeout => "operation_timeout",
Self::Unknown => "unknown",
}
}
}
impl From<PostgresDiagnosticKind> for DiagnosticKind {
fn from(value: PostgresDiagnosticKind) -> Self {
match value {
PostgresDiagnosticKind::InvalidConfiguration => Self::InvalidConfiguration,
PostgresDiagnosticKind::DatabaseMissing | PostgresDiagnosticKind::MigrationMissing => {
Self::ResourceMissing
}
PostgresDiagnosticKind::AuthenticationFailed => Self::AuthenticationFailed,
PostgresDiagnosticKind::PermissionDenied => Self::PermissionDenied,
PostgresDiagnosticKind::ConnectionUnavailable
| PostgresDiagnosticKind::MigrationLockUnavailable
| PostgresDiagnosticKind::OperationTimeout => Self::Unavailable,
PostgresDiagnosticKind::TooManyConnections => Self::CapacityExhausted,
PostgresDiagnosticKind::MigrationChecksumMismatch
| PostgresDiagnosticKind::MigrationDirty
| PostgresDiagnosticKind::MigrationVersionConflict => Self::StateMismatch,
PostgresDiagnosticKind::MigrationSourceInvalid
| PostgresDiagnosticKind::MigrationExecutionFailed => Self::ExecutionFailed,
PostgresDiagnosticKind::Unknown => Self::Unknown,
}
}
}
impl std::fmt::Display for PostgresDiagnosticKind {
fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
formatter.write_str(self.as_str())
}
}
#[derive(Clone, PartialEq, Eq)]
#[non_exhaustive]
pub struct PostgresDiagnostic {
operation: PostgresOperation,
database: Option<String>,
kind: PostgresDiagnosticKind,
message: String,
hint: String,
retryable: bool,
}
impl fmt::Debug for PostgresDiagnostic {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
formatter
.debug_struct("PostgresDiagnostic")
.field("operation", &self.operation)
.field("database", &self.database)
.field("kind", &self.kind)
.field("message", &"[REDACTED]")
.field("hint", &"[REDACTED]")
.field("retryable", &self.retryable)
.finish()
}
}
impl PostgresDiagnostic {
#[must_use]
pub fn new(
operation: PostgresOperation,
database: Option<String>,
kind: PostgresDiagnosticKind,
message: impl Into<String>,
hint: impl Into<String>,
retryable: bool,
) -> Self {
Self {
operation,
database,
kind,
message: message.into(),
hint: hint.into(),
retryable,
}
}
#[must_use]
pub const fn operation(&self) -> PostgresOperation {
self.operation
}
#[must_use]
pub fn database(&self) -> Option<&str> {
self.database.as_deref()
}
#[must_use]
pub const fn kind(&self) -> PostgresDiagnosticKind {
self.kind
}
#[must_use]
pub fn message(&self) -> &str {
&self.message
}
#[must_use]
pub fn hint(&self) -> &str {
&self.hint
}
#[must_use]
pub const fn retryable(&self) -> bool {
self.retryable
}
#[must_use]
pub fn to_diagnostic(&self) -> Diagnostic {
self.clone().into()
}
}
impl std::fmt::Display for PostgresDiagnostic {
fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
write!(formatter, "{} during {}", self.kind, self.operation)?;
if let Some(database) = &self.database {
write!(formatter, " for database '{database}'")?;
}
write!(formatter, ": {}", self.message)?;
if !self.hint.is_empty() {
write!(formatter, "; hint: {}", self.hint)?;
}
Ok(())
}
}
impl From<PostgresDiagnostic> for Diagnostic {
fn from(value: PostgresDiagnostic) -> Self {
let mut diagnostic = Self::new(
"postgres",
value.operation.as_str(),
DiagnosticKind::from(value.kind),
value.message,
)
.with_retryable(value.retryable);
if let Some(database) = value.database {
diagnostic = diagnostic.with_resource(database);
}
if !value.hint.is_empty() {
diagnostic = diagnostic.with_remediation(value.hint);
}
diagnostic
}
}
impl From<&PostgresDiagnostic> for Diagnostic {
fn from(value: &PostgresDiagnostic) -> Self {
value.to_diagnostic()
}
}
#[must_use]
pub fn diagnose_sqlx_error(
operation: PostgresOperation,
database_url: &str,
error: &sqlx::Error,
) -> PostgresDiagnostic {
let database = database_name(database_url);
let (kind, message, hint, retryable) = match error {
sqlx::Error::Database(error) => classify_database_error(error.as_ref()),
sqlx::Error::Configuration(_) => (
PostgresDiagnosticKind::InvalidConfiguration,
"PostgreSQL connection configuration is invalid",
"verify database_url syntax and SQLx PostgreSQL connection options",
false,
),
sqlx::Error::Io(error) => {
let (kind, hint, retryable) = classify_io_error(error.kind());
(
kind,
"PostgreSQL network connection failed",
hint,
retryable,
)
}
sqlx::Error::PoolTimedOut => (
PostgresDiagnosticKind::TooManyConnections,
"timed out while acquiring a PostgreSQL connection",
"increase acquire_timeout, reduce load or increase PostgreSQL/pool capacity",
true,
),
sqlx::Error::PoolClosed => (
PostgresDiagnosticKind::ConnectionUnavailable,
"PostgreSQL pool is closed",
"check application shutdown and pool ownership",
false,
),
sqlx::Error::Tls(_) => (
PostgresDiagnosticKind::ConnectionUnavailable,
"PostgreSQL TLS negotiation failed",
"check PostgreSQL TLS mode, server certificate and trusted CA configuration",
false,
),
_ => (
PostgresDiagnosticKind::Unknown,
"PostgreSQL operation failed with an unclassified error",
"inspect PostgreSQL and application logs for the underlying SQLx error",
false,
),
};
PostgresDiagnostic::new(operation, database, kind, message, hint, retryable)
}
fn classify_database_error(
error: &dyn sqlx::error::DatabaseError,
) -> (PostgresDiagnosticKind, &'static str, &'static str, bool) {
let code = error.code();
match code.as_deref() {
Some("3D000") => (
PostgresDiagnosticKind::DatabaseMissing,
"PostgreSQL database does not exist",
"create the database first or enable create_on_startup",
false,
),
Some("28P01" | "28000") => (
PostgresDiagnosticKind::AuthenticationFailed,
"PostgreSQL authentication failed",
"check the PostgreSQL username, password and pg_hba.conf authentication rules",
false,
),
Some("42501") => (
PostgresDiagnosticKind::PermissionDenied,
"PostgreSQL operation was denied",
"grant the configured PostgreSQL role permission for this operation",
false,
),
Some("53300" | "53400") => (
PostgresDiagnosticKind::TooManyConnections,
"PostgreSQL connection capacity is exhausted",
"reduce pool size or increase PostgreSQL connection limits",
true,
),
Some("57P01" | "57P02" | "57P03") => (
PostgresDiagnosticKind::ConnectionUnavailable,
"PostgreSQL is shutting down, recovering or not ready for connections",
"wait for PostgreSQL to become ready and retry the operation",
true,
),
Some(code) if code.starts_with("08") => (
PostgresDiagnosticKind::ConnectionUnavailable,
"PostgreSQL connection was interrupted",
"check PostgreSQL availability, host, port and network policy",
true,
),
_ => (
PostgresDiagnosticKind::Unknown,
"PostgreSQL returned an unclassified database error",
"inspect the PostgreSQL SQLSTATE and server logs",
false,
),
}
}
fn classify_io_error(kind: std::io::ErrorKind) -> (PostgresDiagnosticKind, &'static str, bool) {
match kind {
std::io::ErrorKind::ConnectionRefused => (
PostgresDiagnosticKind::ConnectionUnavailable,
"start PostgreSQL or check the configured host and port",
true,
),
std::io::ErrorKind::TimedOut => (
PostgresDiagnosticKind::ConnectionUnavailable,
"check network latency, firewall rules and PostgreSQL readiness",
true,
),
std::io::ErrorKind::PermissionDenied => (
PostgresDiagnosticKind::PermissionDenied,
"check local socket permissions or network policy",
false,
),
_ => (
PostgresDiagnosticKind::ConnectionUnavailable,
"check PostgreSQL availability and network connectivity",
true,
),
}
}
#[must_use]
pub fn diagnose_pool_error(
operation: PostgresOperation,
database_url: &str,
error: &PostgresPoolError,
) -> PostgresDiagnostic {
match error {
PostgresPoolError::Sqlx(source) => diagnose_sqlx_error(operation, database_url, source),
}
}
#[must_use]
pub fn diagnose_migration_lock_timeout(
database_url: &str,
timeout: Duration,
) -> PostgresDiagnostic {
PostgresDiagnostic::new(
PostgresOperation::MigrationLock,
database_name(database_url),
PostgresDiagnosticKind::MigrationLockUnavailable,
format!(
"PostgreSQL schema-maintenance lock was unavailable for {} ms",
timeout.as_millis()
),
"wait for active schema maintenance to finish or choose a longer migration_lock_timeout",
true,
)
}
#[must_use]
pub fn diagnose_operation_timeout(
operation: PostgresOperation,
database_url: &str,
timeout: Duration,
) -> PostgresDiagnostic {
PostgresDiagnostic::new(
operation,
database_name(database_url),
PostgresDiagnosticKind::OperationTimeout,
format!(
"PostgreSQL {operation} operation exceeded its {} ms deadline",
timeout.as_millis()
),
"inspect database load and the operation before increasing its configured timeout",
true,
)
}
#[must_use]
pub fn diagnose_migration_error(database_url: &str, error: &MigrateError) -> PostgresDiagnostic {
let database = database_name(database_url);
match error {
MigrateError::Execute(source) => {
let diagnosis = diagnose_sqlx_error(PostgresOperation::Migrate, database_url, source);
if !matches!(diagnosis.kind(), PostgresDiagnosticKind::Unknown) {
return diagnosis;
}
}
MigrateError::ExecuteMigration(source, version) => {
let diagnosis = diagnose_sqlx_error(PostgresOperation::Migrate, database_url, source);
if !matches!(diagnosis.kind(), PostgresDiagnosticKind::Unknown) {
return migration_execution_diagnosis_with_version(diagnosis, *version);
}
}
_ => {}
}
match MigrationFailureKind::from_error(error) {
MigrationFailureKind::Source => PostgresDiagnostic::new(
PostgresOperation::Migrate,
database,
PostgresDiagnosticKind::MigrationSourceInvalid,
"failed to load PostgreSQL migration sources",
"verify that migration files are packaged and readable",
false,
),
MigrationFailureKind::VersionMissing { version }
| MigrationFailureKind::VersionNotPresent { version } => PostgresDiagnostic::new(
PostgresOperation::Migrate,
database,
PostgresDiagnosticKind::MigrationMissing,
format!("migration version {version} is missing from resolved migrations"),
"restore the migration file or reset the database after confirming the target",
false,
),
MigrationFailureKind::VersionMismatch { version } => PostgresDiagnostic::new(
PostgresOperation::Migrate,
database,
PostgresDiagnosticKind::MigrationChecksumMismatch,
format!("migration version {version} checksum differs from the applied migration"),
"do not edit applied migrations; create a follow-up migration or reset only in development",
false,
),
MigrationFailureKind::Dirty { version } => PostgresDiagnostic::new(
PostgresOperation::Migrate,
database,
PostgresDiagnosticKind::MigrationDirty,
format!("migration version {version} is marked dirty"),
"inspect the failed migration, repair database state, then clear the dirty marker deliberately",
false,
),
MigrationFailureKind::VersionTooOld { version, latest } => PostgresDiagnostic::new(
PostgresOperation::Migrate,
database,
PostgresDiagnosticKind::MigrationVersionConflict,
format!("migration version {version} is older than latest applied version {latest}"),
"ensure migration files are ordered and the deployed binary matches the database state",
false,
),
MigrationFailureKind::VersionTooNew { version, latest } => PostgresDiagnostic::new(
PostgresOperation::Migrate,
database,
PostgresDiagnosticKind::MigrationVersionConflict,
format!("migration version {version} is newer than latest resolved version {latest}"),
"deploy a binary that contains all applied migrations or restore the missing migrations",
false,
),
MigrationFailureKind::Execute | MigrationFailureKind::ExecuteMigration { .. } => {
PostgresDiagnostic::new(
PostgresOperation::Migrate,
database,
PostgresDiagnosticKind::MigrationExecutionFailed,
"PostgreSQL migration execution failed",
"inspect the failing SQL statement and PostgreSQL server logs",
false,
)
}
MigrationFailureKind::Unsupported | MigrationFailureKind::Unknown => {
PostgresDiagnostic::new(
PostgresOperation::Migrate,
database,
PostgresDiagnosticKind::Unknown,
"PostgreSQL migration failed with an unclassified error",
"inspect SQLx migration state and PostgreSQL logs",
false,
)
}
}
}
fn migration_execution_diagnosis_with_version(
diagnosis: PostgresDiagnostic,
version: i64,
) -> PostgresDiagnostic {
PostgresDiagnostic::new(
PostgresOperation::Migrate,
diagnosis.database,
diagnosis.kind,
format!("migration version {version} failed: {}", diagnosis.message),
diagnosis.hint,
diagnosis.retryable,
)
}