TODO

> WIP: What's here is the end of Night #1

- [ ] driver support:
- [x] pg
- [x] postgres
- [x] mysql
- [x] mysql2
- [x] better-sqlite3
- [ ] sqlite
- [ ] complete test coverage
- [ ] complete documentation

Features

* Agnostic

_Supports postgres, pg, better-sqlite3, sqlite, mysql, mysql2, and custom drivers!_

* Lightweight

_Does not include any driver dependencies._

* Transactional

_Runs all migration files within a transaction for rollback safety._

* Familiar

_Does not invent new syntax or abstractions.
You're always working directly with your driver of choice._

* Flexible

_Find the CLI to restrictive? You may require ley for your own scripting!_

Install

``
$ npm install --save-dev ley
`

Usage

> Both Programmatic and CLI usages are supported.

$3

You must have a migrations directory created, preferably in your project's root.

> Note: You may configure the target directory and location.

Your filenames within this directory determine _the order of their execution._

Because of this, it's often recommended to prefix migrations with a timestamp or numerical sequence.

Numerical Sequence

`
/migrations
|-- 000-users.js
|-- 001-teams.js
|-- 002-seats.js
`

> Note: You may create the next file via ley new todos --length 3 where todos is a meaningful name.
The above command will create the migrations/003-todos.js filepath.

Timestamped

`
/migrations
|-- 1581323445-users.js
|-- 1581323453-teams.js
|-- 1581323458-seats.js
`

> Note: You may create the next file via ley new todos --timestamp where todos is a meaningful name.
The above command will create the migrations/1584389617-todos.js filepath...or similar.


The order of your migrations is critically important!
Migrations must be treated as an append-only immutable task chain. Without this, there's no way to _reliably_ rollback or recreate your database.

> Example: (Above) You cannot apply/create 001-teams.js _after_ 002-seats.js has already been applied.
Doing so would force your teammates or database replicas to recreate "the world" in the wrong sequence.
This may not _always_ pose a problem (eg, unrelated tasks) but it often does and so ley enforces this practice.

Lastly, each migration file must have an up and a down task.

These must be exported functions — async okay! — and will receive your pre-installed client driver as its only argument:

`js
exports.up = async function (DB) {
// with pg :: DB === pg.Client
await DB.query(select * from users);

// with postgres :: DB === sql
await DBselect * from users;
}

exports.down = async function (DB) {
// My pre-configured "undo" function
}
`

$3

1) Add ley as one of your package.json scripts; "migrate", for example:

`js
// package.json
{
"scripts": {
"migrate": "ley"
}
}
`

2) Invoke ley up to apply new migrations, or ley down to rollback previous migrations.

`sh
$ npm run migrate up
$ yarn migrate up
`

$3

> Note: See API for documentation

With programmatic/scripting usage, you will not inherit any of ley's CLI tooling, which includes all colors and error formatting. Instead, you must manually catch & handle all thrown Errors.

`js
const ley = require('ley');

const successes = await ley.up({ ... });
`

Config

> TL;DR: The contents of a ley.config.js file (default file name) is irrelevant to ley itself!

A config file is entirely optional since ley assumes that you're providing the correct environment variable(s) for your client driver. However, that may not always be possible. In those instances, a ley.config.js file (default file name) can be used to adjust your driver's connect method – the file contents are passed directly to this function.

For example, if your hosting provider sets non-standard environment variables for the client driver (like Heroku does), you could extract the information and set the standard environment variables:

`js
// ley.config.js
if (process.env.DATABASE_URL) {
const { parse } = require('pg-connection-string');

// Extract the connection information from the Heroku environment variable
const { host, database, user, password } = parse(process.env.DATABASE_URL);

// Set standard environment variables
process.env.PGHOST = host;
process.env.PGDATABASE = database;
process.env.PGUSERNAME = user;
process.env.PGPASSWORD = password;
}
`

Or, if your database provider requires certain SSL connection options to be set in production, you could do that:

`js
// ley.config.js
const options = {};

if (process.env.NODE_ENV === 'production') {
options.ssl = true;
}

module.exports = options;
`

When the config filename uses the .js extension, then ley will attempt to auto-load a .mjs or a .cjs variant of the file if/when the original .js file was not found. This means that, by default, these files are searched (in order):

* ley.config.js
* ley.config.mjs
* ley.config.cjs

ES Modules

As of ley@0.7.0 and Node.js 12+, you may choose to use ECMAScript modules (ESM). There are a few ways to take advantage of this:

> Note: These are _separate_ options. You do not need to perform both items

1. Define "type": "module" in your root package.json file.
This signals the Node.js runtime that _all_ *.js files in the project should be treated as ES modules. With this setting, you may only use CommonJS format within .cjs files.

`js
// package.json
{
"type": "module",
"scripts": {
"migrate": "ley"
}
}
`

2. Author ES modules _only_ in .mjs files.
Regardless of the value of the "type" field (above), .mjs files are always treated as ES modules and .cjs files are always treated as CommonJS.

In terms of ley usage, this means that your config file may use ESM syntax. Similarly, by default, both ley.config.mjs and ley.config.cjs will be auto-loaded, if found and ley.config.js is missing.

`js
// ley.config.mjs
// or w/ "type": "module" ~> ley.config.js
export default {
host: 'localhost',
port: 5432,
// ...
}
`

Finally, migration files may also be written using ESM syntax:

`js
// migrations/000-example.mjs
// or w/ "type": "module" ~> migrations/000-example.js
export async function up(DB) {
// with pg :: DB === pg.Client
await DB.query(select * from users);

// with postgres :: DB === sql
await DBselect * from users;
}

export async function down(DB) {
// My pre-configured "undo" function
}
`

You may generate new migration files in ESM syntax by passing the --esm flag to the ley new command:

`sh
$ ley new todos --esm
#=> migrations/003-todos.mjs

$ cat migrations/003-todos.mjs
#=> export async function up(client) {
#=> }
#=>
#=> export async function down(client) {
#=> }
`

Drivers

Out of the box, ley includes drivers for the following npm packages:

* postgres
* pg
* mysql
* mysql2
* better-sqlite3

When no driver is specified, ley will attempt to autodetect usage of these libraries in the above order.

However, should you need a driver that's not listed – or should you need to override a supplied driver – you may easily do so via a number of avenues:

1) CLI users can add --driver to any command; or
2) Programmatic users can pass opts.driver to any command; or
3) A ley.config.js file can export a special driver config key.

With any of these, if driver is a string then it will be passed through require() automatically. Otherwise, with the latter two, the driver is assumed to be a Driver class and is validated as such.

> Important: All drivers must adhere to the Driver interface!

Typed Migrations

For extra confidence while writing your migration file(s), there are two options:

$3

1. Ensure tsm is installed

2. Run ley with the require option so that tsm can process file(s)

`sh
$ ley -r tsm
# or
$ ley --require tsm
`

$3

You may also use JSDoc annotations throughout your file to achieve (most) of the benefits of TypeScript, but without installing and configuring TypeScript.

`js
/* @param {import('pg').Client} DB /
exports.up = async function (DB) {
await DB.query(...)
}
`

API

> Important: See Options for common options shared all commands.
In this API section, you will only find command-specific options listed.

$3