migratrom 0.2.0

Declarative, self-verifying database migrations (core engine).
Documentation
//! Schema-object operation builders.
//!
//! These builders cover PostgreSQL-oriented objects beyond tables: schemas,
//! extensions, sequences, enum types/values, views, and materialized views.

use super::helpers::{check, require_capability, step};
use crate::error::Result;
use crate::sql::SqlDialect;
use crate::types::Operation;

/// Options for [`create_extension`].
#[derive(Clone, Debug, Default)]
pub struct CreateExtensionOptions {
    /// Install the extension into this schema (`CREATE EXTENSION ... WITH SCHEMA`).
    pub schema: Option<String>,
}

/// Options for [`add_enum_value`].
#[derive(Clone, Debug, Default)]
pub struct AddEnumValueOptions {
    /// Insert the new label before this existing enum value (`ADD VALUE ... BEFORE`).
    pub before: Option<String>,
}

/// Create a PostgreSQL schema.
pub fn create_schema(name: &str, dialect: &dyn SqlDialect) -> Result<Operation> {
    require_capability(dialect, dialect.capabilities().schemas, "schemas")?;
    Ok(Operation {
        id: format!("schema.{name}"),
        label: format!("Create schema \"{name}\""),
        precheck: vec![check(
            format!("ensure schema \"{name}\" does not exist"),
            dialect.schema_exists_sql(name, true),
        )],
        execute: vec![step(
            format!("create schema \"{name}\""),
            format!("CREATE SCHEMA {}", dialect.quote_ident(name)),
        )],
        postcheck: vec![check(
            format!("verify schema \"{name}\" exists"),
            dialect.schema_exists_sql(name, false),
        )],
        outside_transaction: false,
    })
}

/// Install a PostgreSQL extension (e.g. `"uuid-ossp"`, `"pgcrypto"`).
pub fn create_extension(
    name: &str,
    options: &CreateExtensionOptions,
    dialect: &dyn SqlDialect,
) -> Result<Operation> {
    require_capability(dialect, dialect.capabilities().extensions, "extensions")?;
    let with_schema = match &options.schema {
        Some(schema) => format!(" WITH SCHEMA {}", dialect.quote_ident(schema)),
        None => String::new(),
    };

    Ok(Operation {
        id: format!("extension.{name}"),
        label: format!("Create extension \"{name}\""),
        precheck: vec![check(
            format!("ensure extension \"{name}\" does not exist"),
            dialect.extension_exists_sql(name, true),
        )],
        execute: vec![step(
            format!("create extension \"{name}\""),
            format!(
                "CREATE EXTENSION {}{with_schema}",
                dialect.quote_ident(name)
            ),
        )],
        postcheck: vec![check(
            format!("verify extension \"{name}\" exists"),
            dialect.extension_exists_sql(name, false),
        )],
        outside_transaction: false,
    })
}

/// Create a standalone sequence in the given schema.
pub fn create_sequence(schema: &str, name: &str, dialect: &dyn SqlDialect) -> Result<Operation> {
    require_capability(dialect, dialect.capabilities().sequences, "sequences")?;
    Ok(Operation {
        id: format!("sequence.{name}"),
        label: format!("Create sequence \"{name}\""),
        precheck: vec![check(
            format!("ensure sequence \"{name}\" does not exist"),
            dialect.table_exists_sql(schema, name, true),
        )],
        execute: vec![step(
            format!("create sequence \"{name}\""),
            format!("CREATE SEQUENCE {}", dialect.qualified(schema, name)),
        )],
        postcheck: vec![check(
            format!("verify sequence \"{name}\" exists"),
            dialect.table_exists_sql(schema, name, false),
        )],
        outside_transaction: false,
    })
}

