use std::{
borrow::Cow,
fmt,
future::Future,
str::FromStr,
time::{Duration, Instant},
};
use serde::{Deserialize, Serialize};
use sqlx::{
PgPool, Postgres, Transaction,
migrate::{MigrateDatabase, MigrateError, Migrator},
pool::PoolConnection,
postgres::{PgConnectOptions, PgPoolOptions},
};
use thiserror::Error;
use crate::{
config::{ConfigIssueCollector, ConfigValidationError, SettingsAdapter, ValidateSettings},
result::{ClassifyError, Diagnostic, DiagnosticKind, ErrorCode, ErrorDescriptor, ErrorKind},
};
const SYSTEM_DATABASES: &[&str] = &["postgres", "template0", "template1"];
#[derive(Debug, Clone, Copy)]
#[non_exhaustive]
pub struct PostgresPoolConfig {
max_connections: u32,
min_connections: u32,
acquire_timeout: Duration,
idle_timeout: Option<Duration>,
max_lifetime: Option<Duration>,
test_before_acquire: bool,
}
impl Default for PostgresPoolConfig {
fn default() -> Self {
Self {
max_connections: 10,
min_connections: 0,
acquire_timeout: Duration::from_secs(5),
idle_timeout: Some(Duration::from_secs(10 * 60)),
max_lifetime: Some(Duration::from_secs(30 * 60)),
test_before_acquire: true,
}
}
}
impl PostgresPoolConfig {
#[must_use]
pub const fn max_connections(&self) -> u32 {
self.max_connections
}
#[must_use]
pub const fn min_connections(&self) -> u32 {
self.min_connections
}
#[must_use]
pub const fn acquire_timeout(&self) -> Duration {
self.acquire_timeout
}
#[must_use]
pub const fn idle_timeout(&self) -> Option<Duration> {
self.idle_timeout
}
#[must_use]
pub const fn max_lifetime(&self) -> Option<Duration> {
self.max_lifetime
}
#[must_use]
pub const fn test_before_acquire(&self) -> bool {
self.test_before_acquire
}
#[must_use]
pub const fn with_max_connections(mut self, max_connections: u32) -> Self {
self.max_connections = max_connections;
self
}
#[must_use]
pub const fn with_min_connections(mut self, min_connections: u32) -> Self {
self.min_connections = min_connections;
self
}
#[must_use]
pub const fn with_acquire_timeout(mut self, acquire_timeout: Duration) -> Self {
self.acquire_timeout = acquire_timeout;
self
}
#[must_use]
pub const fn with_idle_timeout(mut self, idle_timeout: Option<Duration>) -> Self {
self.idle_timeout = idle_timeout;
self
}
#[must_use]
pub const fn with_max_lifetime(mut self, max_lifetime: Option<Duration>) -> Self {
self.max_lifetime = max_lifetime;
self
}
#[must_use]
pub const fn with_test_before_acquire(mut self, test_before_acquire: bool) -> Self {
self.test_before_acquire = test_before_acquire;
self
}
pub fn validate(self) -> Result<Self, PostgresPoolError> {
if self.max_connections == 0 {
return Err(PostgresPoolError::InvalidMaxConnections);
}
if self.acquire_timeout.is_zero() {
return Err(PostgresPoolError::InvalidAcquireTimeout);
}
if self.min_connections > self.max_connections {
return Err(PostgresPoolError::InvalidMinConnections {
min: self.min_connections,
max: self.max_connections,
});
}
Ok(self)
}
}
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
#[non_exhaustive]
pub struct PostgresPoolSettings {
#[serde(default = "default_max_connections")]
pub max_connections: u32,
#[serde(default)]
pub min_connections: u32,
#[serde(
default = "default_acquire_timeout",
with = "crate::config::human_duration"
)]
pub acquire_timeout: Duration,
#[serde(
default = "default_idle_timeout",
with = "crate::config::human_duration::option"
)]
pub idle_timeout: Option<Duration>,
#[serde(
default = "default_max_lifetime",
with = "crate::config::human_duration::option"
)]
pub max_lifetime: Option<Duration>,
#[serde(default = "default_true")]
pub test_before_acquire: bool,
}
impl Default for PostgresPoolSettings {
fn default() -> Self {
Self::from(PostgresPoolConfig::default())
}
}
impl From<PostgresPoolConfig> for PostgresPoolSettings {
fn from(value: PostgresPoolConfig) -> Self {
Self {
max_connections: value.max_connections,
min_connections: value.min_connections,
acquire_timeout: value.acquire_timeout,
idle_timeout: value.idle_timeout,
max_lifetime: value.max_lifetime,
test_before_acquire: value.test_before_acquire,
}
}
}
impl TryFrom<PostgresPoolSettings> for PostgresPoolConfig {
type Error = PostgresPoolError;
fn try_from(value: PostgresPoolSettings) -> Result<Self, Self::Error> {
Self::try_from(&value)
}
}
impl TryFrom<&PostgresPoolSettings> for PostgresPoolConfig {
type Error = PostgresPoolError;
fn try_from(value: &PostgresPoolSettings) -> Result<Self, Self::Error> {
Self::default()
.with_max_connections(value.max_connections)
.with_min_connections(value.min_connections)
.with_acquire_timeout(value.acquire_timeout)
.with_idle_timeout(value.idle_timeout)
.with_max_lifetime(value.max_lifetime)
.with_test_before_acquire(value.test_before_acquire)
.validate()
}
}
impl PostgresPoolSettings {
#[must_use]
pub const fn with_max_connections(mut self, max_connections: u32) -> Self {
self.max_connections = max_connections;
self
}
#[must_use]
pub const fn with_min_connections(mut self, min_connections: u32) -> Self {
self.min_connections = min_connections;
self
}
#[must_use]
pub const fn with_acquire_timeout(mut self, acquire_timeout: Duration) -> Self {
self.acquire_timeout = acquire_timeout;
self
}
#[must_use]
pub const fn with_idle_timeout(mut self, idle_timeout: Option<Duration>) -> Self {
self.idle_timeout = idle_timeout;
self
}
#[must_use]
pub const fn with_max_lifetime(mut self, max_lifetime: Option<Duration>) -> Self {
self.max_lifetime = max_lifetime;
self
}
#[must_use]
pub const fn with_test_before_acquire(mut self, test_before_acquire: bool) -> Self {
self.test_before_acquire = test_before_acquire;
self
}
pub fn into_config(self) -> Result<PostgresPoolConfig, PostgresPoolError> {
PostgresPoolConfig::try_from(self)
}
pub fn validate_at(&self, path: &str) -> Result<(), ConfigValidationError> {
let mut issues = ConfigIssueCollector::new();
issues.require(
self.max_connections > 0,
format!("{path}.max_connections"),
"must be greater than zero",
);
issues.require(
!self.acquire_timeout.is_zero(),
format!("{path}.acquire_timeout"),
"must be greater than zero",
);
issues.require(
self.min_connections <= self.max_connections,
format!("{path}.min_connections"),
"must be less than or equal to max_connections",
);
issues.into_result()
}
}
impl SettingsAdapter<PostgresPoolConfig> for PostgresPoolSettings {
type Error = PostgresPoolError;
fn adapt(&self) -> Result<PostgresPoolConfig, Self::Error> {
PostgresPoolConfig::try_from(self)
}
}
impl ValidateSettings for PostgresPoolSettings {
fn validate_settings(&self) -> Result<(), ConfigValidationError> {
self.validate_at("postgres.pool")
}
}
#[derive(Clone)]
#[non_exhaustive]
pub struct PostgresBootstrapConfig {
database_url: String,
pool_config: PostgresPoolConfig,
create_on_startup: bool,
migrate_on_startup: bool,
startup_retry: PostgresStartupRetryConfig,
migration_lock_key: Option<i64>,
}
impl fmt::Debug for PostgresBootstrapConfig {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
formatter
.debug_struct("PostgresBootstrapConfig")
.field("database_url", &"[REDACTED]")
.field("pool_config", &self.pool_config)
.field("create_on_startup", &self.create_on_startup)
.field("migrate_on_startup", &self.migrate_on_startup)
.field("startup_retry", &self.startup_retry)
.field("migration_lock_key", &self.migration_lock_key)
.finish()
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[non_exhaustive]
pub struct PostgresStartupRetryConfig {
max_attempts: u32,
initial_delay: Duration,
max_delay: Duration,
}
impl Default for PostgresStartupRetryConfig {
fn default() -> Self {
Self {
max_attempts: 1,
initial_delay: Duration::from_millis(250),
max_delay: Duration::from_secs(5),
}
}
}
impl PostgresStartupRetryConfig {
#[must_use]
pub const fn new(max_attempts: u32, initial_delay: Duration, max_delay: Duration) -> Self {
Self {
max_attempts,
initial_delay,
max_delay,
}
}
#[must_use]
pub const fn disabled() -> Self {
Self {
max_attempts: 1,
initial_delay: Duration::from_millis(250),
max_delay: Duration::from_secs(5),
}
}
#[must_use]
pub const fn max_attempts(&self) -> u32 {
self.max_attempts
}
#[must_use]
pub const fn initial_delay(&self) -> Duration {
self.initial_delay
}
#[must_use]
pub const fn max_delay(&self) -> Duration {
self.max_delay
}
pub fn validate(self) -> Result<Self, PostgresBootstrapError> {
if self.max_attempts == 0 {
return Err(PostgresBootstrapError::InvalidStartupRetry);
}
if self.max_attempts > 1 && self.initial_delay.is_zero() {
return Err(PostgresBootstrapError::InvalidStartupRetry);
}
if self.max_delay < self.initial_delay {
return Err(PostgresBootstrapError::InvalidStartupRetry);
}
Ok(self)
}
}
#[derive(Clone, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
#[non_exhaustive]
pub struct PostgresBootstrapSettings {
pub database_url: String,
#[serde(default)]
pub pool: PostgresPoolSettings,
#[serde(default)]
pub create_on_startup: bool,
#[serde(default = "default_true")]
pub migrate_on_startup: bool,
#[serde(default)]
pub startup_retry: PostgresStartupRetrySettings,
#[serde(default = "default_migration_lock_key")]
pub migration_lock_key: Option<i64>,
}
impl fmt::Debug for PostgresBootstrapSettings {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
formatter
.debug_struct("PostgresBootstrapSettings")
.field("database_url", &"[REDACTED]")
.field("pool", &self.pool)
.field("create_on_startup", &self.create_on_startup)
.field("migrate_on_startup", &self.migrate_on_startup)
.field("startup_retry", &self.startup_retry)
.field("migration_lock_key", &self.migration_lock_key)
.finish()
}
}
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
#[non_exhaustive]
pub struct PostgresStartupRetrySettings {
#[serde(default = "default_startup_retry_attempts")]
pub max_attempts: u32,
#[serde(
default = "default_startup_retry_initial_delay",
with = "crate::config::human_duration"
)]
pub initial_delay: Duration,
#[serde(
default = "default_startup_retry_max_delay",
with = "crate::config::human_duration"
)]
pub max_delay: Duration,
}
impl Default for PostgresStartupRetrySettings {
fn default() -> Self {
Self::from(PostgresStartupRetryConfig::default())
}
}
impl From<PostgresStartupRetryConfig> for PostgresStartupRetrySettings {
fn from(value: PostgresStartupRetryConfig) -> Self {
Self {
max_attempts: value.max_attempts,
initial_delay: value.initial_delay,
max_delay: value.max_delay,
}
}
}
impl TryFrom<PostgresStartupRetrySettings> for PostgresStartupRetryConfig {
type Error = PostgresBootstrapError;
fn try_from(value: PostgresStartupRetrySettings) -> Result<Self, Self::Error> {
Self::try_from(&value)
}
}
impl TryFrom<&PostgresStartupRetrySettings> for PostgresStartupRetryConfig {
type Error = PostgresBootstrapError;
fn try_from(value: &PostgresStartupRetrySettings) -> Result<Self, Self::Error> {
PostgresStartupRetryConfig::new(value.max_attempts, value.initial_delay, value.max_delay)
.validate()
}
}
impl PostgresStartupRetrySettings {
#[must_use]
pub const fn with_max_attempts(mut self, max_attempts: u32) -> Self {
self.max_attempts = max_attempts;
self
}
#[must_use]
pub const fn with_initial_delay(mut self, initial_delay: Duration) -> Self {
self.initial_delay = initial_delay;
self
}
#[must_use]
pub const fn with_max_delay(mut self, max_delay: Duration) -> Self {
self.max_delay = max_delay;
self
}
pub fn into_config(self) -> Result<PostgresStartupRetryConfig, PostgresBootstrapError> {
PostgresStartupRetryConfig::try_from(self)
}
pub fn validate_at(&self, path: &str) -> Result<(), ConfigValidationError> {
let mut issues = ConfigIssueCollector::new();
issues.require(
self.max_attempts > 0,
format!("{path}.max_attempts"),
"must be greater than zero",
);
issues.require(
self.max_attempts <= 1 || !self.initial_delay.is_zero(),
format!("{path}.initial_delay"),
"must be greater than zero when max_attempts is greater than one",
);
issues.require(
self.max_delay >= self.initial_delay,
format!("{path}.max_delay"),
"must be greater than or equal to initial_delay",
);
issues.into_result()
}
}
impl SettingsAdapter<PostgresStartupRetryConfig> for PostgresStartupRetrySettings {
type Error = PostgresBootstrapError;
fn adapt(&self) -> Result<PostgresStartupRetryConfig, Self::Error> {
PostgresStartupRetryConfig::try_from(self)
}
}
impl ValidateSettings for PostgresStartupRetrySettings {
fn validate_settings(&self) -> Result<(), ConfigValidationError> {
self.validate_at("postgres.startup_retry")
}
}
impl PostgresBootstrapSettings {
#[must_use]
pub fn new(database_url: impl Into<String>) -> Self {
Self {
database_url: database_url.into(),
pool: PostgresPoolSettings::default(),
create_on_startup: false,
migrate_on_startup: true,
startup_retry: PostgresStartupRetrySettings::default(),
migration_lock_key: default_migration_lock_key(),
}
}
#[must_use]
pub fn with_database_url(mut self, database_url: impl Into<String>) -> Self {
self.database_url = database_url.into();
self
}
#[must_use]
pub fn with_pool(mut self, pool: PostgresPoolSettings) -> Self {
self.pool = pool;
self
}
#[must_use]
pub const fn with_create_on_startup(mut self, create_on_startup: bool) -> Self {
self.create_on_startup = create_on_startup;
self
}
#[must_use]
pub const fn with_migrate_on_startup(mut self, migrate_on_startup: bool) -> Self {
self.migrate_on_startup = migrate_on_startup;
self
}
#[must_use]
pub const fn with_startup_retry(mut self, startup_retry: PostgresStartupRetrySettings) -> Self {
self.startup_retry = startup_retry;
self
}
#[must_use]
pub const fn with_migration_advisory_lock(mut self, key: Option<i64>) -> Self {
self.migration_lock_key = key;
self
}
pub fn into_config(self) -> Result<PostgresBootstrapConfig, PostgresBootstrapError> {
PostgresBootstrapConfig::try_from(self)
}
pub fn validate_at(&self, path: &str) -> Result<(), ConfigValidationError> {
let mut issues = ConfigIssueCollector::new();
issues.require_non_empty(format!("{path}.database_url"), &self.database_url);
issues.extend_result(self.pool.validate_at(&format!("{path}.pool")));
issues.extend_result(
self.startup_retry
.validate_at(&format!("{path}.startup_retry")),
);
issues.into_result()
}
}
impl From<PostgresBootstrapConfig> for PostgresBootstrapSettings {
fn from(value: PostgresBootstrapConfig) -> Self {
Self {
database_url: value.database_url,
pool: PostgresPoolSettings::from(value.pool_config),
create_on_startup: value.create_on_startup,
migrate_on_startup: value.migrate_on_startup,
startup_retry: PostgresStartupRetrySettings::from(value.startup_retry),
migration_lock_key: value.migration_lock_key,
}
}
}
impl TryFrom<PostgresBootstrapSettings> for PostgresBootstrapConfig {
type Error = PostgresBootstrapError;
fn try_from(value: PostgresBootstrapSettings) -> Result<Self, Self::Error> {
PostgresBootstrapConfig::try_from(&value)
}
}
impl TryFrom<&PostgresBootstrapSettings> for PostgresBootstrapConfig {
type Error = PostgresBootstrapError;
fn try_from(value: &PostgresBootstrapSettings) -> Result<Self, Self::Error> {
let pool_config = PostgresPoolConfig::try_from(&value.pool)
.map_err(PostgresBootstrapError::InvalidPoolConfig)?;
let startup_retry = PostgresStartupRetryConfig::try_from(&value.startup_retry)?;
PostgresBootstrapConfig::new(value.database_url.clone())
.with_pool_config(pool_config)
.with_create_on_startup(value.create_on_startup)
.with_migrate_on_startup(value.migrate_on_startup)
.with_startup_retry(startup_retry)
.with_migration_advisory_lock(value.migration_lock_key)
.validate()
}
}
impl SettingsAdapter<PostgresBootstrapConfig> for PostgresBootstrapSettings {
type Error = PostgresBootstrapError;
fn adapt(&self) -> Result<PostgresBootstrapConfig, Self::Error> {
PostgresBootstrapConfig::try_from(self)
}
}
impl ValidateSettings for PostgresBootstrapSettings {
fn validate_settings(&self) -> Result<(), ConfigValidationError> {
self.validate_at("postgres")
}
}
impl PostgresBootstrapConfig {
#[must_use]
pub fn new(database_url: impl Into<String>) -> Self {
Self {
database_url: database_url.into(),
pool_config: PostgresPoolConfig::default(),
create_on_startup: false,
migrate_on_startup: true,
startup_retry: PostgresStartupRetryConfig::default(),
migration_lock_key: Some(advisory_lock_key("footing", "migrations")),
}
}
#[must_use]
pub fn database_url(&self) -> &str {
&self.database_url
}
#[must_use]
pub const fn pool_config(&self) -> PostgresPoolConfig {
self.pool_config
}
#[must_use]
pub const fn create_on_startup(&self) -> bool {
self.create_on_startup
}
#[must_use]
pub const fn migrate_on_startup(&self) -> bool {
self.migrate_on_startup
}
#[must_use]
pub const fn startup_retry(&self) -> PostgresStartupRetryConfig {
self.startup_retry
}
#[must_use]
pub const fn migration_lock_key(&self) -> Option<i64> {
self.migration_lock_key
}
#[must_use]
pub fn with_database_url(mut self, database_url: impl Into<String>) -> Self {
self.database_url = database_url.into();
self
}
#[must_use]
pub const fn with_pool_config(mut self, pool_config: PostgresPoolConfig) -> Self {
self.pool_config = pool_config;
self
}
#[must_use]
pub const fn with_create_on_startup(mut self, create_on_startup: bool) -> Self {
self.create_on_startup = create_on_startup;
self
}
#[must_use]
pub const fn with_migrate_on_startup(mut self, migrate_on_startup: bool) -> Self {
self.migrate_on_startup = migrate_on_startup;
self
}
#[must_use]
pub const fn with_startup_retry(mut self, startup_retry: PostgresStartupRetryConfig) -> Self {
self.startup_retry = startup_retry;
self
}
#[must_use]
pub const fn with_migration_advisory_lock(mut self, key: Option<i64>) -> Self {
self.migration_lock_key = key;
self
}
pub fn validate(self) -> Result<Self, PostgresBootstrapError> {
if self.database_url.trim().is_empty() {
return Err(PostgresBootstrapError::EmptyDatabaseUrl);
}
self.pool_config
.validate()
.map_err(PostgresBootstrapError::InvalidPoolConfig)?;
self.startup_retry.validate()?;
Ok(self)
}
}
#[derive(Error)]
#[non_exhaustive]
pub enum PostgresPoolError {
#[error("max_connections must be greater than zero")]
InvalidMaxConnections,
#[error("acquire_timeout must be greater than zero")]
InvalidAcquireTimeout,
#[error("min_connections {min} must be less than or equal to max_connections {max}")]
InvalidMinConnections {
#[doc = "The configured lower bound."]
min: u32,
#[doc = "The configured upper bound."]
max: u32,
},
#[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 {
match self {
Self::InvalidMaxConnections
| Self::InvalidAcquireTimeout
| Self::InvalidMinConnections { .. } => ErrorKind::Validation,
Self::Sqlx(_) => ErrorKind::Dependency,
}
}
fn error_code(&self) -> Cow<'static, str> {
Cow::Borrowed(match self {
Self::InvalidMaxConnections => "invalid_postgres_max_connections",
Self::InvalidAcquireTimeout => "invalid_postgres_acquire_timeout",
Self::InvalidMinConnections { .. } => "invalid_postgres_min_connections",
Self::Sqlx(_) => "postgres_unavailable",
})
}
}
#[derive(Error)]
#[non_exhaustive]
pub enum PostgresBootstrapError {
#[error("database_url must not be empty")]
EmptyDatabaseUrl,
#[error("invalid PostgreSQL pool configuration")]
InvalidPoolConfig(#[source] PostgresPoolError),
#[error("invalid PostgreSQL startup retry configuration")]
InvalidStartupRetry,
#[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,
kind: MigrationFailureKind,
#[source]
source: Box<MigrateError>,
},
#[error("failed to acquire PostgreSQL migration advisory lock: {diagnosis}")]
MigrationLock {
diagnosis: PostgresDiagnostic,
#[source]
source: Box<sqlx::Error>,
},
}
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::EmptyDatabaseUrl
| Self::InvalidPoolConfig(_)
| Self::InvalidStartupRetry
| Self::MissingMigrator => ErrorKind::Validation,
Self::EnsureDatabase { .. }
| Self::Connect { .. }
| Self::Migration { .. }
| Self::MigrationLock { .. } => ErrorKind::Dependency,
}
}
fn error_code(&self) -> Cow<'static, str> {
Cow::Borrowed(match self {
Self::EmptyDatabaseUrl => "postgres_database_url_empty",
Self::InvalidPoolConfig(_) => "invalid_postgres_pool_config",
Self::InvalidStartupRetry => "invalid_postgres_startup_retry",
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",
})
}
fn error_descriptor(&self) -> ErrorDescriptor {
let code = ErrorCode::try_new(self.error_code().into_owned())
.unwrap_or_else(|_| ErrorCode::unknown());
ErrorDescriptor::new(self.error_kind(), 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, .. } => Some(diagnosis),
Self::EmptyDatabaseUrl
| Self::InvalidPoolConfig(_)
| Self::InvalidStartupRetry
| Self::MissingMigrator => None,
}
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[non_exhaustive]
pub enum MigrationFailureKind {
Execute,
ExecuteMigration {
#[doc = "The affected version."]
version: i64,
},
Source,
VersionMissing {
#[doc = "The affected version."]
version: i64,
},
VersionMismatch {
#[doc = "The affected version."]
version: i64,
},
VersionNotPresent {
#[doc = "The affected version."]
version: i64,
},
VersionTooOld {
#[doc = "The affected version."]
version: i64,
#[doc = "The latest supported version."]
latest: i64,
},
VersionTooNew {
#[doc = "The affected version."]
version: i64,
#[doc = "The latest supported version."]
latest: i64,
},
Dirty {
#[doc = "The affected version."]
version: i64,
},
Unsupported,
Unknown,
}
impl MigrationFailureKind {
#[must_use]
pub fn from_error(error: &MigrateError) -> Self {
match error {
MigrateError::Execute(_) => Self::Execute,
MigrateError::ExecuteMigration(_, version) => {
Self::ExecuteMigration { version: *version }
}
MigrateError::Source(_) => Self::Source,
MigrateError::VersionMissing(version) => Self::VersionMissing { version: *version },
MigrateError::VersionMismatch(version) => Self::VersionMismatch { version: *version },
MigrateError::VersionNotPresent(version) => {
Self::VersionNotPresent { version: *version }
}
MigrateError::VersionTooOld(version, latest) => Self::VersionTooOld {
version: *version,
latest: *latest,
},
MigrateError::VersionTooNew(version, latest) => Self::VersionTooNew {
version: *version,
latest: *latest,
},
MigrateError::ForceNotSupported => Self::Unsupported,
#[allow(deprecated)]
MigrateError::InvalidMixReversibleAndSimple => Self::Unsupported,
MigrateError::Dirty(version) => Self::Dirty { version: *version },
_ => Self::Unknown,
}
}
}
#[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,
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::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 => 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 {
let diagnostic = Diagnostic::dependency(
"postgres",
self.operation.as_str(),
DiagnosticKind::from(self.kind),
self.message.clone(),
)
.with_retryable(self.retryable);
let diagnostic = if let Some(database) = &self.database {
diagnostic.with_resource(database.clone())
} else {
diagnostic
};
if self.hint.is_empty() {
diagnostic
} else {
diagnostic.with_remediation(self.hint.clone())
}
}
}
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 {
value.to_diagnostic()
}
}
impl From<&PostgresDiagnostic> for Diagnostic {
fn from(value: &PostgresDiagnostic) -> Self {
value.to_diagnostic()
}
}
#[derive(Clone)]
#[non_exhaustive]
pub struct PostgresResetConfig {
database_url: String,
pool_config: PostgresPoolConfig,
create_on_startup: bool,
migrate_after_reset: bool,
}
impl fmt::Debug for PostgresResetConfig {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
formatter
.debug_struct("PostgresResetConfig")
.field("database_url", &"[REDACTED]")
.field("pool_config", &self.pool_config)
.field("create_on_startup", &self.create_on_startup)
.field("migrate_after_reset", &self.migrate_after_reset)
.finish()
}
}
impl PostgresResetConfig {
#[must_use]
pub fn new(database_url: impl Into<String>) -> Self {
Self {
database_url: database_url.into(),
pool_config: PostgresPoolConfig::default().with_max_connections(1),
create_on_startup: false,
migrate_after_reset: false,
}
}
#[must_use]
pub fn database_url(&self) -> &str {
&self.database_url
}
#[must_use]
pub const fn migrate_after_reset(&self) -> bool {
self.migrate_after_reset
}
#[must_use]
pub const fn with_pool_config(mut self, pool_config: PostgresPoolConfig) -> Self {
self.pool_config = pool_config;
self
}
#[must_use]
pub const fn with_create_on_startup(mut self, create_on_startup: bool) -> Self {
self.create_on_startup = create_on_startup;
self
}
#[must_use]
pub const fn with_migrate_after_reset(mut self, migrate_after_reset: bool) -> Self {
self.migrate_after_reset = migrate_after_reset;
self
}
pub fn validate(self) -> Result<Self, PostgresResetError> {
if self.database_url.trim().is_empty() {
return Err(PostgresResetError::EmptyDatabaseUrl);
}
self.pool_config
.validate()
.map_err(PostgresResetError::InvalidPoolConfig)?;
let Some(name) = database_name(&self.database_url) else {
return Err(PostgresResetError::MissingDatabaseName);
};
if SYSTEM_DATABASES.contains(&name.as_str()) {
return Err(PostgresResetError::SystemDatabase { database: name });
}
Ok(self)
}
}
#[derive(Debug, Clone, PartialEq, Eq)]
#[non_exhaustive]
pub struct PostgresResetOutcome {
database_name: String,
migrated: bool,
}
impl PostgresResetOutcome {
#[must_use]
pub fn database_name(&self) -> &str {
&self.database_name
}
#[must_use]
pub const fn migrated(&self) -> bool {
self.migrated
}
}
#[derive(Error)]
#[non_exhaustive]
pub enum PostgresResetError {
#[error("database_url must not be empty")]
EmptyDatabaseUrl,
#[error("invalid PostgreSQL pool configuration")]
InvalidPoolConfig(#[source] PostgresPoolError),
#[error("failed to determine target database name from database_url")]
MissingDatabaseName,
#[error("refusing to reset system database '{database}'")]
SystemDatabase {
#[doc = "The affected database name."]
database: String,
},
#[error("migrate_after_reset requires a SQLx migrator")]
MissingMigrator,
#[error("failed to ensure PostgreSQL database exists before reset: {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 reset PostgreSQL public schema: {diagnosis}")]
ResetSchema {
diagnosis: PostgresDiagnostic,
#[source]
source: Box<sqlx::Error>,
},
#[error("failed to run PostgreSQL migrations after reset: {diagnosis}")]
Migration {
diagnosis: PostgresDiagnostic,
kind: MigrationFailureKind,
#[source]
source: Box<MigrateError>,
},
}
impl fmt::Debug for PostgresResetError {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
formatter
.debug_struct("PostgresResetError")
.field("error_code", &self.error_code())
.field("diagnosis", &self.diagnosis())
.field("source", &"[REDACTED]")
.finish()
}
}
impl ClassifyError for PostgresResetError {
fn error_kind(&self) -> ErrorKind {
match self {
Self::EmptyDatabaseUrl
| Self::InvalidPoolConfig(_)
| Self::MissingDatabaseName
| Self::SystemDatabase { .. }
| Self::MissingMigrator => ErrorKind::Validation,
Self::EnsureDatabase { .. }
| Self::Connect { .. }
| Self::ResetSchema { .. }
| Self::Migration { .. } => ErrorKind::Dependency,
}
}
fn error_code(&self) -> Cow<'static, str> {
Cow::Borrowed(match self {
Self::EmptyDatabaseUrl => "postgres_database_url_empty",
Self::InvalidPoolConfig(_) => "invalid_postgres_pool_config",
Self::MissingDatabaseName => "postgres_database_name_missing",
Self::SystemDatabase { .. } => "postgres_system_database_reset_refused",
Self::MissingMigrator => "postgres_migrator_required",
Self::EnsureDatabase { .. } => "postgres_ensure_database_failed",
Self::Connect { .. } => "postgres_connect_failed",
Self::ResetSchema { .. } => "postgres_reset_schema_failed",
Self::Migration { .. } => "postgres_migration_failed",
})
}
}
impl PostgresResetError {
#[must_use]
pub const fn diagnosis(&self) -> Option<&PostgresDiagnostic> {
match self {
Self::EnsureDatabase { diagnosis, .. }
| Self::Connect { diagnosis, .. }
| Self::ResetSchema { diagnosis, .. }
| Self::Migration { diagnosis, .. } => Some(diagnosis),
Self::EmptyDatabaseUrl
| Self::InvalidPoolConfig(_)
| Self::MissingDatabaseName
| Self::SystemDatabase { .. }
| Self::MissingMigrator => None,
}
}
}
pub async fn connect_pool(
database_url: &str,
config: PostgresPoolConfig,
) -> Result<PgPool, PostgresPoolError> {
Ok(pool_options(config)?.connect(database_url).await?)
}
pub fn connect_lazy_pool(
database_url: &str,
config: PostgresPoolConfig,
) -> Result<PgPool, PostgresPoolError> {
Ok(pool_options(config)?.connect_lazy(database_url)?)
}
pub fn pool_options(config: PostgresPoolConfig) -> Result<PgPoolOptions, PostgresPoolError> {
let config = config.validate()?;
let mut options = PgPoolOptions::new()
.max_connections(config.max_connections)
.min_connections(config.min_connections)
.acquire_timeout(config.acquire_timeout)
.test_before_acquire(config.test_before_acquire);
if let Some(idle_timeout) = config.idle_timeout {
options = options.idle_timeout(idle_timeout);
}
if let Some(max_lifetime) = config.max_lifetime {
options = options.max_lifetime(max_lifetime);
}
Ok(options)
}
#[must_use]
pub fn diagnose_sqlx_error(
operation: PostgresOperation,
database_url: &str,
error: &sqlx::Error,
) -> PostgresDiagnostic {
let database = database_name(database_url);
if let sqlx::Error::Database(database_error) = error {
let code = database_error.code();
return match code.as_deref() {
Some("3D000") => PostgresDiagnostic::new(
operation,
database,
PostgresDiagnosticKind::DatabaseMissing,
database_error.message(),
"create the database first or enable create_on_startup",
false,
),
Some("28P01" | "28000") => PostgresDiagnostic::new(
operation,
database,
PostgresDiagnosticKind::AuthenticationFailed,
database_error.message(),
"check the PostgreSQL username, password and pg_hba.conf authentication rules",
false,
),
Some("42501") => PostgresDiagnostic::new(
operation,
database,
PostgresDiagnosticKind::PermissionDenied,
database_error.message(),
"grant the configured PostgreSQL role permission for this operation",
false,
),
Some("53300" | "53400") => PostgresDiagnostic::new(
operation,
database,
PostgresDiagnosticKind::TooManyConnections,
database_error.message(),
"reduce pool size or increase PostgreSQL connection limits",
true,
),
Some(code) if code.starts_with("08") => PostgresDiagnostic::new(
operation,
database,
PostgresDiagnosticKind::ConnectionUnavailable,
database_error.message(),
"check PostgreSQL availability, host, port and network policy",
true,
),
_ => PostgresDiagnostic::new(
operation,
database,
PostgresDiagnosticKind::Unknown,
database_error.message(),
"inspect the PostgreSQL SQLSTATE and server logs",
false,
),
};
}
match error {
sqlx::Error::Configuration(_) => PostgresDiagnostic::new(
operation,
database,
PostgresDiagnosticKind::InvalidConfiguration,
"PostgreSQL connection configuration is invalid",
"verify database_url syntax and SQLx PostgreSQL connection options",
false,
),
sqlx::Error::Io(source) => {
let (kind, hint, retryable) = match source.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,
),
};
PostgresDiagnostic::new(
operation,
database,
kind,
"PostgreSQL network connection failed",
hint,
retryable,
)
}
sqlx::Error::PoolTimedOut => PostgresDiagnostic::new(
operation,
database,
PostgresDiagnosticKind::TooManyConnections,
"timed out while acquiring a PostgreSQL connection",
"increase acquire_timeout, reduce load or increase PostgreSQL/pool capacity",
true,
),
sqlx::Error::PoolClosed => PostgresDiagnostic::new(
operation,
database,
PostgresDiagnosticKind::ConnectionUnavailable,
"PostgreSQL pool is closed",
"check application shutdown and pool ownership",
false,
),
sqlx::Error::Tls(_) => PostgresDiagnostic::new(
operation,
database,
PostgresDiagnosticKind::ConnectionUnavailable,
"PostgreSQL TLS negotiation failed",
"check PostgreSQL TLS mode, server certificate and trusted CA configuration",
false,
),
_ => PostgresDiagnostic::new(
operation,
database,
PostgresDiagnosticKind::Unknown,
"PostgreSQL operation failed with an unclassified error",
"inspect PostgreSQL and application logs for the underlying SQLx error",
false,
),
}
}
#[must_use]
pub fn diagnose_pool_error(
operation: PostgresOperation,
database_url: &str,
error: &PostgresPoolError,
) -> PostgresDiagnostic {
match error {
PostgresPoolError::InvalidMaxConnections
| PostgresPoolError::InvalidAcquireTimeout
| PostgresPoolError::InvalidMinConnections { .. } => PostgresDiagnostic::new(
operation,
database_name(database_url),
PostgresDiagnosticKind::InvalidConfiguration,
error.to_string(),
"fix the PostgreSQL pool settings before startup",
false,
),
PostgresPoolError::Sqlx(source) => diagnose_sqlx_error(operation, database_url, source),
}
}
#[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} was applied but 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,
)
}
pub async fn bootstrap_database(
config: PostgresBootstrapConfig,
migrator: Option<&Migrator>,
) -> Result<PgPool, PostgresBootstrapError> {
let config = config.validate()?;
let migrator = if config.migrate_on_startup {
Some(migrator.ok_or(PostgresBootstrapError::MissingMigrator)?)
} else {
None
};
if config.create_on_startup {
tracing::info!(
database = %display_database_name(config.database_url()),
"ensuring PostgreSQL database exists"
);
ensure_database_exists_with_retry(config.database_url(), config.startup_retry)
.await
.map_err(|source| PostgresBootstrapError::EnsureDatabase {
diagnosis: diagnose_sqlx_error(
PostgresOperation::EnsureDatabase,
config.database_url(),
&source,
),
source: Box::new(source),
})?;
}
let pool = connect_pool_with_retry(
config.database_url(),
config.pool_config,
config.startup_retry,
)
.await
.map_err(|source| PostgresBootstrapError::Connect {
diagnosis: diagnose_pool_error(PostgresOperation::Connect, config.database_url(), &source),
source: Box::new(source),
})?;
if let Some(migrator) = migrator {
tracing::info!(
database = %display_database_name(config.database_url()),
"running PostgreSQL database migrations"
);
if let Some(key) = config.migration_lock_key {
if let Err(error) = run_migrations_with_advisory_lock(&pool, migrator, key).await {
return Err(bootstrap_migration_run_error(config.database_url(), error));
}
} else {
run_migrations(&pool, migrator).await.map_err(|source| {
PostgresBootstrapError::Migration {
diagnosis: diagnose_migration_error(config.database_url(), &source),
kind: MigrationFailureKind::from_error(&source),
source: Box::new(source),
}
})?;
}
}
Ok(pool)
}
pub async fn reset_database(
config: PostgresResetConfig,
migrator: Option<&Migrator>,
) -> Result<PostgresResetOutcome, PostgresResetError> {
let config = config.validate()?;
let migrator = if config.migrate_after_reset {
Some(migrator.ok_or(PostgresResetError::MissingMigrator)?)
} else {
None
};
let database_name =
database_name(config.database_url()).ok_or(PostgresResetError::MissingDatabaseName)?;
if config.create_on_startup {
tracing::info!(database = %database_name, "ensuring PostgreSQL database exists before reset");
ensure_database_exists(config.database_url())
.await
.map_err(|source| PostgresResetError::EnsureDatabase {
diagnosis: diagnose_sqlx_error(
PostgresOperation::EnsureDatabase,
config.database_url(),
&source,
),
source: Box::new(source),
})?;
}
let pool = connect_pool(config.database_url(), config.pool_config)
.await
.map_err(|source| PostgresResetError::Connect {
diagnosis: diagnose_pool_error(
PostgresOperation::Connect,
config.database_url(),
&source,
),
source: Box::new(source),
})?;
sqlx::query("DROP SCHEMA IF EXISTS public CASCADE")
.execute(&pool)
.await
.map_err(|source| PostgresResetError::ResetSchema {
diagnosis: diagnose_sqlx_error(
PostgresOperation::ResetSchema,
config.database_url(),
&source,
),
source: Box::new(source),
})?;
sqlx::query("CREATE SCHEMA public")
.execute(&pool)
.await
.map_err(|source| PostgresResetError::ResetSchema {
diagnosis: diagnose_sqlx_error(
PostgresOperation::ResetSchema,
config.database_url(),
&source,
),
source: Box::new(source),
})?;
sqlx::query("GRANT ALL ON SCHEMA public TO CURRENT_USER")
.execute(&pool)
.await
.map_err(|source| PostgresResetError::ResetSchema {
diagnosis: diagnose_sqlx_error(
PostgresOperation::ResetSchema,
config.database_url(),
&source,
),
source: Box::new(source),
})?;
if let Some(migrator) = migrator {
run_migrations(&pool, migrator)
.await
.map_err(|source| PostgresResetError::Migration {
diagnosis: diagnose_migration_error(config.database_url(), &source),
kind: MigrationFailureKind::from_error(&source),
source: Box::new(source),
})?;
}
Ok(PostgresResetOutcome {
database_name,
migrated: config.migrate_after_reset,
})
}
pub async fn ensure_database_exists(database_url: &str) -> Result<(), sqlx::Error> {
if Postgres::database_exists(database_url).await? {
return Ok(());
}
match Postgres::create_database(database_url).await {
Ok(()) => Ok(()),
Err(error) => match Postgres::database_exists(database_url).await {
Ok(true) => Ok(()),
Ok(false) | Err(_) => Err(error),
},
}
}
pub async fn ensure_database_exists_with_retry(
database_url: &str,
retry: PostgresStartupRetryConfig,
) -> Result<(), sqlx::Error> {
retry_async(retry, || ensure_database_exists(database_url)).await
}
pub async fn run_migrations(pool: &PgPool, migrator: &Migrator) -> Result<(), MigrateError> {
migrator.run(pool).await
}
#[derive(Error)]
#[non_exhaustive]
pub enum PostgresMigrationRunError {
#[error("failed to acquire PostgreSQL migration advisory lock")]
Lock(#[source] sqlx::Error),
#[error("failed to run PostgreSQL migrations")]
Migration {
kind: MigrationFailureKind,
#[source]
source: Box<MigrateError>,
},
}
impl fmt::Debug for PostgresMigrationRunError {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
formatter
.debug_struct("PostgresMigrationRunError")
.field("error_code", &self.error_code())
.field("source", &"[REDACTED]")
.finish()
}
}
impl ClassifyError for PostgresMigrationRunError {
fn error_kind(&self) -> ErrorKind {
ErrorKind::Dependency
}
fn error_code(&self) -> Cow<'static, str> {
Cow::Borrowed(match self {
Self::Lock(_) => "postgres_migration_lock_failed",
Self::Migration { .. } => "postgres_migration_failed",
})
}
fn error_descriptor(&self) -> ErrorDescriptor {
let code = ErrorCode::try_new(self.error_code().into_owned())
.unwrap_or_else(|_| ErrorCode::unknown());
ErrorDescriptor::new(self.error_kind(), code, self.to_string())
.with_retryable(matches!(self, Self::Lock(_)))
}
}
impl From<PostgresMigrationRunError> for PostgresBootstrapError {
fn from(error: PostgresMigrationRunError) -> Self {
bootstrap_migration_run_error("", error)
}
}
fn bootstrap_migration_run_error(
database_url: &str,
error: PostgresMigrationRunError,
) -> PostgresBootstrapError {
match error {
PostgresMigrationRunError::Lock(source) => PostgresBootstrapError::MigrationLock {
diagnosis: diagnose_sqlx_error(PostgresOperation::MigrationLock, database_url, &source),
source: Box::new(source),
},
PostgresMigrationRunError::Migration { kind, source } => {
PostgresBootstrapError::Migration {
diagnosis: diagnose_migration_error(database_url, &source),
kind,
source,
}
}
}
}
pub async fn run_migrations_with_advisory_lock(
pool: &PgPool,
migrator: &Migrator,
lock_key: i64,
) -> Result<(), PostgresMigrationRunError> {
let mut connection = pool
.acquire()
.await
.map_err(PostgresMigrationRunError::Lock)?;
let mut lock_guard = SessionAdvisoryLockGuard::new(&mut connection);
sqlx::query("SELECT pg_advisory_lock($1)")
.bind(lock_key)
.execute(&mut **lock_guard.connection())
.await
.map_err(PostgresMigrationRunError::Lock)?;
let migration_result = migrator.run(&mut **lock_guard.connection()).await;
let unlock_result = sqlx::query("SELECT pg_advisory_unlock($1)")
.bind(lock_key)
.execute(&mut **lock_guard.connection())
.await;
if unlock_result.is_ok() {
lock_guard.disarm();
}
if let Err(source) = migration_result {
return Err(PostgresMigrationRunError::Migration {
kind: MigrationFailureKind::from_error(&source),
source: Box::new(source),
});
}
unlock_result.map_err(PostgresMigrationRunError::Lock)?;
Ok(())
}
struct SessionAdvisoryLockGuard<'a> {
connection: &'a mut PoolConnection<Postgres>,
armed: bool,
}
impl<'a> SessionAdvisoryLockGuard<'a> {
fn new(connection: &'a mut PoolConnection<Postgres>) -> Self {
Self {
connection,
armed: true,
}
}
fn connection(&mut self) -> &mut PoolConnection<Postgres> {
self.connection
}
fn disarm(&mut self) {
self.armed = false;
}
}
impl Drop for SessionAdvisoryLockGuard<'_> {
fn drop(&mut self) {
if self.armed {
self.connection.close_on_drop();
}
}
}
pub async fn ping_pool(pool: &PgPool) -> Result<(), sqlx::Error> {
sqlx::query("SELECT 1").execute(pool).await?;
Ok(())
}
pub async fn connect_pool_with_retry(
database_url: &str,
config: PostgresPoolConfig,
retry: PostgresStartupRetryConfig,
) -> Result<PgPool, PostgresPoolError> {
let config = config.validate()?;
retry_async(retry, || connect_pool(database_url, config)).await
}
pub async fn check_pool_health(pool: &PgPool) -> PostgresHealth {
let started = Instant::now();
match ping_pool(pool).await {
Ok(()) => PostgresHealth {
status: PostgresHealthStatus::Ready,
latency: started.elapsed(),
},
Err(_) => PostgresHealth {
status: PostgresHealthStatus::Unavailable,
latency: started.elapsed(),
},
}
}
const POSTGRES_HEALTH_ERROR: &str = "database health check failed";
#[must_use]
pub fn database_name(database_url: &str) -> Option<String> {
PgConnectOptions::from_str(database_url)
.ok()
.and_then(|options| options.get_database().map(ToOwned::to_owned))
.filter(|database| !database.trim().is_empty())
}
#[must_use]
pub fn redact_database_url(database_url: &str) -> String {
let Some((scheme, rest)) = database_url.split_once("://") else {
return "<invalid-postgres-url>".to_owned();
};
let authority_end = rest.find(['/', '?', '#']).unwrap_or(rest.len());
let (authority, suffix) = rest.split_at(authority_end);
let redacted_authority = match authority.rsplit_once('@') {
Some((userinfo, host)) => {
let redacted_userinfo = userinfo
.split_once(':')
.map(|(user, _)| format!("{user}:****"))
.unwrap_or_else(|| "****".to_owned());
format!("{redacted_userinfo}@{host}")
}
None => authority.to_owned(),
};
format!(
"{scheme}://{redacted_authority}{}",
redact_database_url_suffix(suffix)
)
}
fn redact_database_url_suffix(suffix: &str) -> String {
let (without_fragment, fragment) = suffix
.split_once('#')
.map_or((suffix, None), |(value, _)| (value, Some("#****")));
let Some((path, query)) = without_fragment.split_once('?') else {
return format!("{without_fragment}{}", fragment.unwrap_or_default());
};
let redacted_query = query
.split('&')
.map(|parameter| {
parameter
.split_once('=')
.map_or_else(|| parameter.to_owned(), |(key, _)| format!("{key}=****"))
})
.collect::<Vec<_>>()
.join("&");
format!("{path}?{redacted_query}{}", fragment.unwrap_or_default())
}
fn display_database_name(database_url: &str) -> Cow<'_, str> {
database_name(database_url)
.map(Cow::Owned)
.unwrap_or(Cow::Borrowed("<unknown>"))
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[non_exhaustive]
pub enum PostgresHealthStatus {
Ready,
Unavailable,
}
#[derive(Clone, PartialEq, Eq)]
#[non_exhaustive]
pub struct PostgresHealth {
status: PostgresHealthStatus,
latency: Duration,
}
impl fmt::Debug for PostgresHealth {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
formatter
.debug_struct("PostgresHealth")
.field("status", &self.status)
.field("latency", &self.latency)
.field("has_error", &!self.ready())
.finish()
}
}
impl PostgresHealth {
#[must_use]
pub const fn status(&self) -> PostgresHealthStatus {
self.status
}
#[must_use]
pub const fn latency(&self) -> Duration {
self.latency
}
#[must_use]
pub fn error(&self) -> Option<&str> {
(!self.ready()).then_some(POSTGRES_HEALTH_ERROR)
}
#[must_use]
pub const fn ready(&self) -> bool {
matches!(self.status, PostgresHealthStatus::Ready)
}
}
fn default_max_connections() -> u32 {
PostgresPoolConfig::default().max_connections
}
fn default_acquire_timeout() -> Duration {
PostgresPoolConfig::default().acquire_timeout
}
fn default_idle_timeout() -> Option<Duration> {
PostgresPoolConfig::default().idle_timeout
}
fn default_max_lifetime() -> Option<Duration> {
PostgresPoolConfig::default().max_lifetime
}
fn default_true() -> bool {
true
}
fn default_startup_retry_attempts() -> u32 {
PostgresStartupRetryConfig::default().max_attempts
}
fn default_startup_retry_initial_delay() -> Duration {
PostgresStartupRetryConfig::default().initial_delay
}
fn default_startup_retry_max_delay() -> Duration {
PostgresStartupRetryConfig::default().max_delay
}
fn default_migration_lock_key() -> Option<i64> {
PostgresBootstrapConfig::new("").migration_lock_key
}
async fn retry_async<T, E, F, Fut>(
retry: PostgresStartupRetryConfig,
mut operation: F,
) -> Result<T, E>
where
F: FnMut() -> Fut,
Fut: Future<Output = Result<T, E>>,
E: std::fmt::Display,
{
let max_attempts = retry.max_attempts.max(1);
let mut attempt = 1_u32;
let mut delay = if retry.initial_delay.is_zero() {
PostgresStartupRetryConfig::default().initial_delay
} else {
retry.initial_delay
};
let max_delay = retry.max_delay.max(delay);
loop {
match operation().await {
Ok(value) => return Ok(value),
Err(error) if attempt >= max_attempts => return Err(error),
Err(_) => {
tracing::warn!(
attempt,
max_attempts,
retry_after_ms = delay.as_millis(),
"PostgreSQL startup operation failed; retrying"
);
tokio::time::sleep(delay).await;
attempt = attempt.saturating_add(1);
delay = delay.checked_mul(2).unwrap_or(Duration::MAX).min(max_delay);
}
}
}
}
pub type PostgresTransaction<'a> = Transaction<'a, Postgres>;
pub async fn begin_transaction(pool: &PgPool) -> Result<PostgresTransaction<'_>, sqlx::Error> {
pool.begin().await
}
pub async fn commit_transaction(transaction: PostgresTransaction<'_>) -> Result<(), sqlx::Error> {
transaction.commit().await
}
pub async fn rollback_transaction(transaction: PostgresTransaction<'_>) -> Result<(), sqlx::Error> {
transaction.rollback().await
}
#[must_use]
pub fn advisory_lock_key(namespace: &str, name: &str) -> i64 {
const FNV_OFFSET: u64 = 0xcbf2_9ce4_8422_2325;
const FNV_PRIME: u64 = 0x0000_0100_0000_01b3;
let mut hash = FNV_OFFSET;
for byte in namespace
.trim()
.bytes()
.chain([0])
.chain(name.trim().bytes())
{
hash ^= u64::from(byte);
hash = hash.wrapping_mul(FNV_PRIME);
}
i64::from_ne_bytes(hash.to_ne_bytes())
}
pub async fn acquire_advisory_transaction_lock(
transaction: &mut PostgresTransaction<'_>,
key: i64,
) -> Result<(), sqlx::Error> {
sqlx::query("SELECT pg_advisory_xact_lock($1)")
.bind(key)
.execute(&mut **transaction)
.await?;
Ok(())
}
pub async fn acquire_shared_advisory_transaction_lock(
transaction: &mut PostgresTransaction<'_>,
key: i64,
) -> Result<(), sqlx::Error> {
sqlx::query("SELECT pg_advisory_xact_lock_shared($1)")
.bind(key)
.execute(&mut **transaction)
.await?;
Ok(())
}
pub async fn try_acquire_advisory_transaction_lock(
transaction: &mut PostgresTransaction<'_>,
key: i64,
) -> Result<bool, sqlx::Error> {
sqlx::query_scalar("SELECT pg_try_advisory_xact_lock($1)")
.bind(key)
.fetch_one(&mut **transaction)
.await
}
#[cfg(test)]
mod tests {
use crate::config::{SettingsAdapter, ValidateSettings};
use crate::result::DiagnosticKind;
use super::{
MigrationFailureKind, POSTGRES_HEALTH_ERROR, PostgresBootstrapConfig,
PostgresBootstrapError, PostgresBootstrapSettings, PostgresDiagnosticKind, PostgresHealth,
PostgresHealthStatus, PostgresOperation, PostgresPoolConfig, PostgresPoolError,
PostgresPoolSettings, PostgresResetConfig, PostgresResetError, PostgresStartupRetryConfig,
advisory_lock_key, database_name, diagnose_migration_error, diagnose_sqlx_error,
redact_database_url,
};
#[test]
fn rejects_zero_max_connections() {
let result = PostgresPoolConfig::default()
.with_max_connections(0)
.validate();
assert!(matches!(
result,
Err(PostgresPoolError::InvalidMaxConnections)
));
}
#[test]
fn rejects_min_connections_above_max() {
let result = PostgresPoolConfig::default()
.with_max_connections(2)
.with_min_connections(3)
.validate();
assert!(matches!(
result,
Err(PostgresPoolError::InvalidMinConnections { min: 3, max: 2 })
));
}
#[test]
fn rejects_zero_acquire_timeout() {
let result = PostgresPoolConfig::default()
.with_acquire_timeout(std::time::Duration::ZERO)
.validate();
assert!(matches!(
result,
Err(PostgresPoolError::InvalidAcquireTimeout)
));
}
#[test]
fn exposes_pool_config_values() {
let config = PostgresPoolConfig::default()
.with_max_connections(20)
.with_min_connections(2)
.with_test_before_acquire(false);
assert_eq!(config.max_connections(), 20);
assert_eq!(config.min_connections(), 2);
assert!(!config.test_before_acquire());
}
#[test]
fn validates_bootstrap_config_before_touching_database() {
let result = PostgresBootstrapConfig::new(" ")
.validate()
.expect_err("empty URL should be rejected");
assert!(matches!(result, PostgresBootstrapError::EmptyDatabaseUrl));
}
#[tokio::test]
async fn bootstrap_requires_migrator_when_migration_is_enabled() {
let result = super::bootstrap_database(
PostgresBootstrapConfig::new("postgres://postgres:postgres@localhost/app")
.with_migrate_on_startup(true),
None,
)
.await
.expect_err("missing migrator should be rejected before connecting");
assert!(matches!(result, PostgresBootstrapError::MissingMigrator));
}
#[test]
fn parses_database_name_without_exposing_credentials() {
assert_eq!(
database_name("postgres://app:secret@localhost:5432/app_dev").as_deref(),
Some("app_dev")
);
assert_eq!(database_name("not-a-url"), None);
}
#[test]
fn postgres_configuration_debug_redacts_database_urls() {
let database_url =
"postgres://private-user:private-password@localhost/app?sslpassword=private-query";
let bootstrap = PostgresBootstrapConfig::new(database_url);
let settings = PostgresBootstrapSettings::new(database_url);
let reset = PostgresResetConfig::new(database_url);
let output = format!("{bootstrap:?} {settings:?} {reset:?}");
assert!(output.contains("[REDACTED]"));
for sensitive in [
database_url,
"private-user",
"private-password",
"private-query",
] {
assert!(!output.contains(sensitive));
}
}
#[test]
fn postgres_error_formatting_redacts_urls_and_source_details() {
let database_url =
"postgres://private-user:private-password@localhost/app?sslpassword=private-query";
let source_detail = "private-driver-error-detail";
let sqlx_error = sqlx::Error::Configuration(Box::new(std::io::Error::other(source_detail)));
let diagnosis = diagnose_sqlx_error(PostgresOperation::Connect, database_url, &sqlx_error);
let diagnosis_output = format!("{diagnosis} {diagnosis:?}");
let pool_error = PostgresPoolError::Sqlx(sqlx_error);
let pool_output = format!("{pool_error} {pool_error:?}");
let bootstrap_error = PostgresBootstrapError::Connect {
diagnosis,
source: Box::new(pool_error),
};
let output =
format!("{diagnosis_output} {pool_output} {bootstrap_error} {bootstrap_error:?}");
assert!(output.contains("[REDACTED]"));
for sensitive in [
database_url,
"private-user",
"private-password",
"private-query",
source_detail,
] {
assert!(!output.contains(sensitive));
}
}
#[test]
fn postgres_health_exposes_only_a_stable_redacted_error() {
let health = PostgresHealth {
status: PostgresHealthStatus::Unavailable,
latency: std::time::Duration::from_millis(10),
};
assert_eq!(health.error(), Some("database health check failed"));
let output = format!("{health:?}");
assert!(output.contains("has_error"));
assert!(!output.contains(POSTGRES_HEALTH_ERROR));
}
#[test]
fn postgres_settings_convert_to_runtime_config() {
let settings = PostgresBootstrapSettings {
database_url: "postgres://app:secret@localhost/app".to_owned(),
pool: PostgresPoolSettings {
max_connections: 20,
..PostgresPoolSettings::default()
},
create_on_startup: true,
migrate_on_startup: false,
startup_retry: PostgresStartupRetryConfig::new(
3,
std::time::Duration::from_millis(10),
std::time::Duration::from_millis(50),
)
.into(),
migration_lock_key: Some(42),
};
let config = settings.into_config().expect("settings should convert");
assert_eq!(config.database_url(), "postgres://app:secret@localhost/app");
assert_eq!(config.pool_config().max_connections(), 20);
assert!(config.create_on_startup());
assert!(!config.migrate_on_startup());
assert_eq!(config.startup_retry().max_attempts(), 3);
assert_eq!(config.migration_lock_key(), Some(42));
}
#[test]
fn postgres_settings_adapt_and_validate_with_stable_paths() {
let settings = PostgresBootstrapSettings {
database_url: "postgres://app:secret@localhost/app".to_owned(),
pool: PostgresPoolSettings {
max_connections: 0,
..PostgresPoolSettings::default()
},
..PostgresBootstrapSettings::new("postgres://app:secret@localhost/app")
};
let validation = settings
.validate_at("database")
.expect_err("invalid settings should report config paths");
assert_eq!(
validation.issues()[0].path(),
"database.pool.max_connections"
);
let error = settings
.adapt()
.expect_err("invalid settings should not adapt");
assert!(matches!(
error,
PostgresBootstrapError::InvalidPoolConfig(PostgresPoolError::InvalidMaxConnections)
));
assert!(settings.validate_settings().is_err());
}
#[test]
fn diagnoses_migration_state_failures_for_operators() {
let missing = sqlx::migrate::MigrateError::VersionMissing(20260428000200);
let diagnosis = diagnose_migration_error("postgres://app:secret@localhost/app", &missing);
assert_eq!(diagnosis.kind(), PostgresDiagnosticKind::MigrationMissing);
assert_eq!(diagnosis.database(), Some("app"));
assert!(diagnosis.message().contains("20260428000200"));
assert!(!diagnosis.retryable());
assert_eq!(
diagnosis.to_diagnostic().kind(),
DiagnosticKind::ResourceMissing
);
let mismatch = sqlx::migrate::MigrateError::VersionMismatch(20260428000200);
assert_eq!(
MigrationFailureKind::from_error(&mismatch),
MigrationFailureKind::VersionMismatch {
version: 20260428000200
}
);
assert_eq!(
diagnose_migration_error("postgres://app:secret@localhost/app", &mismatch).kind(),
PostgresDiagnosticKind::MigrationChecksumMismatch
);
let permission = sqlx::migrate::MigrateError::Execute(sqlx::Error::Io(
std::io::Error::new(std::io::ErrorKind::PermissionDenied, "socket denied"),
));
assert_eq!(
diagnose_migration_error("postgres://app:secret@localhost/app", &permission).kind(),
PostgresDiagnosticKind::PermissionDenied
);
}
#[test]
fn reset_config_rejects_system_databases() {
let system = PostgresResetConfig::new("postgres://app:secret@localhost/postgres")
.validate()
.expect_err("system database should be rejected");
assert!(matches!(system, PostgresResetError::SystemDatabase { .. }));
}
#[test]
fn redacts_database_urls_without_losing_routing_information() {
assert_eq!(
redact_database_url("postgres://app:secret@localhost:5432/app"),
"postgres://app:****@localhost:5432/app"
);
assert_eq!(
redact_database_url(
"postgres://app:secret@localhost/app?sslmode=require&sslpassword=private-query"
),
"postgres://app:****@localhost/app?sslmode=****&sslpassword=****"
);
assert_eq!(
redact_database_url("postgres://localhost/app?password=private-query#private-fragment"),
"postgres://localhost/app?password=****#****"
);
assert_eq!(redact_database_url("not-a-url"), "<invalid-postgres-url>");
}
#[test]
fn advisory_lock_keys_are_stable_and_namespaced() {
let left = advisory_lock_key("app", "migrations");
let same = advisory_lock_key(" app ", " migrations ");
let other = advisory_lock_key("app", "workers");
assert_eq!(left, same);
assert_ne!(left, other);
}
}