use std::{
borrow::Cow,
fmt,
future::Future,
str::FromStr,
time::{Duration, Instant},
};
use sqlx::{
PgPool, Postgres, Transaction,
migrate::{MigrateDatabase, MigrateError, Migrator},
pool::PoolConnection,
postgres::{PgConnectOptions, PgPoolOptions},
};
use thiserror::Error;
use crate::{
result::{ClassifyError, ErrorDescriptor, ErrorKind},
secret::ExposeSecret,
};
use super::{
config::{PostgresBootstrapConfig, PostgresPoolConfig, PostgresStartupRetryConfig},
diagnostics::{
MigrationFailureKind, PostgresBootstrapError, PostgresOperation, PostgresPoolError,
diagnose_migration_error, diagnose_pool_error, diagnose_sqlx_error,
},
};
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)?)
}
#[must_use]
pub fn pool_options(config: PostgresPoolConfig) -> PgPoolOptions {
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);
}
options
}
pub async fn bootstrap_database(
config: PostgresBootstrapConfig,
migrator: Option<&Migrator>,
) -> Result<PgPool, PostgresBootstrapError> {
let migrator = if config.migrate_on_startup {
Some(migrator.ok_or(PostgresBootstrapError::MissingMigrator)?)
} else {
None
};
let database_url = config.database_url.expose_secret();
if config.create_on_startup {
tracing::info!(
database = %display_database_name(database_url),
"ensuring PostgreSQL database exists"
);
ensure_database_exists_with_retry(database_url, config.startup_retry)
.await
.map_err(|source| PostgresBootstrapError::EnsureDatabase {
diagnosis: diagnose_sqlx_error(
PostgresOperation::EnsureDatabase,
database_url,
&source,
),
source: Box::new(source),
})?;
}
let pool = connect_pool_with_retry(database_url, config.pool_config, config.startup_retry)
.await
.map_err(|source| PostgresBootstrapError::Connect {
diagnosis: diagnose_pool_error(PostgresOperation::Connect, database_url, &source),
source: Box::new(source),
})?;
if let Some(migrator) = migrator {
tracing::info!(
database = %display_database_name(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(database_url, error));
}
} else {
run_migrations(&pool, migrator).await.map_err(|source| {
PostgresBootstrapError::Migration {
diagnosis: diagnose_migration_error(database_url, &source),
kind: MigrationFailureKind::from_error(&source),
source: Box::new(source),
}
})?;
}
}
Ok(pool)
}
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) -> crate::result::ErrorCode {
crate::result::ErrorCode::internal(match self {
Self::Lock(_) => "postgres_migration_lock_failed",
Self::Migration { .. } => "postgres_migration_failed",
})
}
fn error_descriptor(&self) -> ErrorDescriptor {
ErrorDescriptor::new(self.error_kind(), self.error_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> {
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(),
},
}
}
pub(super) 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 {
pub(super) status: PostgresHealthStatus,
pub(super) 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)
}
}
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
}