Skip to content

public / sequelize

Go to a project

不要怂，就是干，撸起袖子干！

Commit 4615d7f7 by Sushant Committed by GitHub
Options

docs(migration): explain how to use migrations (#8319) 

* docs(migration): explain how to use migrations

* docs(migration): storage, .sequelizerc

* docs(migrations): dynamic config, storage, ssl, url option, using env varibales

* docs(migrations): seeds and production tips

* docs: simplify queryInterface intro

* docs: QueryInterface API + seeding docs + styling

* docs: expose describe table to public
1 parent 0af04063
Inline Side-by-side
Showing with 716 additions and 307 deletions
docs/css/theme.css
...@@ -15,10 +15,16 @@ ...@@ -15,10 +15,16 @@
color: #ffffff; color: #ffffff;
} }
.manual-toc-root ul li a { .manual-toc-root ul li {
margin-top: 0.5em;
margin-bottom: 0.5em;
font-weight: normal !important; font-weight: normal !important;
} }
.manual-toc .indent-h1 {
margin: 0.5em 0 0 .5em;
}
/* Class Summay*/ /* Class Summay*/
.summary thead tr { .summary thead tr {
background-color: #074278; background-color: #074278;
......
docs/migrations.md
# Migrations # Migrations
Sequelize `2.0.0` introduces a new CLI which is based on [gulp][0] and combines [sequelize-cli][1] and [gulp-sequelize][2]. The CLI ships support for migrations and project bootstrapping. With migrations you can transfer your existing database into another state and vice versa: Those state transitions are saved in migration files, which describe the way how to get to the new state and how to revert the changes in order to get back to the old state. Just like you use Git / SVN to manage changes in your source code, you can use migrations to keep track of changes to database. With migrations you can transfer your existing database into another state and vice versa: Those state transitions are saved in migration files, which describe the way how to get to the new state and how to revert the changes in order to get back to the old state.
You will need [Sequelize CLI][0]. The CLI ships support for migrations and project bootstrapping.
## The CLI ## The CLI
In order to use the CLI you need to install the respective package: ### Installing CLI
Lets start with installing CLI, you can find instructions [here][0]. Most preferred way is installing locally like this
```bash ```bash
$ npm install --save sequelize-cli $ npm install --save sequelize-cli
``` ```
As with any npm package, you can use the global flag (`-g`) to install the CLI globally. If you have installed the CLI without the global flag, use `node_modules/.bin/sequelize [command]` instead of `sequelize [command]`. ### Bootstrapping
To create an empty project you will need to execute `init` command
```bash
$ node_modules/.bin/sequelize init
```
This will create following folders
1) `config`, contains config file, which tells CLI how to connect with database
2) `models`, contains all models for your project
3) `migrations`, contains all migration files
4) `seeders`, contains all seed files
#### Configuration
Before continuing further we will need to tell CLI how to connect to database. To do that lets open default config file `config/config.json`. It looks something like this
```json
{
development: {
username: 'root',
password: null,
database: 'database_development',
host: '127.0.0.1',
dialect: 'mysql'
},
test: {
username: 'root',
password: null,
database: 'database_test',
host: '127.0.0.1',
dialect: 'mysql'
},
production: {
username: 'root',
password: null,
database: 'database_production',
host: '127.0.0.1',
dialect: 'mysql'
}
}
```
Now edit this file and set correct database credentials and dialect.
**Note:** _If your database doesn't exists yet, you can just call `db:create` command. With proper access it will create that database for you._
### Creating first Model (and Migration)
Once you have properly configured CLI config file you are ready to create you first migration. Its as simple as executing a simple command.
We will use `model:generate` command. This command requires two options
1) `name`, Name of the model
2) `attributes`, List of model attributes
Lets create a model named `User`
```bash
$ node_modules/.bin/sequelize model:generate --name User --attributes firstName:string,lastName:string,email:string
```
This will do following
The CLI currently supports the following commands: 1) Create a model file `user` in `models` folder
2) Create a migration file with name like `XXXXXXXXXXXXXX-create-user.js` in `migrations` folder
**Note:** _Sequelize will only use Model files, its the table representation. On other hand migration file is a change in that model or more specifically that table, used by CLI. Treat migrations like a commit or a log for some change in database._
### Running Migrations
Now till this step CLI haven't inserted anything into database. We have just created required model and migration files for our first model `User`. Now to actually create that table in database you need to run `db:migrate` command.
```bash ```bash
$ sequelize db:migrate # Run pending migrations. $ node_modules/.bin/sequelize db:migrate
$ sequelize db:migrate:undo # Revert the last migration run.
$ sequelize help # Display this help text.
$ sequelize init # Initializes the project.
$ sequelize migration:create # Generates a new migration file.
$ sequelize version # Prints the version number.
``` ```
Further and more detailed information about the available commands This command will execute these steps
can be obtained via the help command:
1) It will ensure a table called `SequelizeMeta` in database. This table is used to record which migration have ran on current database
2) Start looking for any migration files which haven't ran yet. This is possible by checking `SequelizeMeta` table. In this case it will run `XXXXXXXXXXXXXX-create-user.js` migration, which we created in last step.
3) Creates a table called `User` with all columns as specified in its migration file.
### Undoing Migrations
Now our table has been created and saved in database. With migration you can revert to old state by just running a command.
You can use `db:migrate:undo`, this command will revert most recent migration.
```bash ```bash
$ sequelize help:init $ node_modules/.bin/sequelize db:migrate:undo
$ sequelize help:db:migrate
$ sequelize help:db:migrate:undo
# etc
``` ```
The latter one for example will print out the following output: You can revert back to initial state by undoing all migrations with `db:migrate:undo:all` command. You can also revert back to a specific migration by passing its name in `--to` option.
```bash ```bash
Sequelize [CLI: v0.0.2, ORM: v1.7.5] $ node_modules/.bin/sequelize db:migrate:undo:all --to XXXXXXXXXXXXXX-create-posts.js
```
### Creating First Seed
Suppose we want to insert some data into few tables by default. If we follow up on previous example we can consider creating a demo user for `User` table.
COMMANDS To manage all data migrations you can use seeders. Seed files are some change in data that can be used to populate database table with sample data or test data.
sequelize db:migrate:undo -- Revert the last migration run.
DESCRIPTION Lets create a seed file which will add a demo user to our `User` table.
Revert the last migration run.
OPTIONS ```bash
--env The environment to run the command in. Default: development $ node_modules/.bin/sequelize seed:generate --name demo-user
--options-path The path to a JSON file with additional options. Default: none
--coffee Enables coffee script support. Default: false
--config The path to the config file. Default: config/config.json
``` ```
## Skeleton This command will create a seed file in `seeders` folder. File name will look something like `XXXXXXXXXXXXXX-demo-user.js`, It follows same `up / down` semantics like migration files.
The following skeleton shows a typical migration file. All migrations are expected to be located in a folder called `migrations` at the very top of the project. The sequelize binary can generate a migration skeleton. See the above section for more details. Now we should edit this file to insert demo user to `User` table.
```js ```js
'use strict';
module.exports = { module.exports = {
up: (queryInterface, Sequelize) => { up: (queryInterface, Sequelize) => {
// logic for transforming into the new state return queryInterface.bulkInsert('User', [{
firstName: 'John',
lastName: 'Doe',
email: 'demo@demo.com'
}], {});
}, },
 
