# goose.js

> CLI command for database migration

Latest version **0.1.1** (published 2018-09-17) · ISC license · 0 weekly downloads

## Install

```sh
npm install goose.js
pnpm add goose.js
yarn add goose.js
bun add goose.js
```

Provides the command `goose.js`.

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.1.1 |
| Published | 2018-09-17 |
| First published | 2018-09-17 |
| Weekly downloads | 0 |
| License | ISC |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 14 |
| Unpacked size | 251.4 KB |
| Known vulnerabilities | 0 (+3 in 2 direct dependencies) |
| Install scripts | no |
| Maintainers | kante |
| Keywords | goose, goose.js, database, migration, mysql, sqlite, postgres, mkante |

## Links

- npm: https://www.npmjs.com/package/goose.js
- npm.io page: https://npm.io/package/goose.js

## Dependencies (14)

- [pg](https://npm.io/package/pg.md) ^7.4.3
- [knex](https://npm.io/package/knex.md) ^0.15.1
- [chalk](https://npm.io/package/chalk.md) ^2.4.1
- [mysql](https://npm.io/package/mysql.md) ^2.15.0
- [yargs](https://npm.io/package/yargs.md) ^12.0.1
- [errors](https://npm.io/package/errors.md) ^0.3.0
- [lodash](https://npm.io/package/lodash.md) ^4.17.10
- [log4js](https://npm.io/package/log4js.md) ^2.11.0
- [sqlite3](https://npm.io/package/sqlite3.md) ^4.0.1
- [fs-extra](https://npm.io/package/fs-extra.md) ^6.0.1
- [json2yaml](https://npm.io/package/json2yaml.md) ^1.1.0
- [read-yaml](https://npm.io/package/read-yaml.md) ^1.1.0
- [dateformat](https://npm.io/package/dateformat.md) ^3.0.3
- [file-exists](https://npm.io/package/file-exists.md) ^5.0.1

## Alternatives

- [angular-pipes](https://npm.io/package/angular-pipes.md) — 5.6K weekly downloads
- [@ng-web-apis/midi](https://npm.io/package/@ng-web-apis/midi.md) — 2.6K weekly downloads
- [happn-3](https://npm.io/package/happn-3.md) — 1.6K weekly downloads
- [@opensip-cli/lang-go](https://npm.io/package/@opensip-cli/lang-go.md) — 1.2K weekly downloads
- [mongoose-typescript](https://npm.io/package/mongoose-typescript.md) — 85 weekly downloads

## Recent versions

- 0.1.1 (latest) — 2018-09-17
- 0.1.0 — 2018-09-17

## 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](https://nodejs.org/en/download/).

```Bash
$ 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.
```Bash
$ 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:

```Bash
$ 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:
```SQL
-- 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`.
```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.

```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:
```json
"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.
    ```javascript 1.8
    "adapter": "mysql",
    "host": "localhost",
    "user": "test",
    "pass": "test",
    "port": 3306,
    "database": ""
    ```
- Sqlite: specify the `sqlite` adapter.
    ```javascript 1.8
    "adapter": "sqlite",
    "filename": "./data/derby.db"
    ```
    
- PostgreSQL: specify the `sqlite` adapter.
    ```javascript 1.8
    "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.

```javascript 1.8
"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. 
```Bash
$ goose.js help
```

To know a specific command usage pass the help subcommand.
```Bash
$ 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.
```Bash
$ cd yourapp
$ goose.js init
```

Optionally you can specify a custom location for goose’s config file:
```Bash
$ cd yourapp
$ goose.js init ./custom/location/
```

You can also specify a custom file name:

```Bash
$ 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.

```Bash
$ goose.js up -e development
```
To migrate to a specific version then use the --timestamp parameter or -t for short.

```Bash
$ 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.

```Bash
$ goose.js down -e development
```
To rollback to a specific version then use the --timestamp parameter or -t for short.

```Bash
$ goose.js down -e development -t 20110103081132
```

Specifying 0 as the target version will revert all migrations.

```Bash
$ 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.

```Bash
$ goose.js status -e development
```

---
_Source: https://npm.io/package/goose.js · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._