Micrate

If your migration contains complex SQL statements that include semicolons (such as PL/pgSQL functions), you must wrap the block in StatementBegin and StatementEnd directives to prevent micrate from incorrectly splitting the script.

-- +micrate Up
-- +micrate StatementBegin
CREATE OR REPLACE FUNCTION example_func() RETURNS void AS $$
BEGIN
  -- complex logic with semicolons
END;
$$ language plpgsql;
-- +micrate StatementEnd

Use the scaffold subcommand to generate a new migration file. This creates a timestamped .sql file in the db/migrations/ directory containing Up and Down sections.

Example command: micrate scaffold <migration_name>

Migration files use special comments to define execution blocks:

• -- +micrate Up: SQL to run when applying the migration.
• -- +micrate Down: SQL to run when rolling back the migration.

$ micrate scaffold add_users_table

You can install the standalone micrate binary tool via Homebrew or by downloading a release from the GitHub repository. Once installed, micrate connects to your database using the DATABASE_URL environment variable.

$ brew tap amberframework/micrate
$ brew install micrate

To use micrate programmatically within a Crystal project, add it as a dependency in your shard.yml:

dependencies:
  micrate:
    github: amberframework/micrate

To run the CLI logic manually (e.g., in a CI runner or a custom script), require the driver you are using and call Micrate::Cli.run after setting the Micrate::DB.connection_url.

require "micrate"
require "pg"

Micrate::DB.connection_url = "postgresql://..."
Micrate::Cli.run

Micrate is a database migration management system for Crystal projects. To use the CLI, you must first set the DATABASE_URL environment variable.

Setup

export DATABASE_URL=postgres://user:pswd@host:port/database

Usage

micrate [options] <subcommand> [subcommand options]

export DATABASE_URL=postgres://user:pswd@host:port/database
micrate up

Use the following commands to control your database schema state:

• micrate up: Executes all pending migrations.
• micrate down: Rolls back the last applied migration.
• micrate redo: Rolls back the last migration and immediately applies it again.
• micrate status: Shows the state (Applied At or Pending) of all migrations.
• micrate dbversion: Returns the current version of the database.

$ micrate up
$ micrate status
$ micrate dbversion
$ micrate down
$ micrate redo

If you are building a standalone command line client in Crystal, you can use Micrate::Cli directly. You must require the driver you wish to use and then invoke the run method.

require "micrate"
# require your driver here

Micrate::Cli.run

To create the scaffolding for a new migration, use the scaffold command followed by the desired migration name.

Usage

micrate scaffold <migration_name>

micrate scaffold create_users_table