db-truck

🚚 db-truck

db-truck is a simple npm module you can use to manage schema migrations for your favorite SQL database.

Migrating your database has never been so easy!

Usage

# install db-truck
$ npm install -g db-truck

# or install it locally if you want to use it in a project
$ npm install --save-dev db-truck

# create your new repository
$ db-truck init

# create your first migration
$ db-truck create my-first-migration

# ./migrations/<unix_timestamp>_my-first-migration.js
# Implement your migration

# Run all of your migrations
$ CONNECTION_STRING=<connection-string> db-truck up

# or through args:

$  db-truck -c <connection-string> up

tip: You can export env variables if you'd like to keep your commands short, and not have to pass them in every time:

export CONNECTION_STRING=<...>
export MIGRATIONS_PATH=<...>
# or
export DB_USER=<...>
export DB_PASSWORD=<...>
export HOST=<...>
export DB=<...>

Commands

db-truck init

This will create a ./migrations folder where you can keep your migrations

$ db-truck init

db-truck create

Creates a new migration:

$ db-truck create my-first-migration

creates a file under ./migrations/<unix_timestamp>_my-first-migration.js with a sample migration:

module.exports = {
  up: async client => {
    /*
      Create/alter statements
      e.g.
      await client.query('CREATE TABLE ${migrationName};')
    */
  },
  down: async client => {
    /*
      Reverse your migration here
      e.g.
      await client.query('DROP TABLE ${migrationName};')
    */
  }
}

Migrations can also be written in TypeScript and parameterised SQL template strings are supported (like those provided by sql-template-tag or sql-template-strings):

import { Migration } from 'db-truck'
import sql from 'sql-template-tag'

const migration: Migration = {
  up: async client => {
    const value = 'text'
    await client.query(sql`INSERT INTO test_table (text) VALUES (${value});`)
  }
}

export default migration

db-truck pending

Lists all your pending migrations

$ db-truck pending

db-truck up

Runs all your pending migrations

$ db-truck up

db-truck assume-migrated

Force updates the migrations table to assume that certain migrations have been run. This is especially useful in scenarios where you're adding db-truck to a database that already contains data and you wouldn't want to have all migrations applied to an existing production environment.

note: assume-migrated accepts the same options as the up command.

$ db-truck assume-migrated

db-truck down

Will downgrade your migrations (one downgrade per run)

$ db-truck down

custom migration paths

If you'd like to store your migrations in a different path:

$ db-truck -migrations-path=<your_custom_path>

or, export the following environment variable:

export MIGRATIONS_PATH=<your_custom_path>

Design

db-truck uses sequelize and umzug under the hood. Sequelize will create a schema_migrations table in your database in order to keep track of which migrations have been executed and which ones are still pending.

License (MIT)

WWWWWW||WWWWWW
 W W W||W W W
      ||
    ( OO )__________
     /  |           \
    /o o|    MIT     \
    \___/||_||__||_|| *
         || ||  || ||
        _||_|| _||_||
       (__|__|(__|__|

Copyright (c) 2018 Segment.io, Inc. [e-mail]

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the 'Software'), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Maintainers

Create PR, get it approved. Once it's merged to master you can release new version by running release workflow against master branch, which will upgrade the version, rebuild files in dist and push it to the repo's master branch