use std::{fmt, time::Duration};
use serde::{Deserialize, Serialize};
use sqlx::{
Connection,
migrate::{MigrateError, Migrator},
};
use thiserror::Error;
use crate::{
result::{ClassifyError, ErrorDescriptor, ErrorKind},
secret::{ExposeSecret, SecretString},
settings::{SettingsIssues, SettingsValidationError},
};
use super::{
config::{
DEFAULT_POSTGRES_ADVISORY_LOCK_TIMEOUT, DEFAULT_POSTGRES_MIGRATION_TIMEOUT,
PostgresPoolConfig, PostgresPoolSettings, default_ensure_database_timeout,
},
diagnostics::{
PostgresDiagnostic, PostgresDiagnosticKind, PostgresOperation, PostgresPoolError,
diagnose_migration_error, diagnose_operation_timeout, diagnose_pool_error,
diagnose_sqlx_error,
},
identity::{connect_options, database_name},
runtime::{
SessionAdvisoryLockAcquireError, acquire_schema_maintenance_session_lock, connect_pool,
ensure_database_exists,
},
};
const SYSTEM_DATABASES: &[&str] = &["postgres", "template0", "template1"];
pub const DEFAULT_POSTGRES_RESET_SCHEMA_TIMEOUT: Duration = Duration::from_secs(60);
pub const DEFAULT_POSTGRES_RESET_MIGRATION_TIMEOUT: Duration = DEFAULT_POSTGRES_MIGRATION_TIMEOUT;
#[cfg_attr(feature = "tier", derive(tier::TierConfig))]
#[derive(Clone, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
#[non_exhaustive]
pub struct PostgresResetSettings<S = SecretString> {
#[cfg_attr(feature = "tier", tier(secret, leaf))]
pub database_url: S,
pub pool: PostgresPoolSettings,
pub create_on_startup: bool,
#[serde(
default = "default_ensure_database_timeout",
with = "crate::settings::human_duration"
)]
pub ensure_database_timeout: Duration,
pub migrate_after_reset: bool,
#[serde(
default = "default_reset_lock_timeout",
with = "crate::settings::human_duration"
)]
pub reset_lock_timeout: Duration,
#[serde(
default = "default_reset_schema_timeout",
with = "crate::settings::human_duration"
)]
pub reset_schema_timeout: Duration,
#[serde(
default = "default_post_reset_migration_timeout",
with = "crate::settings::human_duration"
)]
pub post_reset_migration_timeout: Duration,
}
impl<S> fmt::Debug for PostgresResetSettings<S> {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
formatter
.debug_struct("PostgresResetSettings")
.field("database_url", &"[REDACTED]")
.field("pool", &self.pool)
.field("create_on_startup", &self.create_on_startup)
.field("ensure_database_timeout", &self.ensure_database_timeout)
.field("migrate_after_reset", &self.migrate_after_reset)
.field("reset_lock_timeout", &self.reset_lock_timeout)
.field("reset_schema_timeout", &self.reset_schema_timeout)
.field(
"post_reset_migration_timeout",
&self.post_reset_migration_timeout,
)
.finish()
}
}
impl<S> PostgresResetSettings<S> {
#[must_use]
pub fn from_secret(database_url: S) -> Self {
Self {
database_url,
pool: PostgresPoolSettings {
max_connections: 1,
..PostgresPoolSettings::default()
},
create_on_startup: false,
ensure_database_timeout: default_ensure_database_timeout(),
migrate_after_reset: false,
reset_lock_timeout: default_reset_lock_timeout(),
reset_schema_timeout: default_reset_schema_timeout(),
post_reset_migration_timeout: default_post_reset_migration_timeout(),
}
}
#[must_use]
pub fn map_database_url<T>(self, map: impl FnOnce(S) -> T) -> PostgresResetSettings<T> {
PostgresResetSettings {
database_url: map(self.database_url),
pool: self.pool,
create_on_startup: self.create_on_startup,
ensure_database_timeout: self.ensure_database_timeout,
migrate_after_reset: self.migrate_after_reset,
reset_lock_timeout: self.reset_lock_timeout,
reset_schema_timeout: self.reset_schema_timeout,
post_reset_migration_timeout: self.post_reset_migration_timeout,
}
}
#[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, enabled: bool) -> Self {
self.create_on_startup = enabled;
self
}
#[must_use]
pub const fn with_ensure_database_timeout(mut self, timeout: Duration) -> Self {
self.ensure_database_timeout = timeout;
self
}
#[must_use]
pub const fn with_migrate_after_reset(mut self, enabled: bool) -> Self {
self.migrate_after_reset = enabled;
self
}
#[must_use]
pub const fn with_reset_lock_timeout(mut self, timeout: Duration) -> Self {
self.reset_lock_timeout = timeout;
self
}
#[must_use]
pub const fn with_reset_schema_timeout(mut self, timeout: Duration) -> Self {
self.reset_schema_timeout = timeout;
self
}
#[must_use]
pub const fn with_post_reset_migration_timeout(mut self, timeout: Duration) -> Self {
self.post_reset_migration_timeout = timeout;
self
}
pub fn build(self) -> Result<PostgresResetConfig, SettingsValidationError>
where
S: Into<SecretString>,
{
let settings: PostgresResetSettings = self.map_database_url(Into::into);
settings.validate()?;
let Some(database_name) = database_name(settings.database_url.expose_secret()) else {
return Err(SettingsValidationError::single(
"postgres.reset.database_url",
"must contain a database name",
));
};
Ok(PostgresResetConfig {
database_url: settings.database_url,
database_name,
pool_config: settings.pool.into_config(),
create_on_startup: settings.create_on_startup,
ensure_database_timeout: settings.ensure_database_timeout,
migrate_after_reset: settings.migrate_after_reset,
reset_lock_timeout: settings.reset_lock_timeout,
reset_schema_timeout: settings.reset_schema_timeout,
post_reset_migration_timeout: settings.post_reset_migration_timeout,
})
}
}
impl<S> PostgresResetSettings<S>
where
S: ExposeSecret<str>,
{
pub fn validate(&self) -> Result<(), SettingsValidationError> {
let mut issues = SettingsIssues::new();
let database_url = self.database_url.expose_secret();
issues.require_non_empty("postgres.reset.database_url", database_url);
issues.extend_result(self.pool.validate_at("postgres.reset.pool"));
match database_name(database_url) {
Some(name) => {
issues.require(
connect_options(database_url).is_ok(),
"postgres.reset.database_url",
"must be a valid PostgreSQL connection URL",
);
issues.require(
!SYSTEM_DATABASES.contains(&name.as_str()),
"postgres.reset.database_url",
"must not target a PostgreSQL system database",
);
}
None if !database_url.trim().is_empty() => issues.push(
"postgres.reset.database_url",
"must contain a database name",
),
None => {}
}
for (field, timeout) in [
("ensure_database_timeout", self.ensure_database_timeout),
("reset_lock_timeout", self.reset_lock_timeout),
("reset_schema_timeout", self.reset_schema_timeout),
(
"post_reset_migration_timeout",
self.post_reset_migration_timeout,
),
] {
issues.require(
!timeout.is_zero() && std::time::Instant::now().checked_add(timeout).is_some(),
format!("postgres.reset.{field}"),
"must be greater than zero and fit the runtime timer range",
);
}
issues.into_result()
}
}
impl PostgresResetSettings {
#[must_use]
pub fn new(database_url: impl Into<String>) -> Self {
Self::from_secret(SecretString::new(database_url))
}
}
impl From<PostgresResetConfig> for PostgresResetSettings {
fn from(value: PostgresResetConfig) -> Self {
Self {
database_url: value.database_url,
pool: PostgresPoolSettings::from(value.pool_config),
create_on_startup: value.create_on_startup,
ensure_database_timeout: value.ensure_database_timeout,
migrate_after_reset: value.migrate_after_reset,
reset_lock_timeout: value.reset_lock_timeout,
reset_schema_timeout: value.reset_schema_timeout,
post_reset_migration_timeout: value.post_reset_migration_timeout,
}
}
}
#[derive(Clone)]
#[non_exhaustive]
pub struct PostgresResetConfig {
database_url: SecretString,
database_name: String,
pool_config: PostgresPoolConfig,
create_on_startup: bool,
ensure_database_timeout: Duration,
migrate_after_reset: bool,
reset_lock_timeout: Duration,
reset_schema_timeout: Duration,
post_reset_migration_timeout: Duration,
}
impl fmt::Debug for PostgresResetConfig {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
formatter
.debug_struct("PostgresResetConfig")
.field("database_url", &"[REDACTED]")
.field("database_name", &self.database_name)
.field("pool_config", &self.pool_config)
.field("create_on_startup", &self.create_on_startup)
.field("ensure_database_timeout", &self.ensure_database_timeout)
.field("migrate_after_reset", &self.migrate_after_reset)
.field("reset_lock_timeout", &self.reset_lock_timeout)
.field("reset_schema_timeout", &self.reset_schema_timeout)
.field(
"post_reset_migration_timeout",
&self.post_reset_migration_timeout,
)
.finish()
}
}
impl PostgresResetConfig {
#[must_use]
pub const fn ensure_database_timeout(&self) -> Duration {
self.ensure_database_timeout
}
#[must_use]
pub const fn database_url(&self) -> &SecretString {
&self.database_url
}
#[must_use]
pub const fn migrate_after_reset(&self) -> bool {
self.migrate_after_reset
}
#[must_use]
pub const fn reset_lock_timeout(&self) -> Duration {
self.reset_lock_timeout
}
#[must_use]
pub const fn reset_schema_timeout(&self) -> Duration {
self.reset_schema_timeout
}
#[must_use]
pub const fn post_reset_migration_timeout(&self) -> Duration {
self.post_reset_migration_timeout
}
}
#[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("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 acquire PostgreSQL schema-maintenance lock for reset: {diagnosis}")]
ResetLock {
diagnosis: PostgresDiagnostic,
#[source]
source: Box<sqlx::Error>,
},
#[error("timed out waiting for PostgreSQL schema-maintenance lock before reset: {diagnosis}")]
ResetLockTimeout {
diagnosis: PostgresDiagnostic,
timeout: std::time::Duration,
},
#[error("failed to reset PostgreSQL public schema: {diagnosis}")]
ResetSchema {
diagnosis: PostgresDiagnostic,
#[source]
source: Box<sqlx::Error>,
},
#[error("timed out while resetting PostgreSQL public schema: {diagnosis}")]
ResetSchemaTimeout {
diagnosis: PostgresDiagnostic,
timeout: Duration,
},
#[error("failed to run PostgreSQL migrations after reset: {diagnosis}")]
Migration {
diagnosis: PostgresDiagnostic,
#[source]
source: Box<MigrateError>,
},
#[error("timed out while running PostgreSQL migrations after reset: {diagnosis}")]
MigrationTimeout {
diagnosis: PostgresDiagnostic,
timeout: Duration,
},
}
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::MissingMigrator => ErrorKind::Validation,
Self::ResetLockTimeout { .. }
| Self::ResetSchemaTimeout { .. }
| Self::MigrationTimeout { .. } => ErrorKind::Timeout,
Self::EnsureDatabase { .. }
| Self::Connect { .. }
| Self::ResetLock { .. }
| Self::ResetSchema { .. }
| Self::Migration { .. } => 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::ResetLock { .. } => "postgres_reset_lock_failed",
Self::ResetLockTimeout { .. } => "postgres_reset_lock_timeout",
Self::ResetSchema { .. } => "postgres_reset_schema_failed",
Self::ResetSchemaTimeout { .. } => "postgres_reset_schema_timeout",
Self::Migration { .. } => "postgres_migration_failed",
Self::MigrationTimeout { .. } => "postgres_reset_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 PostgresResetError {
#[must_use]
pub const fn diagnosis(&self) -> Option<&PostgresDiagnostic> {
match self {
Self::EnsureDatabase { diagnosis, .. }
| Self::Connect { diagnosis, .. }
| Self::ResetLock { diagnosis, .. }
| Self::ResetLockTimeout { diagnosis, .. }
| Self::ResetSchema { diagnosis, .. }
| Self::ResetSchemaTimeout { diagnosis, .. }
| Self::Migration { diagnosis, .. }
| Self::MigrationTimeout { diagnosis, .. } => Some(diagnosis),
Self::MissingMigrator => None,
}
}
}
pub async fn reset_database(
config: PostgresResetConfig,
migrator: Option<&Migrator>,
) -> Result<PostgresResetOutcome, PostgresResetError> {
let migrator = if config.migrate_after_reset {
Some(migrator.ok_or(PostgresResetError::MissingMigrator)?)
} else {
None
};
let database_url = config.database_url.expose_secret();
let database_name = config.database_name;
if config.create_on_startup {
tracing::info!(database = %database_name, "ensuring PostgreSQL database exists before reset");
ensure_database_exists(database_url, config.ensure_database_timeout)
.await
.map_err(|source| PostgresResetError::EnsureDatabase {
diagnosis: diagnose_sqlx_error(
PostgresOperation::EnsureDatabase,
database_url,
&source,
),
source: Box::new(source),
})?;
}
let pool = connect_pool(database_url, config.pool_config)
.await
.map_err(|source| PostgresResetError::Connect {
diagnosis: diagnose_pool_error(PostgresOperation::Connect, database_url, &source),
source: Box::new(source),
})?;
let mut reset_guard = acquire_schema_maintenance_session_lock(
&pool,
Some(&database_name),
None,
config.reset_lock_timeout,
)
.await
.map_err(|error| match error {
SessionAdvisoryLockAcquireError::Sqlx(source) => PostgresResetError::ResetLock {
diagnosis: diagnose_sqlx_error(PostgresOperation::ResetSchema, database_url, &source),
source: Box::new(source),
},
SessionAdvisoryLockAcquireError::Timeout { timeout } => {
PostgresResetError::ResetLockTimeout {
diagnosis: reset_lock_timeout_diagnosis(database_url, timeout),
timeout,
}
}
})?;
let reset_result = tokio::time::timeout(config.reset_schema_timeout, async {
let mut transaction = reset_guard.connection().begin().await?;
sqlx::query("DROP SCHEMA IF EXISTS public CASCADE")
.execute(&mut *transaction)
.await?;
sqlx::query("CREATE SCHEMA public")
.execute(&mut *transaction)
.await?;
sqlx::query("GRANT ALL ON SCHEMA public TO CURRENT_USER")
.execute(&mut *transaction)
.await?;
transaction.commit().await
})
.await;
match reset_result {
Ok(Ok(())) => {}
Ok(Err(source)) => {
return Err(PostgresResetError::ResetSchema {
diagnosis: diagnose_sqlx_error(
PostgresOperation::ResetSchema,
database_url,
&source,
),
source: Box::new(source),
});
}
Err(_) => {
return Err(PostgresResetError::ResetSchemaTimeout {
diagnosis: diagnose_operation_timeout(
PostgresOperation::ResetSchema,
database_url,
config.reset_schema_timeout,
),
timeout: config.reset_schema_timeout,
});
}
}
if let Some(migrator) = migrator {
match tokio::time::timeout(
config.post_reset_migration_timeout,
migrator.run(&mut **reset_guard.connection()),
)
.await
{
Ok(Ok(())) => {}
Ok(Err(source)) => {
return Err(PostgresResetError::Migration {
diagnosis: diagnose_migration_error(database_url, &source),
source: Box::new(source),
});
}
Err(_) => {
return Err(PostgresResetError::MigrationTimeout {
diagnosis: diagnose_operation_timeout(
PostgresOperation::Migrate,
database_url,
config.post_reset_migration_timeout,
),
timeout: config.post_reset_migration_timeout,
});
}
}
}
reset_guard
.release_with_timeout(config.reset_lock_timeout)
.await
.map_err(|source| PostgresResetError::ResetLock {
diagnosis: diagnose_sqlx_error(PostgresOperation::ResetSchema, database_url, &source),
source: Box::new(source),
})?;
Ok(PostgresResetOutcome {
database_name,
migrated: config.migrate_after_reset,
})
}
fn reset_lock_timeout_diagnosis(database_url: &str, timeout: Duration) -> PostgresDiagnostic {
PostgresDiagnostic::new(
PostgresOperation::ResetSchema,
database_name(database_url),
PostgresDiagnosticKind::MigrationLockUnavailable,
format!(
"PostgreSQL reset lock was unavailable for {} ms",
timeout.as_millis()
),
"wait for active schema maintenance to finish or choose a longer reset_lock_timeout",
true,
)
}
const fn default_reset_lock_timeout() -> Duration {
DEFAULT_POSTGRES_ADVISORY_LOCK_TIMEOUT
}
const fn default_reset_schema_timeout() -> Duration {
DEFAULT_POSTGRES_RESET_SCHEMA_TIMEOUT
}
const fn default_post_reset_migration_timeout() -> Duration {
DEFAULT_POSTGRES_RESET_MIGRATION_TIMEOUT
}