migratrom 0.2.0

Declarative, self-verifying database migrations (core engine).
Documentation
//! Schema-change cookbook.
//!
//! Every builder returns a self-verifying [`crate::Operation`]: it has a stable
//! id, human-readable label, prechecks, execute steps, and postchecks. Add the
//! resulting operations to a [`crate::Migration`] and apply the migration with
//! an adapter crate. A passing postcheck makes the operation a safe no-op.
//!
//! # Tables and columns
//!
//! These builders work with both built-in dialects where the underlying SQL is
//! supported. `ColumnDef` type and default strings are authored SQL, so use the
//! syntax of the selected database.
//!
//! ```rust
//! use migratrom::operations::{add_column, create_table, rename_column, rename_table};
//! use migratrom::{ColumnDef, PrimaryKey, SqliteDialect};
//!
//! # fn main() -> Result<(), migratrom::MigratromError> {
//! let dialect = SqliteDialect;
//! let _create = create_table(
//!     "main", "users",
//!     &[ColumnDef::new("id", "INTEGER"), ColumnDef::new("email", "TEXT")],
//!     Some(&PrimaryKey { columns: vec!["id".into()] }),
//!     &dialect,
//! )?;
//! let _add = add_column(
//!     "main", "users", &ColumnDef::new("display_name", "TEXT").nullable(true), &dialect,
//! )?;
//! let _rename_table = rename_table("main", "users", "accounts", &dialect)?;
//! let _rename_column = rename_column("main", "accounts", "display_name", "name", &dialect)?;
//! # Ok(())
//! # }
//! ```
//!
//! # PostgreSQL column changes and constraints
//!
//! `set_column_default`, `set_column_not_null`, and the constraint builders
//! require PostgreSQL capabilities. They return [`crate::MigratromError::Unsupported`]
//! with [`crate::SqliteDialect`].
//!
//! ```rust
//! use migratrom::operations::{
//!     add_check, add_foreign_key, add_primary_key, add_unique, set_column_default,
//!     set_column_not_null,
//! };
//! use migratrom::{ForeignKeyReference, ForeignKeySpec, PostgresDialect, ReferentialAction};
//!
//! # fn main() -> Result<(), migratrom::MigratromError> {
//! let dialect = PostgresDialect;
//! let _default = set_column_default("public", "users", "role", "DEFAULT 'member'", &dialect)?;
//! let _not_null = set_column_not_null("public", "users", "email", &dialect)?;
//! let _unique = add_unique("public", "users", "users_email_key", &["email".into()], &dialect)?;
//! let _check = add_check("public", "users", "users_email_nonempty", "email <> ''", &dialect)?;
//! let _primary_key = add_primary_key("public", "events", "events_pkey", &["id".into()], &dialect)?;
//! let _foreign_key = add_foreign_key(
//!     "public", "posts",
//!     &ForeignKeySpec {
//!         name: "posts_author_id_fkey".into(),
//!         columns: vec!["author_id".into()],
//!         references: ForeignKeyReference { table: "users".into(), columns: vec!["id".into()] },
//!         on_delete: Some(ReferentialAction::Cascade),
//!         on_update: None,
//!     },
//!     &dialect,
//! )?;
//! # Ok(())
//! # }
//! ```
//!
//! # Indexes
//!
//! A normal index works with both dialects. Setting
//! [`crate::CreateIndexOptions::concurrently`] uses PostgreSQL's `CREATE INDEX
//! CONCURRENTLY`; the operation is marked [`crate::Operation::outside_transaction`]
//! and is rejected by SQLite.
//!
//! ```rust
//! use migratrom::operations::create_index;
//! use migratrom::{CreateIndexOptions, PostgresDialect};
//!
//! # fn main() -> Result<(), migratrom::MigratromError> {
//! let dialect = PostgresDialect;
//! let _index = create_index(
//!     "public", "users", "users_email_idx", &["email".into()],
//!     &CreateIndexOptions { concurrently: true }, &dialect,
//! )?;
//! # Ok(())
//! # }
//! ```
//!
//! # PostgreSQL schema objects
//!
//! Schemas, extensions, sequences, enum types, enum values, and materialized
//! views are PostgreSQL-only. Regular views work with both built-in dialects.
//!
//! ```rust
//! use migratrom::operations::{
//!     add_enum_value, create_extension, create_materialized_view, create_schema,
//!     create_sequence, create_type, create_view, AddEnumValueOptions, CreateExtensionOptions,
//! };
//! use migratrom::PostgresDialect;
//!
//! # fn main() -> Result<(), migratrom::MigratromError> {
//! let dialect = PostgresDialect;
//! let _schema = create_schema("app", &dialect)?;
//! let _extension = create_extension(
//!     "pgcrypto", &CreateExtensionOptions { schema: Some("app".into()) }, &dialect,
//! )?;
//! let _sequence = create_sequence("app", "event_ids", &dialect)?;
//! let _type = create_type("app", "role", &["member".into(), "admin".into()], &dialect)?;
//! let _enum_value = add_enum_value(
//!     "app", "role", "owner", &AddEnumValueOptions { before: Some("admin".into()) }, &dialect,
//! )?;
//! let _view = create_view("app", "active_users", "SELECT * FROM app.users WHERE active", &dialect)?;
//! let _materialized = create_materialized_view(
//!     "app", "user_counts", "SELECT count(*) AS total FROM app.users", &dialect,
//! )?;
//! # Ok(())
//! # }
//! ```
//!
//! # Raw SQL
//!
//! Use [`raw_sql`] when the built-in builders do not cover a change. Supply at
//! least one execute step and one boolean postcheck; otherwise the builder returns
//! [`crate::MigratromError::Config`].
//!
//! ```rust
//! use migratrom::operations::{raw_sql, RawCheck, RawSqlInput, RawStep};
//!
//! # fn main() -> Result<(), migratrom::MigratromError> {
//! let _operation = raw_sql(RawSqlInput {
//!     label: "Create audit trigger".into(),
//!     execute: vec![RawStep::new("CREATE TRIGGER audit_users AFTER INSERT ON users BEGIN SELECT 1; END")],
//!     postcheck: vec![RawCheck::new(
//!         "SELECT EXISTS (SELECT 1 FROM sqlite_master WHERE type = 'trigger' AND name = 'audit_users')",
//!     )],
//!     ..Default::default()
//! })?;
//! # Ok(())
//! # }
//! ```

mod columns;
mod constraints;
mod helpers;
mod indexes;
mod raw;
mod schema_objects;
mod tables;

pub use columns::{set_column_default, set_column_not_null};
pub use constraints::{add_check, add_foreign_key, add_primary_key, add_unique};
pub use indexes::create_index;
pub use raw::{raw_sql, RawCheck, RawSqlInput, RawStep};
pub use schema_objects::{
    add_enum_value, create_extension, create_materialized_view, create_schema, create_sequence,
    create_type, create_view, AddEnumValueOptions, CreateExtensionOptions,
};
pub use tables::{add_column, create_table, rename_column, rename_table};