https://github.com/fboulnois/migrio
A drop-in database migration library in Rust for PostgreSQL
https://github.com/fboulnois/migrio
async postgres postgresql rust sql tokio tokio-postgres
Last synced: 3 months ago
JSON representation
A drop-in database migration library in Rust for PostgreSQL
- Host: GitHub
- URL: https://github.com/fboulnois/migrio
- Owner: fboulnois
- License: mit
- Created: 2025-05-26T23:21:32.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2025-05-26T23:26:42.000Z (about 1 year ago)
- Last Synced: 2025-12-21T21:14:24.540Z (5 months ago)
- Topics: async, postgres, postgresql, rust, sql, tokio, tokio-postgres
- Language: Rust
- Homepage:
- Size: 18.6 KB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# migrio
An asynchronous database migration library for PostgreSQL.
- `sqlx` is a library for working with databases in Rust and provides a fantastic migration feature which is simple and easy to use. However, it also depends on a lot of crates and is not specifically focused on performance.
- `tokio-postgres` is an extremely fast PostgreSQL client for Rust built on `tokio` but it does not provide any migration functionality.
`migrio` combines the best of both of these crates. By only focusing on migrations, `migrio` is able to provide a simple way to apply and roll back migrations in your database. It provides a nearly drop-in replacement for the migration functionality of `sqlx`, but is built on top of `tokio-postgres` to minimize dependencies.
## Usage
1. Create a migration directory with SQL files. Each file should be named with a version number and a description, for example:
```sh
migrations/
├── 0001_initial.sql
├── 0002_add_column.sql
├── 0003_add_table.up.sql
└── 0003_add_table.down.sql
```
2. Add `migrio` to your `Cargo.toml`:
```toml
[dependencies]
migrio = "1.0"
```
3. Run the migration from your code:
```rust
use migrio::Migration;
// let (mut client, connection) = tokio_postgres::connect(...).await?;
// ...
let migration = Migration::new("migrations")?;
migration.run(&mut client).await?;
```
## API
The API and functionality of `migrio` is nearly identical to `sqlx`:
```rust
// type alias of migrio::Migration
use migrio::Migrator;
// create a new migration from the `migration_dir` directory
let migration = Migrator::new(migration_dir)?;
// run all migrations
migration.run(&mut client).await?;
// roll back migrations up to a specific version
migration.undo(&mut client, version).await?;
```
`migrio` sorts the migrations by version number and applies them in order. If a migration fails, the entire migration is rolled back. Migrations use the following naming scheme for files:
```sh
{VERSION}_{DESCRIPTION}.sql
{VERSION}_{DESCRIPTION}.up.sql
{VERSION}_{DESCRIPTION}.down.sql
```
`{VERSION}` is a number that represents the order in which the migrations should be applied. `{DESCRIPTION}` is a human-readable description of the migration. `migrio` also supports optional reversible `up` and `down` migrations. When using reversible migrations, each `up` migration should be paired with a corresponding `down` migration. The `down` migrations are applied in reverse order when `undo`ing a migration.
## Development
### Building
To build the library:
```sh
cargo build
```
### Testing
To run unit tests:
```sh
cargo test
```
To also run integration tests against a PostgreSQL database:
```sh
docker compose -f tests/docker-compose.test.yml up -d
cargo test -- --include-ignored
```