# knex-schemer

> Schema Build and update tool for knex

Latest version **0.1.17** (published 2016-02-25) · MIT license · 0 weekly downloads

## Install

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

## 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.17 |
| Published | 2016-02-25 |
| First published | 2015-06-18 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 3 |
| Known vulnerabilities | 0 (+2 in 1 direct dependencies) |
| Install scripts | no |
| GitHub stars | 21 |
| Author | Branden Horiuchi |
| Maintainers | vbranden |
| Keywords | knex, schema, builder, sync |

## Links

- npm: https://www.npmjs.com/package/knex-schemer
- Repository: https://github.com/bhoriuchi/knex-schemer
- Issues: https://github.com/bhoriuchi/knex-schemer/issues
- npm.io page: https://npm.io/package/knex-schemer

## Dependencies (3)

- [knex](https://npm.io/package/knex.md) ^0.10.0
- [lodash](https://npm.io/package/lodash.md) ^4.5.1
- [bluebird](https://npm.io/package/bluebird.md) ^3.3.1

## Alternatives

- [@commercetools/sync-actions](https://npm.io/package/@commercetools/sync-actions.md) — 25.1K weekly downloads
- [cwait](https://npm.io/package/cwait.md) — 21.4K weekly downloads
- [@ledgerhq/hw-app-cosmos](https://npm.io/package/@ledgerhq/hw-app-cosmos.md) — 4.2K weekly downloads
- [@financial-times/o-loading](https://npm.io/package/@financial-times/o-loading.md) — 2.8K weekly downloads
- [fa](https://npm.io/package/fa.md) — 185 weekly downloads

## Recent versions

- 0.1.17 (latest) — 2016-02-25
- 0.1.16 — 2015-11-24
- 0.1.15 — 2015-11-23
- 0.1.14 — 2015-11-23
- 0.1.13 — 2015-11-19
- 0.1.12 — 2015-11-05
- 0.1.11 — 2015-11-04
- 0.1.10 — 2015-07-06
- 0.1.9 — 2015-06-30
- 0.1.8 — 2015-06-27
- 0.1.7 — 2015-06-25
- 0.1.6 — 2015-06-25
- 0.1.5 — 2015-06-22
- 0.1.4 — 2015-06-22
- 0.1.3 — 2015-06-22
- … 3 more at https://npm.io/package/knex-schemer/versions

## README

# ☯ knex-schemer
---
`knex-schemer` is a tool that allows you to define a database schema in [`JSON`](http://json.org/) using *Knex-Schemer Definition Format*  or [`KSDF`](https://github.com/bhoriuchi/knex-schemer/wiki/Knex-Schemer-Definition-Format) and create/update/delete that schema using basic transactional functions. This approach allows you to re-use and extend the schema definition in different parts of your application. It also allows you to create and update database tables quickly. As named, the tool requires a [`knex`](http://knexjs.org/) instance to operate

* See the [`WIKI`](https://github.com/bhoriuchi/knex-schemer/wiki) for full documentation
* And the [`Change Log`](https://github.com/bhoriuchi/knex-schemer/wiki/Change-Log) for what's new!

---

## Documentation
---
### API

#### `schemer.convert`( `data`, `schema` )

* `data` [`Object`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) - Data to convert
* `schema` [`Object`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) - Database schema object

removes data columns and tables that do not exist in the schema and returns a converted data object

#### `schemer.convertAndLoad`( `data`, `schema`, [`transaction`] )

* `data` [`Object`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) - Data to convert
* `schema` [`Object`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) - Database schema object
* [`transaction`] [`Transaction`](http://knexjs.org/#Transactions) - transaction to use

converts the data object and loads the data into the database

#### `schemer.drop`( `schema`, [`transaction`] )

* `schema` [`Object`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) - Database schema object
* [`transaction`] [`Transaction`](http://knexjs.org/#Transactions) - transaction to use

drops all tables defined in the schema object

#### `schemer.sync`( `schema`, [`transaction`] )

* `schema` [`Object`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) - Database schema object
* [`transaction`] [`Transaction`](http://knexjs.org/#Transactions) - transaction to use

creates the tables defined in the schema object if they do not exist. If the tables do exist, the row definitions are updated to reflect the schema object. Table alteration is limited to what is supported by `knex.js`

#### `schemer.dump`( `options` )

* `options` [`Object`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) - Hash of options or a schema object
  * `schema` [`Object`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) - Schema object
  * [`tables`] [`String[]`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) - Array of table names to dump 

dumps database data into a data object that can be used by `schemer.load()`


<br>

---

### Examples
---
#### Full define, drop, create, and load example
Defines a schema and dataset, then drops any existing tables, creates them, and loads the data
```js
// require the module
var schemer = require('knex-schemer')(knex);
var types   = schemer.constants.types;

// create a schema
var schema = {

    user: {
        id: { type: type.integer, primary: true, increments: true },
        name: { type: type.string },
        username: { type: type.string, size: 32 },
        email: { type: type.string }
    },
    credential: {
        id: { type: type.integer, primary: true, increments: true },
        name: { type: type.string },
        username: { type: type.string },
        encryptedKey: { type: type.string }
    }
};

// define data to load
var data = {
    user: [
        {
            id: 1,
            name: 'Jack Shepard',
            username: 'jshepard',
            email: 'thechosenone@theisland.org'
        },
        {
            id: 2,
            name: 'Kate Austen',
            username: 'kausten',
            email: 'kateplusfate@theisland.org'
        }
    ],
    credential: [
        {
            id: 1,
            name: 'swan',
            username: 'operator',
            encryptedKey: '4815162342'
        }
    ]
};

// drop all tables
schemer.drop(schema).then(function() {

    // create or update all tables
    return schemer.sync(schema).then(function() {

        // convert and load the data
        return schemer.convertAndLoad(data, schema).then(function() {
            // post load operations
        });
    });
});
```

#### Full transactional drop, create, and load example
Borrowing the schema and data from the first example, the operations can share the same transaction using `knex.transaction()`

```js
// create a knex transaction
knex.transaction(function(trx) {
    // pass the transaction as the last argument in each method
    schemer.drop(schema, trx).then(function() {
        return schemer.sync(schema, trx).then(function(result) {
            return schemer.convertAndLoad(data, schema, trx);
        });
    });
})
.then(function() {
    // do something on success
})
.catch(function(e) {
    // do something on error
});
```

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