down: (queryInterface, Sequelize) => { down: (queryInterface, Sequelize) => {
// logic for reverting the changes return queryInterface.bulkDelete('User', null, {});
} }
} };
``` ```
The passed `queryInterface` object can be used to modify the database. The `Sequelize` object stores the available data types such as `STRING` or `INTEGER`. Function `up` or `down` should return a `Promise`. Here is some code: ### Running Seeds
In last step you have create a seed file. Its still not committed to database. To do that we need to run a simple command.
```js ```bash
module.exports = { $ node_modules/.bin/sequelize db:seed
up: (queryInterface, Sequelize) => {
return queryInterface.dropAllTables();
}
}
``` ```
The available methods of the queryInterface object are the following. This will execute that seed file and you will have a demo user inserted into `User` table.
**Note:** _Seeders execution is not stored anywhere unlike migration which use `SequelizeMeta` table. If you wish to override this please read `Storage` section_
## Functions ### Undoing Seeds
Seeders if they are using any storage can be undo. There are two commands available for that
Using the `queryInterface` object described before, you will have access to most of already introduced functions. Furthermore there are some other methods, which are designed to actually change the database schema. If you wish to undo most recent seed
### createTable(tableName, attributes, options) ```bash
node_modules/.bin/sequelize db:seed:undo
```
If you wish to undo all seeds
This method allows creation of new tables. It is allowed to pass simple or complex attribute definitions. You can define the encoding of the table and the table's engine via options ```bash
node_modules/.bin/sequelize db:migrate:undo:all
```
## Advance Topics
### Migration Skeleton
The following skeleton shows a typical migration file.
```js ```js
queryInterface.createTable( module.exports = {
'nameOfTheNewTable', up: (queryInterface, Sequelize) => {
{ // logic for transforming into the new state
id: {
type: Sequelize.INTEGER,
primaryKey: true,
autoIncrement: true
},
createdAt: {
type: Sequelize.DATE
},
updatedAt: {
type: Sequelize.DATE
}, },
attr1: Sequelize.STRING,  
attr2: Sequelize.INTEGER, down: (queryInterface, Sequelize) => {
attr3: { // logic for reverting the changes
}
}
```
The passed `queryInterface` object can be used to modify the database. The `Sequelize` object stores the available data types such as `STRING` or `INTEGER`. Function `up` or `down` should return a `Promise`. Lets look at an example
```js
module.exports = {
up: (queryInterface, Sequelize) => {
return queryInterface.createTable('Person', {
name: Sequelize.STRING,
isBetaMember: {
type: Sequelize.BOOLEAN, type: Sequelize.BOOLEAN,
defaultValue: false, defaultValue: false,
allowNull: false allowNull: false
},
//foreign key usage
attr4: {
type: Sequelize.INTEGER,
references: {
model: 'another_table_name',
key: 'id'
},
onUpdate: 'cascade',
onDelete: 'cascade'
} }
});
}, },
{ down: (queryInterface, Sequelize) => {
engine: 'MYISAM', // default: 'InnoDB' return queryInterface.dropTable('Person');
charset: 'latin1', // default: null
schema: 'public' // default: public, PostgreSQL only.
} }
) }
``` ```
### dropTable(tableName, options) ### The `.sequelizerc` File
This is a special configuration file. It let you specify various options that you would usually pass as arguments to CLI. Some scenarios where you can use it.
This method allows deletion of an existing table. 1) You want to override default path to `migrations`, `models`, `seeders` or `config` folder.
2) You want to rename `config.json` to something else like `database.json`
```js And a whole lot more. Let see how you can use this file for custom configuration.
queryInterface.dropTable('nameOfTheExistingTable')
```
### dropAllTables(options) For starters lets create an empty file in root directory of your project.
This method allows deletion of all existing tables in the database. ```bash
$ touch .sequelizerc
```
Now lets work with an example config.
```js ```js
queryInterface.dropAllTables() const path = require('path');
module.exports = {
'config': path.resolve('config', 'database.json'),
'models-path': path.resolve('db', 'models'),
'seeders-path': path.resolve('db', 'seeders'),
'migrations-path': path.resolve('db', 'migrations')
}
``` ```
### renameTable(before, after, options) With this config you are telling CLI to
This method allows renaming of an existing table. 1) Use `config/database.json` file for config settings
2) Use `db/models` as models folder
3) Use `db/seeders` as seeders folder
4) Use `db/migrations` as migrations folder
```js ### Dynamic Configuration
queryInterface.renameTable('Person', 'User') Configuration file is by default a JSON file called `config.json`. But sometimes you want to execute some code or access environment variables which is not possible in JSON files.
```
### showAllTables(options) Sequelize CLI can read from both `JSON` and `JS` files. This can be setup with `.sequelizerc` file. Let see how
This method returns the name of all existing tables in the database. First you need to create a `.sequelizerc` file in root folder of your project. This file should override config path to a `JS` file. Like this
```js ```js
queryInterface.showAllTables().then(tableNames => {}) const path = require('path');
module.exports = {
'config': path.resolve('config', 'config.js')
}
``` ```
### describeTable(tableName, options) Now Sequelize CLI will load `config/config.js` for getting configuration options. Since this is a JS file you can have any code executed and export final dynamic configuration file.
This method returns an array of hashes containing information about all attributes in the table. An example of `config/config.js` file
```js ```js
queryInterface.describeTable('Person').then(attributes => { const fs = require('fs');
/*
attributes will be something like: module.exports = {
  development: {
{ username: 'database_dev',
name: { password: 'database_dev',
type: 'VARCHAR(255)', // this will be 'CHARACTER VARYING' for pg! database: 'database_dev',
allowNull: true, host: '127.0.0.1',
defaultValue: null dialect: 'mysql'
}, },
isBetaMember: { test: {
type: 'TINYINT(1)', // this will be 'BOOLEAN' for pg! username: 'database_test',
allowNull: false, password: null,
defaultValue: false database: 'database_test',
host: '127.0.0.1',
dialect: 'mysql'
},
production: {
username: process.env.DB_USERNAME,
password: process.env.DB_PASSWORD,
database: process.env.DB_NAME,
host: process.env.DB_HOSTNAME,
dialect: 'mysql',
dialectOptions: {
ssl: {
ca: fs.readFileSync(__dirname + '/mysql-ca-master.crt')
}
} }
} }
*/ };
})
``` ```
### addColumn(tableNameOrOptions, attributeName, dataTypeOrOptions, options) ### Using Environment Variables
With CLI you can directly access the environment variables inside the `config/config.js`. You can use `.sequelizerc` to tell CLI to use `config/config.js` for configuration. This is explained in last section.
This method allows adding columns to an existing table. The data type can be simple or complex. Then you can just expose file with proper environment variables.
```js ```js
queryInterface.addColumn( module.exports = {
'nameOfAnExistingTable', development: {
'nameOfTheNewAttribute', username: 'database_dev',
Sequelize.STRING password: 'database_dev',
) database: 'database_dev',
  host: '127.0.0.1',
// or dialect: 'mysql'
  },
queryInterface.addColumn( test: {
'nameOfAnExistingTable', username: process.env.CI_DB_USERNAME,
'nameOfTheNewAttribute', password: process.env.CI_DB_PASSWORD,
{ database: process.env.CI_DB_NAME,
type: Sequelize.STRING, host: '127.0.0.1',
allowNull: false dialect: 'mysql'
},
production: {
username: process.env.PROD_DB_USERNAME,
password: process.env.PROD_DB_PASSWORD,
database: process.env.PROD_DB_NAME,
host: process.env.PROD_DB_HOSTNAME,
dialect: 'mysql'
} }
) ```
// or with first attribute to put the column at the beginning of the table ### Specifying Dialect Options
// currently supports only in MySQL Sometime you want to specify a dialectOption, if its a general config you can just add it in `config/config.json`. Sometime you want to execute some code to get dialectOptions, you should use dynamic config file for those cases.
queryInterface.addColumn( ```json
'nameOfAnExistingTable', {
'nameOfTheNewAttribute', "production": {
{ "dialect":"mysql",
type: Sequelize.STRING, "dialectOptions": {
first: true "bigNumberStrings": true
} }
)
// or with after attribute to put the column after a specific column
// currently supports only in MySQL
queryInterface.addColumn(
'nameOfAnExistingTable',
'nameOfTheNewAttribute',
{
type: Sequelize.STRING,
after: 'nameOfAnExistingColumn'
} }
) }
// or with an explicit schema:
queryInterface.addColumn({
tableName: 'Person',
schema: 'public'
},
'signature',
Sequelize.STRING
)
``` ```
### removeColumn(tableNameOrOptions, attributeName, options) ### Production Usages
Some tips around using CLI and migration setup in production environment.
This method allows deletion of a specific column of an existing table. 1) Use environment variables for config settings. This is better achieved with dynamic configuration. A sample production safe configuration may look like.
```js ```js
queryInterface.removeColumn('Person', 'signature') const fs = require('fs');
// or with an explicit schema: module.exports = {
development: {
queryInterface.removeColumn({ username: 'database_dev',
tableName: 'Person', password: 'database_dev',
schema: 'public' database: 'database_dev',
}, 'signature'); host: '127.0.0.1',
``` dialect: 'mysql'
},
### changeColumn(tableName, attributeName, dataTypeOrOptions, options) test: {
username: 'database_test',
This method changes the meta data of an attribute. It is possible to change the default value, allowance of null or the data type. Please make sure, that you are completely describing the new data type. password: null,
database: 'database_test',
```js host: '127.0.0.1',
queryInterface.changeColumn( dialect: 'mysql'
'nameOfAnExistingTable', },
'nameOfAnExistingAttribute', production: {
{ username: process.env.DB_USERNAME,
type: Sequelize.FLOAT, password: process.env.DB_PASSWORD,
allowNull: false, database: process.env.DB_NAME,
defaultValue: 0.0 host: process.env.DB_HOSTNAME,
dialect: 'mysql',
dialectOptions: {
ssl: {
ca: fs.readFileSync(__dirname + '/mysql-ca-master.crt')
}
}
} }
) };
``` ```
### renameColumn(tableName, attrNameBefore, attrNameAfter, options) Our goal is to use environment variables for various database secrets and not accidentally checkout them to source control.
This methods allows renaming attributes. ### Storage
There are three types of storage that you can use: `sequelize`, `json`, and `none`.
```js - `sequelize` : stores migrations and seeds in a table on the sequelize database
queryInterface.renameColumn('Person', 'signature', 'sig') - `json` : stores migrations and seeds on a json file
``` - `none` : does not store any migration/seed
### addIndex(tableName, attributes, options)
This methods creates indexes for specific attributes of a table. The index name will be automatically generated if it is not passed via in the options (see below). #### Migration Storage
By default the CLI will create a table in your database called `SequelizeMeta` containing an entry
for each executed migration. To change this behavior, there are three options you can add to the
configuration file. Using `migrationStorage`, you can choose the type of storage to be used for
migrations. If you choose `json`, you can specify the path of the file using `migrationStoragePath`
or the CLI will write to the file `sequelize-meta.json`. If you want to keep the information in the
database, using `sequelize`, but want to use a different table, you can change the table name using
`migrationStorageTableName`.
```js ```json
// This example will create the index person_firstname_lastname {
queryInterface.addIndex('Person', ['firstname', 'lastname']) "development": {
"username": "root",
// This example will create a unique index with the name SuperDuperIndex using the optional 'options' field. "password": null,
// Possible options: "database": "database_development",
// - indicesType: UNIQUE|FULLTEXT|SPATIAL "host": "127.0.0.1",
// - indexName: The name of the index. Default is __ "dialect": "mysql",
// - parser: For FULLTEXT columns set your parser
// - indexType: Set a type for the index, e.g. BTREE. See the documentation of the used dialect
// - logging: A function that receives the sql query, e.g. console.log
// - where: A hash of attributes to limit your index(Filtered Indexes - MSSQL & PostgreSQL only)
queryInterface.addIndex(
'Person',
['firstname', 'lastname'],
{
indexName: 'SuperDuperIndex',
indicesType: 'UNIQUE'
}
)
queryInterface.addIndex(
'Person',
['firstname', 'lastname'],
{
where: {
lastname: {
$ne: null
}
}
}
)
```
### removeIndex(tableName, indexNameOrAttributes, options) // Use a different storage type. Default: sequelize
"migrationStorage": "json",
This method deletes an existing index of a table. // Use a different file name. Default: sequelize-meta.json
"migrationStoragePath": "sequelizeMeta.json",
```js // Use a different table name. Default: SequelizeMeta
queryInterface.removeIndex('Person', 'SuperDuperIndex') "migrationStorageTableName": "sequelize_meta"
  }
// or }
 
queryInterface.removeIndex('Person', ['firstname', 'lastname'])
``` ```
### addConstraint(tableName, attributes, options) **Note:** _The `none` storage is not recommended as a migration storage. If you decide to use it, be
This method adds a new constraint of the specified type. aware of the implications of having no record of what migrations did or didn't run._
- tableName - Name of the table to add the constraint on
- attributes - Array of column names to apply the constraint over #### Seed Storage
- options - An object to define the constraint name, type etc. By default the CLI will not save any seed that is executed. If you choose to change this behavior (!),
you can use `seederStorage` in the configuration file to change the storage type. If you choose `json`,
Avalable options: you can specify the path of the file using `seederStoragePath` or the CLI will write to the file
- type - Type of constraint. One of the values in available constraints(case insensitive) `sequelize-data.json`. If you want to keep the information in the database, using `sequelize`, you can
- name - Name of the constraint. If not specifed, sequelize automatically creates a named constraint based on constraint type, table & column names specify the table name using `seederStorageTableName`, or it will default to `SequelizeData`.
- defaultValue - The value for the default constraint
- where - Where clause/expression for the CHECK constraint ```json
- references - Object specifying target table, column name to create foreign key constraint {
- references.table - Target table name or table "development": {
- references.field - Target column name "username": "root",
Available constraints: "password": null,
- UNIQUE "database": "database_development",
- DEFAULT (MSSQL only) "host": "127.0.0.1",
- CHECK (MySQL - Ignored by the database engine ) "dialect": "mysql",
- FOREIGN KEY // Use a different storage. Default: none
- PRIMARY KEY "seederStorage": "json",
// Use a different file name. Default: sequelize-data.json
```js "seederStoragePath": "sequelizeData.json",
//UNIQUE // Use a different table name. Default: SequelizeData
queryInterface.addConstraint('Users', ['email'], { "seederStorageTableName": "sequelize_data"
type: 'unique',
name: 'custom_unique_constraint_name'
});
//CHECK
queryInterface.addConstraint('Users', ['roles'], {
type: 'check',
where: {
roles: ['user', 'admin', 'moderator', 'guest']
} }
}); }
//Default - MSSQL only
queryInterface.addConstraint('Users', ['roles'], {
type: 'default',
defaultValue: 'guest'
});
//Primary Key
queryInterface.addConstraint('Users', ['username'], {
type: 'primary key',
name: 'custom_primary_constraint_name'
});
//Foreign Key
queryInterface.addConstraint('Posts', ['username'], {
type: 'FOREIGN KEY',
name: 'custom_fkey_constraint_name',
references: { //Required field
table: 'target_table_name',
field: 'target_column_name'
},
onDelete: 'cascade',
onUpdate: 'cascade'
});
``` ```
### removeConstraint(tableName, constraintName, options) ### Configuration Connection String
As an alternative to the `--config` option with configuration files defining your database, you can
use the `--url` option to pass in a connection string. For example:
This method deletes an existing constraint of a table ```bash
$ node_modules/.bin/sequelize db:migrate --url 'mysql://root:password@mysql_host.com/database_name'
```
```js ### Connecting over SSL
queryInterface.removeConstraint('Users', 'my_constraint_name'); Ensure ssl is specified in both `dialectOptions` and in the base config.
```json
{
"production": {
"dialect":"postgres",
"ssl": true,
"dialectOptions": {
"ssl": true
}
}
}
``` ```
### showConstraint(tableName, options) ### Programmatic use
Sequelize has a [sister library][1] for programmatically handling execution and logging of migration tasks.
Lists all the constraints on the given table.
```js ## Query Interface
queryInterface.showConstraint('Users');
// Returns array of objects/constraints
```
## Programmatic use Using `queryInterface` object described before you can change database schema. To see full list of public methods it supports check [QueryInterface API][2]
Sequelize has a [sister library](https://github.com/sequelize/umzug) for programmatically handling execution and logging of migration tasks.
[0]: http://gulpjs.com/ [0]: https://github.com/sequelize/cli
[1]: https://github.com/sequelize/cli [1]: https://github.com/sequelize/umzug
[2]: https://github.com/sequelize/gulp-sequelize [2]: /class/lib/query-interface.js~QueryInterface.html
lib/query-interface.js
...@@ -12,8 +12,8 @@ const QueryTypes = require('./query-types'); ...@@ -12,8 +12,8 @@ const QueryTypes = require('./query-types');
/** /**
* The interface that Sequelize uses to talk to all databases * The interface that Sequelize uses to talk to all databases
*
* @class QueryInterface * @class QueryInterface
* @private
*/ */
class QueryInterface { class QueryInterface {
constructor(sequelize) { constructor(sequelize) {
...@@ -21,18 +21,41 @@ class QueryInterface { ...@@ -21,18 +21,41 @@ class QueryInterface {
this.QueryGenerator = this.sequelize.dialect.QueryGenerator; this.QueryGenerator = this.sequelize.dialect.QueryGenerator;
} }
/**
* Creates a schema
*
* @param {String} schema Schema name to create
* @param {Object} [options] Query options
*
* @return {Promise}
*/
createSchema(schema, options) { createSchema(schema, options) {
options = options || {}; options = options || {};
const sql = this.QueryGenerator.createSchema(schema); const sql = this.QueryGenerator.createSchema(schema);
return this.sequelize.query(sql, options); return this.sequelize.query(sql, options);
} }
/**
* Drops a schema
*
* @param {String} schema Schema name to create
* @param {Object} [options] Query options
*
* @return {Promise}
*/
dropSchema(schema, options) { dropSchema(schema, options) {
options = options || {}; options = options || {};
const sql = this.QueryGenerator.dropSchema(schema); const sql = this.QueryGenerator.dropSchema(schema);
return this.sequelize.query(sql, options); return this.sequelize.query(sql, options);
} }
/**
* Drop all schemas
*
* @param {Object} [options] Query options
*
* @return {Promise}
*/
dropAllSchemas(options) { dropAllSchemas(options) {
options = options || {}; options = options || {};
...@@ -43,8 +66,14 @@ class QueryInterface { ...@@ -43,8 +66,14 @@ class QueryInterface {
} }
} }
/**
* Show all schemas
*
* @param {Object} [options] Query options
*
* @return {Promise<Array>}
*/
showAllSchemas(options) { showAllSchemas(options) {
options = _.assign({}, options, { options = _.assign({}, options, {
raw: true, raw: true,
type: this.sequelize.QueryTypes.SELECT type: this.sequelize.QueryTypes.SELECT
...@@ -57,6 +86,15 @@ class QueryInterface { ...@@ -57,6 +86,15 @@ class QueryInterface {
)); ));
} }
/**
* Returns database version
*
* @param {Object} [options] Query options
* @param {QueryType} [options.type] Query type
*
* @returns {Promise}
* @private
*/
databaseVersion(options) { databaseVersion(options) {
return this.sequelize.query( return this.sequelize.query(
this.QueryGenerator.versionQuery(), this.QueryGenerator.versionQuery(),
...@@ -64,6 +102,57 @@ class QueryInterface { ...@@ -64,6 +102,57 @@ class QueryInterface {
); );
} }
/**
* Create a table with given set of attributes
*
* ```js
* queryInterface.createTable(
* 'nameOfTheNewTable',
* {
* id: {
* type: Sequelize.INTEGER,
* primaryKey: true,
* autoIncrement: true
* },
* createdAt: {
* type: Sequelize.DATE
* },
* updatedAt: {
* type: Sequelize.DATE
* },
* attr1: Sequelize.STRING,
* attr2: Sequelize.INTEGER,
* attr3: {
* type: Sequelize.BOOLEAN,
* defaultValue: false,
* allowNull: false
* },
* //foreign key usage
* attr4: {
* type: Sequelize.INTEGER,
* references: {
* model: 'another_table_name',
* key: 'id'
* },
* onUpdate: 'cascade',
* onDelete: 'cascade'
* }
* },
* {
* engine: 'MYISAM', // default: 'InnoDB'
* charset: 'latin1', // default: null
* schema: 'public' // default: public, PostgreSQL only.
* }
* )
* ```
*
* @param {String} tableName Name of table to create
* @param {Array} attributes List of table attributes to create
* @param {Object} [options]
* @param {Model} [model]
*
* @return {Promise}
*/
createTable(tableName, attributes, options, model) { createTable(tableName, attributes, options, model) {
const keys = Object.keys(attributes); const keys = Object.keys(attributes);
const keyLen = keys.length; const keyLen = keys.length;
...@@ -170,6 +259,14 @@ class QueryInterface { ...@@ -170,6 +259,14 @@ class QueryInterface {
} }
} }
/**
* Drops a table from database
*
* @param {String} tableName Table name to drop
* @param {Object} options Query options
*
* @return {Promise}
*/
dropTable(tableName, options) { dropTable(tableName, options) {
// if we're forcing we should be cascading unless explicitly stated otherwise // if we're forcing we should be cascading unless explicitly stated otherwise
options = _.clone(options) || {}; options = _.clone(options) || {};
...@@ -205,8 +302,15 @@ class QueryInterface { ...@@ -205,8 +302,15 @@ class QueryInterface {
}); });
} }
/**
* Drop all tables from database
*
* @param {Object} [options]
* @param {Array} [options.skip] List of table to skip
*
* @return {Promise}
*/
dropAllTables(options) { dropAllTables(options) {
options = options || {}; options = options || {};
const skip = options.skip || []; const skip = options.skip || [];
...@@ -252,6 +356,14 @@ class QueryInterface { ...@@ -252,6 +356,14 @@ class QueryInterface {
}); });
} }
/**
* Drop all enums from database, Postgres Only
*
* @param {Object} options Query options
*
* @return {Promise}
* @private
*/
dropAllEnums(options) { dropAllEnums(options) {
if (this.sequelize.getDialect() !== 'postgres') { if (this.sequelize.getDialect() !== 'postgres') {
return Promise.resolve(); return Promise.resolve();
...@@ -265,18 +377,46 @@ class QueryInterface { ...@@ -265,18 +377,46 @@ class QueryInterface {
)); ));
} }
/**
* List all enums, Postgres Only
*
* @param {String} [tableName] Table whose enum to list
* @param {Object} [options] Query options
*
* @return {Promise}
* @private
*/
pgListEnums(tableName, options) { pgListEnums(tableName, options) {
options = options || {}; options = options || {};
const sql = this.QueryGenerator.pgListEnums(tableName); const sql = this.QueryGenerator.pgListEnums(tableName);
return this.sequelize.query(sql, _.assign({}, options, { plain: false, raw: true, type: QueryTypes.SELECT })); return this.sequelize.query(sql, _.assign({}, options, { plain: false, raw: true, type: QueryTypes.SELECT }));
} }
/**
* Renames a table
*
* @param {String} before Current name of table
* @param {String} after New name from table
* @param {Object} [options] Query options
*
* @return {Promise}
*/
renameTable(before, after, options) { renameTable(before, after, options) {
options = options || {}; options = options || {};
const sql = this.QueryGenerator.renameTableQuery(before, after); const sql = this.QueryGenerator.renameTableQuery(before, after);
return this.sequelize.query(sql, options); return this.sequelize.query(sql, options);
} }
/**
* Get all tables in current database
*
* @param {Object} [options] Query options
* @param {Boolean} [options.raw=true] Run query in raw mode
* @param {QueryType} [options.type=QueryType.SHOWTABLE]
*
* @return {Promise<Array>}
* @private
*/
showAllTables(options) { showAllTables(options) {
options = _.assign({}, options, { options = _.assign({}, options, {
raw: true, raw: true,
...@@ -287,6 +427,30 @@ class QueryInterface { ...@@ -287,6 +427,30 @@ class QueryInterface {
return this.sequelize.query(showTablesSql, options).then(tableNames => Utils._.flatten(tableNames)); return this.sequelize.query(showTablesSql, options).then(tableNames => Utils._.flatten(tableNames));
} }
/**
* Describe a table structure
*
* This method returns an array of hashes containing information about all attributes in the table.
*
* ```js
* {
* name: {
* type: 'VARCHAR(255)', // this will be 'CHARACTER VARYING' for pg!
* allowNull: true,
* defaultValue: null
* },
* isBetaMember: {
* type: 'TINYINT(1)', // this will be 'BOOLEAN' for pg!
* allowNull: false,
* defaultValue: false
* }
* }
* ```
* @param {String} tableName
* @param {Object} [options] Query options
*
* @return {Promise<Object>}
*/
describeTable(tableName, options) { describeTable(tableName, options) {
let schema = null; let schema = null;
let schemaDelimiter = null; let schemaDelimiter = null;
...@@ -320,6 +484,16 @@ class QueryInterface { ...@@ -320,6 +484,16 @@ class QueryInterface {
}); });
} }
/**
* Add a new column into a table
*
* @param {String} table Table to add column to
* @param {String} key Column name
* @param {Object} attribute Attribute definition
* @param {Object} [options] Query options
*
* @return {Promise}
*/
addColumn(table, key, attribute, options) { addColumn(table, key, attribute, options) {
if (!table || !key || !attribute) { if (!table || !key || !attribute) {
throw new Error('addColumn takes atleast 3 arguments (table, attribute name, attribute definition)'); throw new Error('addColumn takes atleast 3 arguments (table, attribute name, attribute definition)');
...@@ -330,6 +504,15 @@ class QueryInterface { ...@@ -330,6 +504,15 @@ class QueryInterface {
return this.sequelize.query(this.QueryGenerator.addColumnQuery(table, key, attribute), options); return this.sequelize.query(this.QueryGenerator.addColumnQuery(table, key, attribute), options);
} }
/**
* Remove a column from table
*
* @param {String} tableName Table to remove column from
* @param {String} attributeName Columns name to remove
* @param {Object} [options] Query options
*
* @return {Promise}
*/
removeColumn(tableName, attributeName, options) { removeColumn(tableName, attributeName, options) {
options = options || {}; options = options || {};
switch (this.sequelize.options.dialect) { switch (this.sequelize.options.dialect) {
...@@ -347,6 +530,16 @@ class QueryInterface { ...@@ -347,6 +530,16 @@ class QueryInterface {
} }
} }
/**
* Change a column definition
*
* @param {String} tableName Table name to change from
* @param {String} attributeName Column name
* @param {Object} dataTypeOrOptions Attribute definition for new column
* @param {Object} [options] Query options
*
* @return {Promise}
*/
changeColumn(tableName, attributeName, dataTypeOrOptions, options) { changeColumn(tableName, attributeName, dataTypeOrOptions, options) {
const attributes = {}; const attributes = {};
options = options || {}; options = options || {};
...@@ -370,6 +563,16 @@ class QueryInterface { ...@@ -370,6 +563,16 @@ class QueryInterface {
} }
} }
/**
* Rename a column
*
* @param {String} tableName Table name whose column to rename
* @param {String} attrNameBefore Current column name
* @param {String} attrNameAfter New column name
* @param {Object} [options] Query option
*
* @return {Promise}
*/
renameColumn(tableName, attrNameBefore, attrNameAfter, options) { renameColumn(tableName, attrNameBefore, attrNameAfter, options) {
options = options || {}; options = options || {};
return this.describeTable(tableName, options).then(data => { return this.describeTable(tableName, options).then(data => {
...@@ -407,6 +610,20 @@ class QueryInterface { ...@@ -407,6 +610,20 @@ class QueryInterface {
}); });
} }
/**
* Add index to a column
*
* @param {String} tableName Table name to add index on
* @param {Object} options
* @param {Array} options.fields List of attributes to add index on
* @param {Boolean} [options.unique] Create a unique index
* @param {String} [options.using] Useful for GIN indexes
* @param {String} [options.type] Type of index, available options are UNIQUE|FULLTEXT|SPATIAL
* @param {String} [options.name] Name of the index. Default is <table>_<attr1>_<attr2>
* @param {Object} [options.where] Where condition on index, for partial indexes
*
* @return {Promise}
*/
addIndex(tableName, attributes, options, rawTablename) { addIndex(tableName, attributes, options, rawTablename) {
// Support for passing tableName, attributes, options or tableName, options (with a fields param which is the attributes) // Support for passing tableName, attributes, options or tableName, options (with a fields param which is the attributes)
if (!Array.isArray(attributes)) { if (!Array.isArray(attributes)) {
...@@ -427,6 +644,15 @@ class QueryInterface { ...@@ -427,6 +644,15 @@ class QueryInterface {
return this.sequelize.query(sql, _.assign({}, options, { supportsSearchPath: false })); return this.sequelize.query(sql, _.assign({}, options, { supportsSearchPath: false }));
} }
/**
* Show indexes on a table
*
* @param {String} tableName
* @param {Object} [options] Query options
*
* @return {Promise<Array>}
* @private
*/
showIndex(tableName, options) { showIndex(tableName, options) {
const sql = this.QueryGenerator.showIndexesQuery(tableName, options); const sql = this.QueryGenerator.showIndexesQuery(tableName, options);
return this.sequelize.query(sql, _.assign({}, options, { type: QueryTypes.SHOWINDEXES })); return this.sequelize.query(sql, _.assign({}, options, { type: QueryTypes.SHOWINDEXES }));
...@@ -460,12 +686,91 @@ class QueryInterface { ...@@ -460,12 +686,91 @@ class QueryInterface {
}); });
} }
/**
* Remove an already existing index from a table
*
* @param {String} tableName Table name to drop index from
* @param {String} indexNameOrAttributes Index name
* @param {Object} [options] Query options
*
* @return {Promise}
*/
removeIndex(tableName, indexNameOrAttributes, options) { removeIndex(tableName, indexNameOrAttributes, options) {
options = options || {}; options = options || {};
const sql = this.QueryGenerator.removeIndexQuery(tableName, indexNameOrAttributes); const sql = this.QueryGenerator.removeIndexQuery(tableName, indexNameOrAttributes);
return this.sequelize.query(sql, options); return this.sequelize.query(sql, options);
} }
/**
* Add constraints to table
*
* Available constraints:
* - UNIQUE
* - DEFAULT (MSSQL only)
* - CHECK (MySQL - Ignored by the database engine )
* - FOREIGN KEY
* - PRIMARY KEY
*
* UNIQUE
* ```js
* queryInterface.addConstraint('Users', ['email'], {
* type: 'unique',
* name: 'custom_unique_constraint_name'
* });
* ```
*
* CHECK
* ```js
* queryInterface.addConstraint('Users', ['roles'], {
* type: 'check',
* where: {
* roles: ['user', 'admin', 'moderator', 'guest']
* }
* });
* ```
* Default - MSSQL only
* ```js
* queryInterface.addConstraint('Users', ['roles'], {
* type: 'default',
* defaultValue: 'guest'
* });
* ```
*
* Primary Key
* ```js
* queryInterface.addConstraint('Users', ['username'], {
* type: 'primary key',
* name: 'custom_primary_constraint_name'
* });
* ```
*
* Foreign Key
* ```js
* queryInterface.addConstraint('Posts', ['username'], {
* type: 'FOREIGN KEY',
* name: 'custom_fkey_constraint_name',
* references: { //Required field
* table: 'target_table_name',
* field: 'target_column_name'
* },
* onDelete: 'cascade',
* onUpdate: 'cascade'
* });
* ```
*
* @param {String} tableName Table name where you want to add a constraint
* @param {Array} attributes Array of column names to apply the constraint over
* @param {Object} options An object to define the constraint name, type etc
* @param {String} options.type Type of constraint. One of the values in available constraints(case insensitive)
* @param {String} [options.name] Name of the constraint. If not specified, sequelize automatically creates a named constraint based on constraint type, table & column names
* @param {String} [options.defaultValue] The value for the default constraint
* @param {Object} [options.where] Where clause/expression for the CHECK constraint
* @param {Object} [options.references] Object specifying target table, column name to create foreign key constraint
* @param {String} [options.references.table] Target table name
* @param {String} [options.references.field] Target column name
*
* @return {Promise}
*/
addConstraint(tableName, attributes, options, rawTablename) { addConstraint(tableName, attributes, options, rawTablename) {
if (!Array.isArray(attributes)) { if (!Array.isArray(attributes)) {
rawTablename = options; rawTablename = options;
...@@ -498,6 +803,14 @@ class QueryInterface { ...@@ -498,6 +803,14 @@ class QueryInterface {
return this.sequelize.query(sql, Object.assign({}, options, { type: QueryTypes.SHOWCONSTRAINTS })); return this.sequelize.query(sql, Object.assign({}, options, { type: QueryTypes.SHOWCONSTRAINTS }));
} }
/**
*
* @param {String} tableName Table name to drop constraint from
* @param {String} constraintName Constraint name
* @param {Object} options Query options
*
* @return {Promise}
*/
removeConstraint(tableName, constraintName, options) { removeConstraint(tableName, constraintName, options) {
options = options || {}; options = options || {};
...@@ -584,6 +897,26 @@ class QueryInterface { ...@@ -584,6 +897,26 @@ class QueryInterface {
}); });
} }
/**
* Insert records into a table
*
* ```js
* queryInterface.bulkInsert('roles', [{
* label: 'user',
* createdAt: new Date(),
* updatedAt: new Date()
* }, {
* label: 'admin',
* createdAt: new Date(),
* updatedAt: new Date()
* }]);
* ```
*
* @param {String} tableName Table name to insert record to
* @param {Array} records List of records to insert
*
* @return {Promise}
*/
bulkInsert(tableName, records, options, attributes) { bulkInsert(tableName, records, options, attributes) {
options = _.clone(options) || {}; options = _.clone(options) || {};
options.type = QueryTypes.INSERT; options.type = QueryTypes.INSERT;
...@@ -654,6 +987,14 @@ class QueryInterface { ...@@ -654,6 +987,14 @@ class QueryInterface {
}); });
} }
/**
* Delete records from a table
*
* @param {String} tableName Table name from where to delete records
* @param {Object} identifier Where conditions to find records to delete
*
* @return {Promise}
*/
bulkDelete(tableName, identifier, options, model) { bulkDelete(tableName, identifier, options, model) {
options = Utils.cloneDeep(options); options = Utils.cloneDeep(options);
options = _.defaults(options, {limit: null}); options = _.defaults(options, {limit: null});
......
lib/utils.js
...@@ -441,6 +441,10 @@ exports.removeTicks = removeTicks; ...@@ -441,6 +441,10 @@ exports.removeTicks = removeTicks;
* address.coordinates.latitude: 55.6779627, * address.coordinates.latitude: 55.6779627,
* address.coordinates.longitude: 12.5964313 * address.coordinates.longitude: 12.5964313
* } * }
*
* @param value, an Object
* @return Object, an flattened object
* @private
*/ */
function flattenObjectDeep(value) { function flattenObjectDeep(value) {
if (!_.isPlainObject(value)) return value; if (!_.isPlainObject(value)) return value;
......
Markdown is supported
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!