optimumenergyco / beagle

The friendly database migration tool

Beagle

Beagle is a simple, lightweight and friendly database migration tool.

Why Beagle?

You might be wondering why we decided to create Beagle. Aren't there already a bunch of other migration tools out there?

We set out to build Beagle to solve a few problems we felt weren't addressed by other tools:

• Platform agnostic: Many migration tools are designed to work with a specific programming language or framework. We feel like this is overly limiting. Beagle is written in JavaScript, but it can be used with any other platform or framework.
• Plain SQL: Other tools layer an ORM on top of the migrations platform. This usually results in a limited set of supported migration features that work for all databases, which is a bummer when you want to use a feature specific to your database. Beagle uses plain SQL files for its migrations, so you can use any database features you'd like.
• Independent migrations: Some migration tools only keep track of the latest migration. Let's say Karen creates a migration, and then a little later Juan adds a migration. If Juan's migration gets pushed to production and run first, in some systems Karen's migration will never run. Beagle keeps track of individual migrations, allowing you to merge at will.

Current Gotchas

Beagle is a new project and is still under active development. There are currently a few caveats to using it. In the future, these will be addressed.

• The only database currently supported is Postgres.
• Installation is only available via yarn or npm.
• Beagle doesn't include commands to create or drop a database. For now, we suggest you use the Postgres createdb and dropdb commands.
• There's currently no way to run a specific migration. Migrations must be run in order.

Installation

Install Beagle using your favorite JavaScript package manager.

Yarn:

yarn add @optimumenergyco/beagle

NPM:

npm install --save @optimumenergyco/beagle

The Commands

Beagle ships with a simple CLI.

• beagle --help: List out all of the available Beagle commands.
• beagle <command> --help: Get detailed instructions for a command.
• beagle up: Run the next pending migration.
• beagle down: Roll back the last completed migration.
• beagle all: Run all of the pending migrations.
• beagle status: List the pending and completed migrations.
• beagle generate <name>: Create a new timestamped migration file using the provided name.

Database Configuration

Beagle supports two ways to configure the database connection.

Any commands that require a database connection can be configured with the following flags:

• --host: The database's host.
• --port: The database's port.
• --user: The username used to connect to the database.
• --password: The password used to connect to the database.
• --database: The name of the database.

Optionally, these parameters can be configured using environment variables.

• BEAGLE_HOST
• BEAGLE_PORT
• BEAGLE_USER
• BEAGLE_PASSWORD
• BEAGLE_DATABASE

Example

Let's say you'd like to create a new table for your potatoes. Start by calling generate to create your files.

beagle generate create-potatoes

This creates two files:

• 20180819000000-create-potatoes-up.sql
• 20180819000000-create-potatoes-down.sql

You decide your up file will create a potatoes table and your down file will drop it.

20180819000000-create-potatoes-up.sql:

CREATE TABLE potatoes (name TEXT NOT NULL);

20180819000000-create-potatoes-down.sql:

DROP TABLE potatoes;

If you run beagle status, you'll see your migration under "Pending Migrations":

Completed Migrations:

N/A

Pending Migrations:

20180819000000-create-potatoes-up.sql

To run your migration, call beagle up. Afterwards, beagle status will show your migration under "Completed Migrations":

Completed Migrations:

20180819000000-create-potatoes-up.sql

Pending Migrations:

N/A

Deployment

Deployments of Beagle must be done manually. If we were to include our NPM credentials in CodeShip, anyone could submit a pull request calling console.log(process.env) and have access.

To deploy Beagle:

yarn version <version>
yarn publish --access=public

To push up the tags to GitHub:

git push --tags origin master
git push origin master

License

Beagle is licensed under the MIT license.

beagle's Issues

Add a drop command

Add a command to drop the database.

Add a reset command

Add a reset command. This should be shorthand for beagle drop && beagle create && beagle all.

Add a create command

Add a command to create a database.

Add sane defaults to some of the parameters

We should be able to add some sane defaults for some of the parameters to the CLI. For example, the port could default to 5342 and the migrations directory should default tomigrations.