/// Create a PostgreSQL `ENUM` type with the given labels (order preserved).
pub fn create_type(
    schema: &str,
    name: &str,
    labels: &[String],
    dialect: &dyn SqlDialect,
) -> Result<Operation> {
    require_capability(dialect, dialect.capabilities().enum_types, "enum types")?;
    let label_list = labels
        .iter()
        .map(|l| dialect.quote_literal(l))
        .collect::<Vec<_>>()
        .join(", ");

    Ok(Operation {
        id: format!("type.{name}"),
        label: format!("Create enum type \"{name}\""),
        precheck: vec![check(
            format!("ensure type \"{name}\" does not exist"),
            dialect.enum_type_exists_sql(schema, name, true),
        )],
        execute: vec![step(
            format!("create enum type \"{name}\""),
            format!(
                "CREATE TYPE {} AS ENUM ({label_list})",
                dialect.qualified(schema, name)
            ),
        )],
        postcheck: vec![check(
            format!("verify type \"{name}\" exists"),
            dialect.enum_type_exists_sql(schema, name, false),
        )],
        outside_transaction: false,
    })
}

/// Append (or insert) a label on an existing `ENUM` type.
pub fn add_enum_value(
    schema: &str,
    type_name: &str,
    value: &str,
    options: &AddEnumValueOptions,
    dialect: &dyn SqlDialect,
) -> Result<Operation> {
    require_capability(dialect, dialect.capabilities().enum_types, "enum values")?;
    let before_clause = match &options.before {
        Some(before) => format!(" BEFORE {}", dialect.quote_literal(before)),
        None => String::new(),
    };
    let alter_sql = format!(
        "ALTER TYPE {} ADD VALUE {}{before_clause}",
        dialect.qualified(schema, type_name),
        dialect.quote_literal(value)
    );

    Ok(Operation {
        id: format!("enum.{type_name}.{value}"),
        label: format!("Add enum value \"{value}\" to type \"{type_name}\""),
        precheck: vec![
            check(
                format!("ensure enum type \"{type_name}\" exists"),
                dialect.enum_type_exists_sql(schema, type_name, false),
            ),
            check(
                format!("ensure enum value \"{value}\" does not exist on \"{type_name}\""),
                dialect.enum_label_exists_sql(schema, type_name, value, true),
            ),
        ],
        execute: vec![step(
            format!("add enum value \"{value}\" to \"{type_name}\""),
            alter_sql,
        )],
        postcheck: vec![check(
            format!("verify enum value \"{value}\" exists on \"{type_name}\""),
            dialect.enum_label_exists_sql(schema, type_name, value, false),
        )],
        outside_transaction: false,
    })
}

/// Create a regular (non-materialized) view from a `SELECT` statement.
pub fn create_view(
    schema: &str,
    name: &str,
    select_sql: &str,
    dialect: &dyn SqlDialect,
) -> Result<Operation> {
    Ok(Operation {
        id: format!("view.{name}"),
        label: format!("Create view \"{name}\""),
        precheck: vec![check(
            format!("ensure view \"{name}\" does not exist"),
            dialect.view_exists_sql(schema, name, true),
        )],
        execute: vec![step(
            format!("create view \"{name}\""),
            format!(
                "CREATE VIEW {} AS {select_sql}",
                dialect.qualified(schema, name)
            ),
        )],
        postcheck: vec![check(
            format!("verify view \"{name}\" exists"),
            dialect.view_exists_sql(schema, name, false),
        )],
        outside_transaction: false,
    })
}

/// Create a materialized view from a `SELECT` statement (not refreshed here).
pub fn create_materialized_view(
    schema: &str,
    name: &str,
    select_sql: &str,
    dialect: &dyn SqlDialect,
) -> Result<Operation> {
    require_capability(
        dialect,
        dialect.capabilities().materialized_views,
        "materialized views",
    )?;
    Ok(Operation {
        id: format!("matview.{name}"),
        label: format!("Create materialized view \"{name}\""),
        precheck: vec![check(
            format!("ensure materialized view \"{name}\" does not exist"),
            dialect.matview_exists_sql(schema, name, true),
        )],
        execute: vec![step(
            format!("create materialized view \"{name}\""),
            format!(
                "CREATE MATERIALIZED VIEW {} AS {select_sql}",
                dialect.qualified(schema, name)
            ),
        )],
        postcheck: vec![check(
            format!("verify materialized view \"{name}\" exists"),
            dialect.matview_exists_sql(schema, name, false),
        )],
        outside_transaction: false,
    })
}