migratrom 0.2.0

Declarative, self-verifying database migrations (core engine).
Documentation
//! Declarative, self-verifying migrations for PostgreSQL and SQLite.
//!
//! Most applications should use an adapter crate rather than implement [`Db`]:
//! [`migratrom-sqlite`](https://docs.rs/migratrom-sqlite) for a `sqlx::SqlitePool`
//! or [`migratrom-postgres`](https://docs.rs/migratrom-postgres) for a
//! `sqlx::PgPool`. Each adapter exposes an `apply_migrations` convenience function
//! that acquires and pins one connection for the complete migration run.
//!
//! # The migration model
//!
//! A [`Migration`] is a node in a parent/child DAG containing ordered
//! [`Operation`]s. Construct operations with [`operations`]' builders, then pass
//! the complete migration list to an adapter. The runner:
//!
//! 1. creates and reads its history table;
//! 2. verifies checksums for migrations already in that table;
//! 3. orders pending migrations by their parent relationship; and
//! 4. executes each operation as postcheck → precheck → DDL → postcheck.
//!
//! A passing postcheck skips an operation, so operations are idempotent. Editing
//! the operation body of an applied migration causes a checksum failure rather
//! than silently changing recorded history.
//!
//! # Define migrations
//!
//! Build migrations with a dialect matching the database that will apply them.
//! This example only constructs the migration; see the adapter crates for pool
//! setup and execution.
//!
//! ```
//! use migratrom::operations::{add_column, create_table};
//! use migratrom::{ColumnDef, Migration, PrimaryKey, SqliteDialect};
//!
//! # fn main() -> Result<(), migratrom::MigratromError> {
//! let dialect = SqliteDialect;
//! let users = Migration::new(
//!     1,
//!     None,
//!     vec![create_table(
//!         "main",
//!         "users",
//!         &[ColumnDef::new("id", "INTEGER"), ColumnDef::new("email", "TEXT")],
//!         Some(&PrimaryKey { columns: vec!["id".into()] }),
//!         &dialect,
//!     )?],
//! );
//! let add_name = Migration::new(
//!     2,
//!     Some(users.id),
//!     vec![add_column(
//!         "main",
//!         "users",
//!         &ColumnDef::new("name", "TEXT").nullable(true),
//!         &dialect,
//!     )?],
//! );
//! let _: Vec<Migration> = vec![users, add_name];
//! # Ok(())
//! # }
//! ```
//!
//! # Applying safely
//!
//! [`ApplyOptions`] controls the history-table name, dry runs, advisory locking,
//! and progress logging. A dry run executes read-only checks but performs no DDL
//! or history writes. PostgreSQL migrations acquire an advisory lock by default;
//! SQLite does not support advisory locks. A migration normally runs in one
//! transaction. An [`Operation::outside_transaction`] operation, such as a
//! concurrent PostgreSQL index, divides it into transactional segments.
//!
//! # Advanced integrations
//!
//! Implement [`Db`] only when an application cannot use the provided `sqlx`
//! adapters. Implement [`SqlDialect`] to support another database engine. Use
//! [`MigrationLogger`] to integrate migration progress with an application's
//! logging system.
//!
//! For supported schema changes, start with the [`operations`] cookbook. For
//! manually authored DDL, use [`operations::raw_sql`] and supply explicit checks.

#![deny(missing_docs)]

pub mod checksum;
pub mod operations;

mod db;
mod error;
mod graph;
mod logger;
mod runner;
mod sql;
mod types;

pub use db::{with_transaction, Db, Row};
pub use error::{MigratromError, Result};
pub use graph::plan_order;
pub use logger::{ConsoleLogger, MigrationLogger};
pub use runner::{
    advisory_lock_key, apply_migrations, ensure_history_table, read_applied_ids,
    read_applied_records, record_migration, run_operation, AppliedRecord, ApplyOptions, OpOutcome,
    DEFAULT_HISTORY_TABLE,
};
pub use sql::{PostgresDialect, SqlDialect, SqliteDialect};
pub use types::{
    ApplyResult, Check, ColumnDef, CreateIndexOptions, DialectCapabilities, ExecuteStep,
    ForeignKeyReference, ForeignKeySpec, Migration, Operation, PrimaryKey, ReferentialAction,
};