Metaxis is a Haskell library for managing database migrations across multiple backends. It provides a unified interface for applying and rolling back migrations, supporting both SQLite and PostgreSQL.
- Multi-backend support: SQLite and PostgreSQL.
- Migration management: Apply and roll back migrations easily.
- Schema tracking: Keeps track of applied migrations in a dedicated table.
To use Metaxis, ensure you have Haskell installed along with the required dependencies.
Metaxis supports optional build flags to enable specific database backends. Use stack to configure these flags during the build process:
# Build with SQLite enabled and PostgreSQL disabled
stack build --flag metaxis:sqlite --flag metaxis:-postgres
# Build with PostgreSQL enabled and SQLite disabled
stack build --flag metaxis:postgres --flag metaxis:-sqliteIf a backend is disabled, attempting to use it will result in an error message at runtime.
Metaxis provides two main commands:
- Migrate: Apply all pending migrations.
- Rollback: Roll back the last applied migration.
Run the executable with the desired command and backend:
# Apply migrations using SQLite
metaxis migrate --backend sqlite
# Roll back the last migration using PostgreSQL
metaxis rollback --backend pgMigration files should be placed in the migrations directory. Each migration consists of:
- An
.sqlfile for applying the migration. - An optional
.down.sqlfile for rolling back the migration.
Migrations should be numbered sequentially to ensure proper ordering. While a three-digit format (e.g., 001, 002) is recommended for consistency, you can use any numbering scheme as long as it ensures migrations are applied in the correct order.
Example:
migrations/
├── 001_create_users.sql
├── 001_create_users.down.sql
├── 002_add_email_to_users.sql
├── 002_add_email_to_users.down.sql
- SQLite: Uses a local file-based database. Default file is
dev.sqlite3. - PostgreSQL: Uses
defaultConnectInfofor connection. Customize as needed.
After building the project, the metaxis executable will be located in the .stack-work directory. You can run it directly using the full path or add the directory to your PATH for convenience.
Run the executable with the desired command and backend:
# Apply migrations using PostgreSQL
./.stack-work/install/aarch64-osx/<resolver>/bin/metaxis migrate --backend pg
# Roll back the last migration using SQLite
./.stack-work/install/aarch64-osx/<resolver>/bin/metaxis rollback --backend sqliteReplace <resolver> with the specific resolver used during the build process (e.g., cd0d45758eebe2f97dd3d906710943610beec0f500f409354d6ac8c1eeab2e1f/9.8.4).
Alternatively, you can use stack exec to run the binary without specifying the full path:
stack exec metaxis -- migrate --backend pg
stack exec metaxis -- rollback --backend sqliteTo build the project, use the following commands:
stack build
stack exec metaxis -- <command>Metaxis includes a test suite to verify functionality. To run the tests, use:
stack testThe test suite includes:
- SQLite Tests: Ensures schema creation and migration application.
Tests are located in the test directory, with the main entry point being Spec.hs.