npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

goose.js

v0.1.1

Published

CLI command for database migration

Downloads

5

Readme

Goose CLI

A very simple database migration CLI tool for Mysql, Sqlite and PostGres. Most migration tools require developers to use a specific DML framework, the idea is to make migration portable between vendors. In reality people don't really change database and since SQL is not standardized across vendor sometimes you find yourself hacking those libraries to support unsupported edge cases. Goose prefers raw SQL file approach, you write the exact SQL statements for your database.

Install

Goose.js is written in Node.js so make sure you have installed latest stable version.

$ npm install -g goose.js

Get started

Create a new folder for your project migration. Ideally it's better to have separate migration folder per project, goose creates a default config file in the root of your project directory.

$ mkdir my_project
$ cd my_project
$ goose.js init

By default, this config file is named goosefile.json, but you can use the --format or -f command line option to specify either yaml or json. Configure your environment with the correct credentials:

goosefile.json

{
  ...
    "default_database": "development",
    "development": {
      "adapter": "mysql",
      "host": "localhost",
      "user": "test",
      "pass": "test",
      "port": 3306,
      "database": "",
      "charset": "utf8"
    }
  },
  ...
}

To know more about the configuration options look into the Configuration file parameter section

Create migration

Let’s create a new goose migration. Run goose.js using the create command:

$ goose.js create users

This will create a new migration directory in the format YYYY_MM_DD_<MILLISECOND>_users, inside the db/migrations folder. Alose, goose creates two skeleton migration files up.sql and down.sql.

Migrate up

The up.sql file is automatically run when you are migrating up and it detects the given migration hasn’t been executed previously. You should use the up command to transform the database with your intended changes. Example:

-- Inside up.sql

CREATE TABLE users (
    id INT,
    name VARCHAR(200)
);
CREATE TABLE friends (
    user_id INT,
    friend_id INT
);
Migrate down

The down.sql file is automatically run by goose when you are migrating down and it detects the given migration has been executed in the past. You should use the down command to reverse/undo the transformations described in the up.sql.

-- Inside down.sql

DROP TABLE users;
DROP TABLE friends;

Configuration File Parameter

When you initialize your project using the init Command, goose creates a default file in the root of your project directory. By default, this file uses the json data serialization format, but you can use the --format command line option to specify yaml.

  environments: 
    default_migration_table: "goose_migrations"
    default_database: "development"
    development: 
      adapter: "mysql"
      host: "localhost"
      user: "test"
      pass: ""
      port: 3306
      charset: "utf8"
  paths: 
    migrations: "db/migrations"

goose auto-detects which language parser to use for files with *.yml, *.json extensions.

If a --conf command line option is given, goose will load the specified file. Otherwise, it will attempt to find goosefile.json.

Environments

One of the key features of goose is support for multiple database environments. You can use goose to create migrations on your development environment, then run the same migrations on your production environment. Environments are specified under the environments nested collection. For example:

"environments": {
    "default_migration_table": "goose_migrations",
    "default_database": "development",
    "development": {
        "adapter": "mysql",
        "host": "localhost",
        "user": "test",
        "pass": "test",
        "port": 3306,
        "charset": "utf8",
   "production": {
       "adapter": "mysql",
       "host": "prod.server.com",
       "user": "SECRET_USER",
       "pass": "SECRET_PASSWORD",
       "port": 3306,
       "charset": "utf8", 
}
Supported Adapters

Goose currently supports the following database adapters natively:

  • MySQL: specify the mysql adapter.

    "adapter": "mysql",
    "host": "localhost",
    "user": "test",
    "pass": "test",
    "port": 3306,
    "database": ""
  • Sqlite: specify the sqlite adapter.

    "adapter": "sqlite",
    "filename": "./data/derby.db"
  • PostgreSQL: specify the sqlite adapter.

    "adapter": "pgsql",
    "host": "localhost",
    "user": "test",
    "pass": "test",
    "port": 3306,
    "database": ""

Migration Paths

Goose uses db/migrations by default as the path to your migrations directory. In order to overwrite the default location, you need to add the following to the yaml configuration.

"paths": {
    "migrations": "db/custom/path/migrations",
  }

INPORTANT: The migration path is always relative to the project root

Commands

Help command

The help command shows all supported commands with a short short description.

$ goose.js help

To know a specific command usage pass the help subcommand.

$ goose.js init help
$ goose.js up help
Init command

The Init command (short for initialize) is used to prepare your project for goose. This command generates the goosefile.json file in the root of your project directory.

$ cd yourapp
$ goose.js init

Optionally you can specify a custom location for goose’s config file:

$ cd yourapp
$ goose.js init ./custom/location/

You can also specify a custom file name:

$ cd yourapp
$ goose.js init custom-config.yml
Up command

The up command runs all of the available migrations, optionally up to a specific version.

$ goose.js up -e development

To migrate to a specific version then use the --timestamp parameter or -t for short.

$ goose.js migrate -e development -t 20110103081132
Down command

The up command is used to undo previous migrations executed by goose. It is the opposite of the up command.

$ goose.js down -e development

To rollback to a specific version then use the --timestamp parameter or -t for short.

$ goose.js down -e development -t 20110103081132

Specifying 0 as the target version will revert all migrations.

$ goose.js rollback -e development -t 0
Status command

The Status command prints a list of all migrations, along with their current status. You can use this command to determine which migrations have been run.

$ goose.js status -e development