guzu

guzu is a database migration tool, inspired by goose and postgres-migrations. Guzu means goose in Japanese.

Project goals:

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

Install

npm install @garriguv/guzu --save-dev

Usage

import { Guzu } from "@garriguv/guzu";

async function main() {
  const guzu = new Guzu({
    config: {
      host: "localhost",
      port: 5432,
      database: "application_database",
      user: "postgres",
      password: "password",
    },
    dir: "./migrations",
  });

  await guzu.migrate();
}

Options

config

The database configuration. This is passed directly to node-postgres.

dir

The path to the directory containing all migration files.

tableName

The name of the table used to track the migrations. Defaults to guzu_migrations.

logger

A logger object. Defaults to console.log.

Migrations

sqlmigrations only supports migrations written in SQL.

A sample SQL migration looks like this:

CREATE TABLE users (
	id SERIAL PRIMARY KEY,
	name text NOT NULL
);

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

To create a new migration file, you can use the createMigration function:

import { createMigration } from "@garriguv/guzu";

// This will create a new migration file in the ./migrations directory
// with the name XXXX_my_new_migration.sql, where XXXX is the next
// available migration number.
createMigration("My new migration", "./migrations");

The createMigration function will automatically format the migration file name using the next available migration number.

Development

Tests

We run PostgreSQL in a Docker container for the tests, which means that you need to have Docker installed on your machine.

Run the tests:

npm t

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