# knex-automigrate

> Table schema based database migration tool, built on top of the knex.js

Latest version **0.2.0** (published 2026-05-21) · MIT license · 0 weekly downloads

## Install

```sh
npm install knex-automigrate
pnpm add knex-automigrate
yarn add knex-automigrate
bun add knex-automigrate
```

Provides the command `knex-automigrate`.

## Health

**Score 55/100 (C)** — status: active.

Positive: has types; no vulnerabilities; high quality score.

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

## Facts

| | |
|---|---|
| Version | 0.2.0 |
| Published | 2026-05-21 |
| First published | 2017-05-16 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 5 |
| Unpacked size | 67.9 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 10 |
| Author | why2pac |
| Maintainers | why2pac |
| Keywords | nodejs, knexjs, database, orm, table, migration, typescript |

## Links

- npm: https://www.npmjs.com/package/knex-automigrate
- Repository: https://github.com/why2pac/knex-automigrate
- Homepage: https://github.com/why2pac/knex-automigrate#readme
- Issues: https://github.com/why2pac/knex-automigrate/issues
- npm.io page: https://npm.io/package/knex-automigrate

## Dependencies (5)

- [chalk](https://npm.io/package/chalk.md) ^4.1.2
- [liftoff](https://npm.io/package/liftoff.md) ^5.0.1
- [tildify](https://npm.io/package/tildify.md) ^2.0.0
- [minimist](https://npm.io/package/minimist.md) ^1.2.8
- [commander](https://npm.io/package/commander.md) ^14.0.3

## Alternatives

- [mobx-react](https://npm.io/package/mobx-react.md) — 2.8M weekly downloads
- [rc-tree](https://npm.io/package/rc-tree.md) — 2.6M weekly downloads
- [@react-oauth/google](https://npm.io/package/@react-oauth/google.md) — 1.3M weekly downloads
- [@wagmi/connectors](https://npm.io/package/@wagmi/connectors.md) — 877.0K weekly downloads
- [vee-validate](https://npm.io/package/vee-validate.md) — 836.4K weekly downloads

## Recent versions

- 0.2.0 (latest) — 2026-05-21
- 0.1.8 — 2025-04-08
- 0.1.7 — 2025-02-24
- 0.1.6 — 2025-02-24
- 0.1.5 — 2025-02-21
- 0.1.4 — 2024-11-26
- 0.1.3 — 2024-11-26
- 0.1.2 — 2024-03-28
- 0.1.1 — 2022-06-15
- 0.1.0 — 2021-01-11
- 0.0.9 — 2020-08-11
- 0.0.8 — 2018-12-30
- 0.0.7 — 2018-08-27
- 0.0.6 — 2018-08-26
- 0.0.5 — 2017-11-07
- … 4 more at https://npm.io/package/knex-automigrate/versions

## README

knex-automigrate
================

[![NPM Version](https://img.shields.io/npm/v/knex-automigrate.svg)](https://npmjs.org/package/knex-automigrate)
[![NPM Downloads](https://img.shields.io/npm/dm/knex-automigrate.svg)](https://npmjs.org/package/knex-automigrate)

Table schema based database migration tool, built on top of [knex.js](http://knexjs.org).

Define your table schema once and let knex-automigrate handle CREATE, ALTER, and DROP operations automatically — no numbered migration files needed.

- Written in **TypeScript** with full type declarations included
- Migration schema file name must start with `table_` or `view_`
- Currently supported dialects for index migration: `mysql`, `mysql2`

## Installation

```bash
$ npm install knex-automigrate
```

For CLI usage (global install):

```bash
$ npm install knex-automigrate -g
```

## Usage

### Before (traditional database migration with knex.js)

```bash
$ knex migrate:make create_users_table
```

```javascript
// 201701010000_create_users_table.js
exports.up = function(knex, Promise) {
  return Promise.all([
    knex.schema.createTableIfNotExists('users', function(table) {
      table.increments('user_id').unsigned().comment('PK');
      table.string('email', 128).notNullable().comment('E-Mail');
      table.string('nickname', 128).notNullable().comment('Name');
    })
  ]);
};
```

```bash
$ knex migrate:latest
```

```bash
$ knex migrate:make alter_users_table
```

```javascript
// 201701010000_alter_users_table.js
exports.up = function(knex, Promise) {
  return Promise.all([
    knex.schema.alterTable('users', function(table) {
      table.dropColumn('nickname');
      table.string('email', 64).notNullable().comment('E-Mail').alter();
      table.string('name', 64).notNullable().comment('Name');
    })
  ]);
};
```

```bash
$ knex migrate:latest
```

Migration files are,

```
App
　├─ migrations
　│　　├─ 201701010000_create_users_table.js
　│　　└─ 201701010000_alter_users_table.js
　└─ knexfile.js
```

### After (database migration with knex-automigrate)

Migration files are named with `table_` or `view_` prefix. The prefix determines whether the file defines table schemas or view schemas.

```javascript
// table_users.js
exports.auto = function(migrator, knex) {
  return [
    migrator('users', function(table) {
      table.increments('user_id').unsigned().comment('PK');
      table.string('email', 64).notNullable().comment('E-Mail');
      table.string('name', 64).notNullable().comment('Name');
    }),
  ];
};
```

```javascript
// view_users.js
exports.auto = function(migrator, knex) {
  return [
    migrator('user_information', (view) => {
      // If view.columns() is missing,
      // the columns will default to those defined in the 'select()' statement.
      view.as(knex('users').select('user_id', 'email', 'name'));
    }),
  ];
};
```

```bash
$ knex-automigrate migrate:auto
```

Migration files are,

```
App
　├─ migrations
　│　　├─ table_users.js
　│　　└─ view_users.js
　└─ knexfile.js
```

Simply edit the schema file and run `migrate:auto` again — columns are added, altered, or dropped automatically to match the definition.

### CLI

```
Usage: knex-automigrate [options] [command]

Commands:
  migrate:auto           Run all migration table schemas.

Options:
  -V, --version      output the version number
  --debug            Run with debugging.
  --safe             Run as safe mode, which does not delete existing columns.
  --knexfile [path]  Specify the knexfile path.
  --cwd [path]       Specify the working directory.
  --env [name]       environment, default: process.env.NODE_ENV || development
  -h, --help         output usage information
```

## Programmatic Usage

```javascript
const Automigrate = require('knex-automigrate');

await Automigrate({
  config: {
    client: 'mysql2',
    connection: {
      host: '127.0.0.1',
      port: 3306,
      database: 'my_database',
      user: 'root',
      password: null,
    },
    safe: false, // set true to prevent dropping existing columns
  },
  cwd: __dirname,           // directory to scan for table_*.js / view_*.js files
  verbose: true,            // set false to suppress console output
  tables: (migrator, knex) => [
    migrator('users', (table) => {
      table.increments('user_id').unsigned().comment('PK');
      table.string('email', 128).notNullable().comment('E-Mail');
      table.string('name', 64).notNullable().comment('Name');
      table.datetime('created_at').notNullable().defaultTo(knex.fn.now()).comment('Created at');

      table.primary(['user_id']);
      table.unique(['email'], 'uk_users_email');
      table.index(['created_at'], 'idx_users_created_at');
    }),
  ],
  views: (migrator, knex) => [
    migrator('user_summary', (view) => {
      view.as(knex('users').select('user_id', 'email', 'name'));
    }),
  ],
});
```

### TypeScript

```typescript
import Automigrate from 'knex-automigrate';

await Automigrate({
  config: {
    client: 'mysql2',
    connection: { host: '127.0.0.1', database: 'my_database', user: 'root', password: null },
  },
  tables: (migrator, knex) => [
    migrator('users', (table) => {
      table.increments('user_id').unsigned().comment('PK');
      table.string('email', 128).notNullable().comment('E-Mail');
    }),
  ],
});
```

### Options

| Option | Type | Description |
|--------|------|-------------|
| `config` | `Knex.Config & { safe?: boolean }` | Knex configuration. Set `safe: true` to prevent dropping columns. |
| `cwd` | `string` | Directory to scan for `table_*.js` / `view_*.js` migration files. |
| `verbose` | `boolean` | Enable/disable console output. Default: `true`. |
| `tables` | `(migrator, knex) => MigrationEntry[]` | Inline table definitions (in addition to file-based). |
| `views` | `(migrator, knex) => MigrationEntry[]` | Inline view definitions (in addition to file-based). |

### Supported index types

```javascript
// Primary key
table.primary(['id']);

// Unique key
table.unique(['email'], 'uk_users_email');

// Regular index
table.index(['status'], 'idx_users_status');

// Fulltext index
table.index(['title'], 'ft_articles_title', { indexType: 'FULLTEXT' });

// Fulltext index with ngram parser
table.index(['body'], 'ft_articles_body', { indexType: 'FULLTEXT', parser: 'ngram' });
```

## How it works

1. Reads the current table schema from the database (`SHOW CREATE TABLE`)
2. Compares it with the defined schema
3. Automatically generates and runs the appropriate DDL:
   - **New table** → `CREATE TABLE`
   - **New column** → `ALTER TABLE ADD COLUMN`
   - **Changed column** → `ALTER TABLE MODIFY COLUMN`
   - **Removed column** → `ALTER TABLE DROP COLUMN` (unless `safe: true`)
   - **New index** → `CREATE INDEX` / `ALTER TABLE ADD INDEX`
   - **View** → `CREATE OR REPLACE VIEW`

## Dependencies

* [knex.js](http://knexjs.org) (peer dependency, `^3.1.0`)

## License

[MIT License](http://www.opensource.org/licenses/mit-license.php)

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