Migrations

Learn how to handle database migrations efficiently in Caesar.

Overview

Caesar leverages Bun migrations to simplify the task of managing your database schema. Migrations allow you to evolve your database schema over time, ensuring compatibility between different versions of your application.

Creating Migrations

Caesar provides the caesar make:migration command to create new migrations. When you run this command, it generates a new migration file in the ./database/migrations folder.

Usage

caesar make:migration add_users_table

This command will create a new migration file with an appropriate timestamp and the provided name (add_users_table) in the ./database/migrations folder.

Migration Commands

Caesar provides several commands to manage your database migrations:

Run All Pending Migrations

The migrations:run command runs all pending migrations.

caesar migrations:run

This command applies all outstanding migrations to bring your database schema up-to-date.

Rollback the Last Migration

The migrations:rollback command rolls back the last applied migration.

caesar migrations:rollback

This command reverts the database to the state before the last migration was applied.

Reset All Migrations

The migrations:reset command resets all migrations, effectively rolling them all back.

caesar migrations:reset

This command rolls back all migrations, bringing your database back to its initial state.

Example of a Migration File

Here's an example of what a migration file might look like:

package migrations

import (
	"context"
	"myapp/app/models"

	"github.com/uptrace/bun"
)

func addUsersTableUp_123456789(ctx context.Context, db *bun.DB) error {
	_, err := db.NewCreateTable().Model((*models.User)(nil)).Exec(ctx)
	return err
}

func addUsersTableDown_123456789(ctx context.Context, db *bun.DB) error {
	_, err := db.NewDropTable().Model((*models.User)(nil)).Exec(ctx)
	return err
}

func init() {
	Migrations.MustRegister(addUsersTableUp_123456789, addUsersTableDown_123456789)
}

In this example, the addUsersTableUp_123456789 function creates a users table using the Bun ORM when applied, and the addUsersTableDown_123456789 function drops that table when rolled back.

The init function registers these migration functions with the Bun Migrations manager.

Managing Migrations

Ensure your migrations are well-formed and can be applied and rolled back without causing data loss or schema inconsistencies. Here’s how you can manage your migrations effectively:

1. Create a New Migration: Use caesar make:migration <name> to create a new migration file.
2. Edit the Migration: Open the generated file in the ./database/migrations folder and add your up and down migration functions.
3. Register the Migration: Register your migration functions in the init function with the Migrations.MustRegister method.
4. Apply Migrations: Run caesar migrations:run to apply all pending migrations.
5. Rollback a Migration: Use caesar migrations:rollback to roll back the last migration if needed.
6. Reset Migrations: Use caesar migrations:reset to roll back all migrations, restoring the initial schema state.

Migration Lifecycle

Applying a Migration

When you apply a migration:

• The "up" migration function is executed.
• Changes are made to your database schema according to the migration.

Rolling Back a Migration

When you roll back a migration:

• The "down" migration function is executed.
• Changes made by the "up" migration are reverted.

Resetting Migrations

When you reset migrations:

• The "down" migration function of each applied migration is executed in the reverse order.

Summary

Migrations in Caesar, powered by Bun migrations, provide a robust way to manage your database schema over time. With convenient commands like caesar make:migration, migrations:run, migrations:rollback, and migrations:reset, you can create, apply, and manage migrations seamlessly.

Make sure your database schema stays in sync with your application code, ensuring smooth deployments and updates