guzu

guzu is a database migration tool, inspired by goose. Guzu means goose in Japanese.

Project goals:

• No configuration files
• SQL only migrations
• Timestamped migrations
• Immutable migrations once applied

Install

npm install guzu --save-dev

Usage

Options

All the commands require a data source name and a migrations directory where the migration files are located. You can pass these values as command line arguments or as environment variables.

The default value for the migrations directory is . (i.e. the current directory).

Command line arguments:

• --dsn: The data source name. (e.g. postgres://admin:password@localhost:5432)
• --dir: The migrations directory. (e.g. ./migrations)

Environment variables:

• GUZU_DSN: The data source name. (e.g. postgres://admin:password@localhost:5432)
• GUZU_DIR: The migrations directory. (e.g. ./migrations)

create

Create a new SQL migration:

npx guzu create <name>

status

Print the status of all migrations:

npx guzu status

up

Apply all pending migrations:

npx guzu up

up-by-one

Apply the next pending migration:

npx guzu up-by-one

down

Roll back the last applied migration:

npx guzu down

redo

Roll back the last migration and re-apply it.

npx guzu redo

Use this command when you are working on a new migration and you need to iterate on it. It will roll back the last migration and re-apply it even if the hash of the migration file has changed.

This command will ignore hash mismatches and should only be used during development.

seed

Seed the database with the migrations without applying them:

npx guzu seed

Use this command if you are migrating from another database migration tool and you want to seed the database with the migrations without applying them.

Migrations

sqlmigrations only supports migrations written in SQL.

A sample SQL migration looks like this:

-- +guzu up
CREATE TABLE users (
	id SERIAL PRIMARY KEY,
	name text NOT NULL
);

-- +guzu down
DROP TABLE users;

Each migration file must have a -- +guzu up annotation. The -- +guzu down annotation is optional. If a file has both annotations, the -- +guzu up annotation must come first.

By default, all migrations are run within a transaction. You can disable this by adding a -- +guzu NO TRANSACTION annotation.

Development

You can run the CLI using npm start:

npm start -- <command>

For a fast development cycle, you should sping up a PostgreSQL database and set both the GUZU_DSN and GUZU_DIR environment variables. You can use the integration test setup for that.

Start the database:

npm run db:up

Set the environment variables:

export GUZU_DSN=postgres://admin:password@localhost:5432
export GUZU_DIR=./integration/migrations/base

You can reset the database with:

npm run db:reset

A VSCode launch configuration with these settings is provided for debugging.

Unit tests

Run the tests:

npm test

Integration tests

The integration tests require Docker, we run a PostgreSQL database in a container. You can start the database with:

npm run db:up

The database will be available at postgres://admin:password@localhost:5432.

Run the integration tests:

npm run test:integration

Publishing a new release

1. Bump the package version: npm version <major|minor|patch>
2. Push the new version: git push --follow-tags
3. Create a new release: gh release create