Database Migrations

The pidgn migrate command manages database schema changes. It delegates to your application’s built-in migration runner by invoking zig build run with migration flags, so migrations execute within your app’s database context.

Usage

pidgn migrate [subcommand]

Subcommand	Description
(none) or up	Run all pending migrations
rollback	Roll back the last applied migration
status	Display which migrations have been applied and which are pending

Creating migrations

Migrations are generated automatically when you use the model generator:

src/post.zig

pidgn gen model Post title:string body:text published:boolean
# Generated: priv/migrations/001_create_post.zig

Migration files live in priv/migrations/ and follow a numbered naming convention (001_create_post.zig, 002_create_comment.zig, etc.). Each file exports two functions:

const MigrationContext = @import("pidgn_db").MigrationContext;

pub fn up(ctx: *MigrationContext) !void {
    try ctx.createTable("post", &.{
        .{ .name = "id", .col_type = .integer, .primary_key = true, .auto_increment = true },
        .{ .name = "title", .col_type = .text, .nullable = false },
        .{ .name = "body", .col_type = .text, .nullable = false },
        .{ .name = "published", .col_type = .boolean, .nullable = false },
        .{ .name = "inserted_at", .col_type = .bigint, .nullable = false },
        .{ .name = "updated_at", .col_type = .bigint, .nullable = false },
    });
}

pub fn down(ctx: *MigrationContext) !void {
    try ctx.dropTable("post");
}

• up applies the migration (creates tables, adds columns, etc.).
• down reverses it (drops tables, removes columns, etc.).

Running migrations

1. Make sure your database is configured. If you created the project with --db=sqlite or --db=postgres, the DATABASE_URL is already set in your .env file.

2. Run all pending migrations:

   pidgn migrate

   This is equivalent to pidgn migrate up. The CLI runs zig build run -- --migrate under the hood, which builds your application and executes the migration runner.

Rolling back

To undo the most recently applied migration:

pidgn migrate rollback

This calls zig build run -- --migrate-rollback, which invokes the down function of the last applied migration.

Checking status

To see which migrations have been applied and which are still pending:

pidgn migrate status

This calls zig build run -- --migrate-status and prints a table of migration names with their current state.

Writing migrations by hand

You can also create migration files manually in priv/migrations/. Use a sequential number prefix to control execution order:

priv/migrations/
  001_create_users.zig
  002_create_posts.zig
  003_add_email_to_users.zig

Each file must export up and down functions that accept a *MigrationContext. The context provides methods for common schema operations such as createTable, dropTable, addColumn, and removeColumn.

How it works

The pidgn migrate command does not connect to the database directly. Instead, it spawns zig build run with a special flag:

CLI command	Underlying invocation
pidgn migrate	zig build run -- --migrate
pidgn migrate rollback	zig build run -- --migrate-rollback
pidgn migrate status	zig build run -- --migrate-status

This means your application’s build.zig and database configuration are always used, ensuring migrations run against the correct database with the correct environment settings.

Next steps

• Generate models to create migrations automatically
• Start the dev server after applying migrations
• CLI overview for the full list of commands