# migratrom.rs
A Rust implementation of **migratrom** — declarative, self-verifying database
migrations.
## Installation
Add the core crate and the adapter for the database your application uses:
```toml
[dependencies]
migratrom = "0.1"
migratrom-sqlite = "0.1" # or migratrom-postgres = "0.1" / migratrom-turso = "0.1"
```
For development against an unreleased revision, pin the same Git revision for
each crate:
```toml
[dependencies]
migratrom = { git = "https://github.com/migratrom/migratrom.rs", rev = "<commit>" }
migratrom-sqlite = { git = "https://github.com/migratrom/migratrom.rs", rev = "<commit>" }
```
## Workspace
| `migratrom` | Core engine — types, DAG ordering, checksums, operation builders, both dialects, runner. No driver dependency. |
| `migratrom-postgres` | PostgreSQL adapter over `sqlx` (`PgPool`). |
| `migratrom-sqlite` | SQLite adapter over `sqlx` (`SqlitePool`). |
| `migratrom-turso` | [Turso](https://github.com/tursodatabase/turso) adapter — in-process, SQLite-compatible; reuses `SqliteDialect`. |
## Design
- The engine talks to a database only through the `Db` trait
(implemented by adapters) and emits SQL only through the `SqlDialect` trait
(`PostgresDialect` / `SqliteDialect`, both in core).
- **Self-verifying operations.** Each operation is a precheck → execute →
postcheck pipeline and is idempotent: if its postcheck already passes it is
skipped.
- **DAG ordering.** Migrations form a parent/child DAG; `plan_order` topologically
sorts pending migrations. Making it easy for branches to work without conflicts
- **Checksum verification.** Applied bodies are recorded with a SHA-256 checksum
editing an applied migration will make the migration process fail.
- **Transactions.** Each migration runs in one transaction unless it contains an
`outside_transaction` operation (e.g. `CREATE INDEX CONCURRENTLY`), in which
case segments run separately. Adapters pin a single connection so advisory
locks and `BEGIN/COMMIT/ROLLBACK` act on one session.
## Example
```rust
use migratrom::operations::create_table;
use migratrom::{ApplyOptions, ColumnDef, Migration, PrimaryKey, SqliteDialect};
use migratrom_sqlite::apply_migrations;
let dialect = SqliteDialect;
let m1 = Migration::new(
1,
None,
vec![create_table(
"main",
"users",
&[ColumnDef::new("id", "INTEGER"), ColumnDef::new("email", "TEXT")],
Some(&PrimaryKey { columns: vec!["id".into()] }),
&dialect,
)?],
);
apply_migrations(&[m1], &pool, &ApplyOptions::default()).await?;
```
Run it: `cargo run -p migratrom-sqlite --example basic`
## Testing
```sh
cargo test --workspace # unit, golden-vector, in-memory SQLite + Turso e2e
cargo clippy --workspace --all-targets -- -D warnings
cargo fmt --all --check
# PostgreSQL e2e (ignored by default):
DATABASE_URL=postgres://localhost/migratrom_test \
cargo test -p migratrom-postgres -- --ignored
```
## Releasing
Run the release script from a clean `main` checkout that matches `origin/main`.
Authenticate to crates.io first (for example, with `cargo login`). The script runs
formatting, Clippy, and workspace tests; publishes the crates in dependency order;
waits for the core crate to propagate; then creates and pushes the annotated
`v<version>` tag.
```sh
./scripts/publish.sh
```