* This class represents an single instance, a database column. You might see it referred to as both DAO and instance.
*
* DAO instances operate with the concept of a `dataValues` property, which stores the actual values represented by this DAO. By default, the values from dataValues can also be accessed directly from the DAO, that is:
```js
instance.field
// is the same as
instance.get('field')
// is the same as
instance.getDataValue('field')
```
* However, if getters and/or setters are defined for `field` they will be invoked, instead of returning the value from `dataValues`.
* @see {Sequelize#define} Sequelize#define for more information about getters and setters
* If no key is given, returns all values of the instance.
*
* If key is given and a field or virtual getter is present for the key it will call the getter with key - else it will return the value for key.
* @param {String} [key]
* @return {Object|any} If no key is given, all values will be returned as a hash. If key is given, the value of that column / virtual getter will be returned
* If values is an object and raw is true and no includes are in the Instance options, set will set dataValues to values, or extend it if it exists.
* Else values will be looped and a recursive set will be kalled with key and value from the hash.
* If set is called with a key and a value and the key matches an include option, it will build the child include with the value.
* If raw is false and a field or virtual setter is present for the key, it will call the setter with (value, key) - else it will set instance value for key to value.
*
* @see {DAOFactory#find} DAOFactory#find for more information about includes
* @param {String|Object} key(s)
* @param {any} value
* @param {Object} [options]
* @param {Boolean} [options.raw=false] If set to true, field and virtual setters will be ignored
* If changed is called with a string it will return `true|false` depending on whether the value(s) are `dataValues` is different from the value(s) in `_previousDataValues`.
*
* If changed is called without an argument, it will return an array of keys that have changed.
* @param {String} [key]
* @return {Boolean|Array} A boolean if key is provided, otherwise an array of all attributes that have changed
* Update multiple attributes at once. The values are updated by calling set
*
* @see {DAO#set}
* @param {Object} updates A hash of values to update
* @return {EventEmitter}
* @fires error, success, sql
*/
DAO.prototype.setAttributes=function(updates){
this.set(updates)
}
/**
* Destroy the column corresponding to this DAO object. Depending on your setting for paranoid, the row will either be completely deleted, or have its deletedAt timestamp set to the current timestamp.
*
* @param {Object} [options={}]
* @param {Boolean} [options.force=false] If set to true, paranoid models will actually be deleted
* Increment the value of one or more columns. This is done in the database, which means it does not use the values currently stored on the DAO. The increment is done using a
```sql
SET column = column + X
```
query. To get the correct value after an increment into the DAO you should do a reload.
```js
instance.increment('number') increment number by 1
instance.increment(['number', 'count'], { by: 2 }) increment number and count by 2
instance.increment({ answer: 42, tries: 1}, { by: 1 }) increment answer by 42, and tries by 1. `by` is ignore, since each column has its own value
```
*
* @see {DAO#reload}
* @param {String|Array|Object} fields If a string is provided, that column is incremented by the value of `by` given in options. If an array is provided, the same is true for each column. If and object is provided, each column is incremented by the value given
* @param {Object} [options]
* @param {Integer} [options.by=1] The number to increment by
* Increment the value of one or more columns. This is done in the database, which means it does not use the values currently stored on the DAO. The decrement is done using a
```sql
SET column = column - X
```
query. To get the correct value after an decrement into the DAO you should do a reload.
```js
instance.decrement('number') decrement number by 1
instance.decrement(['number', 'count'], { by: 2 }) decrement number and count by 2
instance.decrement({ answer: 42, tries: 1}, { by: 1 }) decrement answer by 42, and tries by 1. `by` is ignore, since each column has its own value
```
*
* @see {DAO#reload}
* @param {String|Array|Object} fields If a string is provided, that column is decremented by the value of `by` given in options. If an array is provided, the same is true for each column. If and object is provided, each column is decremented by the value given
* @param {Object} [options]
* @param {Integer} [options.by=1] The number to decrement by
* An object of different query types. This is used when doing raw queries (sequlize.query). If no type is provided to .query, sequelize will try to guess the correct type based on your SQL. This might not always work if you query is formatted in a special way
* Define a new model, representing a table in the DB.
*
* The table columns are define by the hash that is given as the second argument. Each attribute of the hash represents a column. A short table definition might look like this:
*
* ```js
* sequelize.define(..., {
* columnA: {
* type: Sequelize.BOOLEAN,
* // Other attributes here
* },
* columnB: Sequelize.STRING,
* columnC: 'MY VERY OWN COLUMN TYPE'
* })
* ```
*
* For a list of possible data types, see http://sequelizejs.com/docs/latest/models#data-types
*
* For more about getters and setters, see http://sequelizejs.com/docs/latest/models#getters---setters
*
* For more about instance and class methods see http://sequelizejs.com/docs/latest/models#expansion-of-models
*
* @see {DataTypes}
* @param {String} daoName
* @param {Object} attributes An object, where each attribute is a column of the table. Each column can be either a DataType, a string or a type-description object, with the properties described below:
* @param {String|DataType|Object} attributes.column The description of a database column
* @param {String|DataType} attributes.column.type A string or a data type
* @param {Boolean} [attributes.column.allowNull=true] If false, the column will have a NOT NULL constraint
* @param {Boolean} [attributes.column.defaultValue=null] A literal default value, or a function, see sequelize#fn
* @param {String|Boolean} [attributes.column.unique=false] If true, the column will get a unique constraint. If a string is provided, the column will be part of a composite unique index. If multiple columns have the same string, they will be part of the same unique index
* @param {String|DAOFactory} [attributes.column.references] If this column references another table, provide it here as a DAOFactory, or a string
* @param {String} [attributes.column.referencesKey='id'] The column of the foreign table that this column references
* @param {String} [attributes.column.onUpdate] What should happen when the referenced key is updated. One of CASCADE, RESTRICT or NO ACTION
* @param {String} [attributes.column.onDelete] What should happen when the referenced key is deleted. One of CASCADE, RESTRICT or NO ACTION
* @param {Function} [attributes.column.get] Provide a custom getter for this column. Use this.getDataValue(String) and this.setDataValue(String, Value) to manipulate the underlying values.
* @param {Function} [attributes.column.set] Provide a custom setter for this column. Use this.getDataValue(String) and this.setDataValue(String, Value) to manipulate the underlying values.
* @param {Object} [options] These options are merged with the options provided to the Sequelize constructor
* @param {Boolean} [options.omitNull] Don't persits null values. This means that all columns with null values will not be saved
* @param {Boolean} [options.timestamps=true] Handle createdAt and updatedAt timestamps
* @param {Boolean} [options.paranoid=false] Calling destroy will not delete the model, but instead set a deletedAt timestamp if this is true. Needs timestamps=true to work
* @param {Boolean} [options.underscored=false] Converts all camelCased columns to underscored if true
* @param {Boolean} [options.freezeTableName=false] If freezeTableName is true, sequelize will not try to alter the DAO name to get the table name. Otherwise, the tablename will be pluralized
* @param {String|Boolean} [options.createdAt] Override the name of the createdAt column if a string is provided, or disable it if true. Timestamps must be true
* @param {String|Boolean} [options.updatedAt] Override the name of the updatedAt column if a string is provided, or disable it if true. Timestamps must be true
* @param {String|Boolean} [options.deletedAt] Override the name of the deletedAt column if a string is provided, or disable it if true. Timestamps must be true
* @param {String} [options.tableName] Defaults to pluralized DAO name
* @param {Object} [options.getterMethods] Provide getter functions that work like those defined per column. If you provide a getter method with the same name as a column, it will be used to access the value of that column. If you provide a name that does not match a column, this function will act as a virtual getter, that can fetch multiple other values
* @param {Object} [options.setterMethods] Provide setter functions that work like those defined per column. If you provide a setter method with the same name as a column, it will be used to update the value of that column. If you provide a name that does not match a column, this function will act as a virtual setter, that can act on and set other values, but will not be persisted
* @param {Object} [options.instanceMethods] Provide functions that are added to each instance (DAO)
* @param {Object} [options.classMethods] Provide functions that are added to the model (DAOFactory)
* Imported DAOs are cached, so multiple calls to import with the same path will not load the file multiple times
*
* See https://github.com/sequelize/sequelize/blob/master/examples/using-multiple-model-files/Task.js for a short example of how to define your models in separate files so that they can be imported by sequelize.import
* @param {String} path The path to the file that holds the model you want to import. If the part is relative, it will be resolved relatively to the calling file
* @param {DAOFactory} [callee] If callee is provided, the selected data will be used to build an instance of the DAO represented by the factory. Equivalent to calling DAOFactory.build with the values provided by the query.
* @param {Object} [options={}] Query options. See above for a full set of options
* @param {Object} [options={}] Query options.
* @param {Boolean} [options.raw] If true, sequelize will not try to format the results of the query, or build an instance of a model from the result
* @param {String} [options.type] What is the type of this query (SELECT, UPDATE etc.). If the query starts with SELECT, the type will be assumed to be SELECT, otherwise no assumptions are made. Only used when raw is false.
* @param {Transaction} [options.transaction=null] The transaction that the query should be executed under
* @param {Object|Array} [replacements] Either an object of named parameter replacements in the format `:param` or an array of unnamed replacements to replace `?`
* @return {EventEmitter}
*
* @see {DAOFactory#build} for more information about callee.
* Creates a object representing a database function. This can be used in search queries, both in where and order parts, and as default values in column definitions.
* If you want to refer to columns in your function, you should use sequelize.col, so that the columns are properly interpreted as columns and not a strings.
*
* @see {DAOFactory#find}
* @see {DAOFactory#findAll}
* @see {DAOFactory#define}
* @see {Sequelize#col}
*
* @method fn
* @param {String} fn The function you want to call
* @param {any} args All further arguments will be passed as arguments to the function
* @param {String} [options.isolationLevel='REPEATABLE_READ'] One of READ UNCOMMITTED, READ COMMITTED, REPEATABLE READ, SERIALIZABLE. It is preferred to use sequelize.Transaction.ISOLATION_LEVELS as opposed to providing a string
* @param {Function} callback Called when the transaction has been set up and is ready for use. If the callback takes two arguments it will be called with err, transaction, otherwise it will be called with transaction.
* @return {Transaction}
* @fires error If there is an uncaught error during the transaction
* @fires success When the transaction has ended (either comitted or rolled back)
An object of different query types. This is used when doing raw queries (sequlize.query). If no type is provided to .query, sequelize will try to guess the correct type based on your SQL. This might not always work if you query is formatted in a special way
@@ -235,9 +315,262 @@ Returns an instance (singleton) of Migrator.
------
<aname="define"/>
### define(daoName, attributes, [options])
Define a new model, representing a table in the DB.
The table columns are define by the hash that is given as the second argument. Each attribute of the hash represents a column. A short table definition might look like this:
```js
sequelize.define(...,{
columnA:{
type:Sequelize.BOOLEAN,
// Other attributes here
},
columnB:Sequelize.STRING,
columnC:'MY VERY OWN COLUMN TYPE'
})
```
For a list of possible data types, see http://sequelizejs.com/docs/latest/models#data-types
For more about getters and setters, see http://sequelizejs.com/docs/latest/models#getters---setters
For more about instance and class methods see http://sequelizejs.com/docs/latest/models#expansion-of-models
<td>An object, where each attribute is a column of the table. Each column can be either a DataType, a string or a type-description object, with the properties described below:</td>
</tr>
<tr>
<td>attributes.column</td>
<td>String|DataType|Object</td>
<td>The description of a database column</td>
</tr>
<tr>
<td>attributes.column.type</td>
<td>String|DataType</td>
<td>A string or a data type</td>
</tr>
<tr>
<td>[attributes.column.allowNull=true]</td>
<td>Boolean</td>
<td>If false, the column will have a NOT NULL constraint</td>
</tr>
<tr>
<td>[attributes.column.defaultValue=null]</td>
<td>Boolean</td>
<td>A literal default value, or a function, see sequelize#fn</td>
</tr>
<tr>
<td>[attributes.column.unique=false]</td>
<td>String|Boolean</td>
<td>If true, the column will get a unique constraint. If a string is provided, the column will be part of a composite unique index. If multiple columns have the same string, they will be part of the same unique index</td>
</tr>
<tr>
<td>[attributes.column.primaryKey=false]</td>
<td>Boolean</td>
<td></td>
</tr>
<tr>
<td>[attributes.column.autoIncrement=false]</td>
<td>Boolean</td>
<td></td>
</tr>
<tr>
<td>[attributes.column.comment=null]</td>
<td>String</td>
<td></td>
</tr>
<tr>
<td>[attributes.column.references]</td>
<td>String|DAOFactory</td>
<td>If this column references another table, provide it here as a DAOFactory, or a string</td>
</tr>
<tr>
<td>[attributes.column.referencesKey='id']</td>
<td>String</td>
<td>The column of the foreign table that this column references</td>
</tr>
<tr>
<td>[attributes.column.onUpdate]</td>
<td>String</td>
<td>What should happen when the referenced key is updated. One of CASCADE, RESTRICT or NO ACTION</td>
</tr>
<tr>
<td>[attributes.column.onDelete]</td>
<td>String</td>
<td>What should happen when the referenced key is deleted. One of CASCADE, RESTRICT or NO ACTION</td>
</tr>
<tr>
<td>[attributes.column.get]</td>
<td>Function</td>
<td>Provide a custom getter for this column. Use this.getDataValue(String) and this.setDataValue(String, Value) to manipulate the underlying values.</td>
</tr>
<tr>
<td>[attributes.column.set]</td>
<td>Function</td>
<td>Provide a custom setter for this column. Use this.getDataValue(String) and this.setDataValue(String, Value) to manipulate the underlying values.</td>
</tr>
<tr>
<td>[options]</td>
<td>Object</td>
<td>These options are merged with the options provided to the Sequelize constructor</td>
</tr>
<tr>
<td>[options.omitNull]</td>
<td>Boolean</td>
<td>Don't persits null values. This means that all columns with null values will not be saved</td>
</tr>
<tr>
<td>[options.timestamps=true]</td>
<td>Boolean</td>
<td>Handle createdAt and updatedAt timestamps</td>
</tr>
<tr>
<td>[options.paranoid=false]</td>
<td>Boolean</td>
<td>Calling destroy will not delete the model, but instead set a deletedAt timestamp if this is true. Needs timestamps=true to work</td>
</tr>
<tr>
<td>[options.underscored=false]</td>
<td>Boolean</td>
<td>Converts all camelCased columns to underscored if true</td>
</tr>
<tr>
<td>[options.freezeTableName=false]</td>
<td>Boolean</td>
<td>If freezeTableName is true, sequelize will not try to alter the DAO name to get the table name. Otherwise, the tablename will be pluralized</td>
</tr>
<tr>
<td>[options.createdAt]</td>
<td>String|Boolean</td>
<td>Override the name of the createdAt column if a string is provided, or disable it if true. Timestamps must be true</td>
</tr>
<tr>
<td>[options.updatedAt]</td>
<td>String|Boolean</td>
<td>Override the name of the updatedAt column if a string is provided, or disable it if true. Timestamps must be true</td>
</tr>
<tr>
<td>[options.deletedAt]</td>
<td>String|Boolean</td>
<td>Override the name of the deletedAt column if a string is provided, or disable it if true. Timestamps must be true</td>
</tr>
<tr>
<td>[options.tableName]</td>
<td>String</td>
<td>Defaults to pluralized DAO name</td>
</tr>
<tr>
<td>[options.getterMethods]</td>
<td>Object</td>
<td>Provide getter functions that work like those defined per column. If you provide a getter method with the same name as a column, it will be used to access the value of that column. If you provide a name that does not match a column, this function will act as a virtual getter, that can fetch multiple other values</td>
</tr>
<tr>
<td>[options.setterMethods]</td>
<td>Object</td>
<td>Provide setter functions that work like those defined per column. If you provide a setter method with the same name as a column, it will be used to update the value of that column. If you provide a name that does not match a column, this function will act as a virtual setter, that can act on and set other values, but will not be persisted</td>
</tr>
<tr>
<td>[options.instanceMethods]</td>
<td>Object</td>
<td>Provide functions that are added to each instance (DAO)</td>
</tr>
<tr>
<td>[options.classMethods]</td>
<td>Object</td>
<td>Provide functions that are added to the model (DAOFactory)</td>
</tr>
<tr>
<td>[options.schema='public']</td>
<td>String</td>
<td></td>
</tr>
<tr>
<td>[options.engine]</td>
<td>String</td>
<td></td>
</tr>
<tr>
<td>[options.charset]</td>
<td>Strng</td>
<td></td>
</tr>
<tr>
<td>[options.comment]</td>
<td>String</td>
<td></td>
</tr>
<tr>
<td>[options.collate]</td>
<td>String</td>
<td></td>
</tr>
</table>
#### Return:
***DaoFactory**
------
<aname="model"/>
### model(daoName)
Fetch a DAO factory
Fetch a DAO factory which is already defined
#### Params:
<table>
...
...
@@ -253,17 +586,75 @@ Fetch a DAO factory
</table>
#### Return:
***DAOFactory** The DAOFactory for daoName
------
<aname="isDefined"/>
### isDefined(daoName)
Checks whether a DAO with the given name is defined
#### Params:
<table>
<thead>
<th>Name</th><th>Type</th><th>Description</th>
</thead>
<tr>
<td>daoName</td>
<td>String</td>
<td>The name of a model defined with Sequelize.define</td>
</tr>
</table>
#### Return:
***Boolean** Is a DAO with that name already defined?
------
<aname="import"/>
### import(path)
Imports a DAO defined in another file
Imported DAOs are cached, so multiple calls to import with the same path will not load the file multiple times
See https://github.com/sequelize/sequelize/blob/master/examples/using-multiple-model-files/Task.js for a short example of how to define your models in separate files so that they can be imported by sequelize.import
#### Params:
<table>
<thead>
<th>Name</th><th>Type</th><th>Description</th>
</thead>
<tr>
<td>path</td>
<td>String</td>
<td>The path to the file that holds the model you want to import. If the part is relative, it will be resolved relatively to the calling file</td>
Execute a query on the DB, with the posibility to bypass all the sequelize goodness.
See {@link MyClass} and [MyClass's foo property]{@link MyClass#foo}.
Also, check out {@link http://www.google.com|Google} and
{@link https://github.com GitHub}.
See: {DAOFactory#build} for more information about callee.
See: <ahref="https://github.com/sequelize/sequelize/wiki/API-Reference-DAOFactory#build"> for more information about callee.</a>
#### Params:
<table>
...
...
@@ -286,7 +677,25 @@ See: {DAOFactory#build} for more information about callee.
<tr>
<td>[options={}]</td>
<td>Object</td>
<td>Query options. See above for a full set of options</td>
<td>Query options.</td>
</tr>
<tr>
<td>[options.raw]</td>
<td>Boolean</td>
<td>If true, sequelize will not try to format the results of the query, or build an instance of a model from the result</td>
</tr>
<tr>
<td>[options.type]</td>
<td>String</td>
<td>What is the type of this query (SELECT, UPDATE etc.). If the query starts with SELECT, the type will be assumed to be SELECT, otherwise no assumptions are made. Only used when raw is false. </td>
</tr>
<tr>
<td>[options.transaction=null]</td>
<td>Transaction</td>
<td>The transaction that the query should be executed under</td>
</tr>
<tr>
...
...
@@ -297,8 +706,14 @@ See: {DAOFactory#build} for more information about callee.
</table>
#### Return:
***EventEmitter**
------
<aname="query"/>
### query(sql, [options={raw:true}])
Execute a raw query against the DB.
...
...
@@ -323,11 +738,17 @@ Execute a raw query against the DB.
</table>
#### Return:
***EventEmitter**
------
### authenticate(cake, a)
<aname="createSchema"/>
Test the connetion by trying to authenticate
### createSchema(schema)
Create a new database schema
#### Params:
<table>
...
...
@@ -336,25 +757,134 @@ Test the connetion by trying to authenticate
</thead>
<tr>
<td>cake</td>
<td>boolean</td>
<td>want cake?</td>
<td>schema</td>
<td>String</td>
<td>Name of the schema</td>
</tr>
</table>
#### Return:
***EventEmitter**
------
<aname="showAllSchemas"/>
### showAllSchemas()
Show all defined schemas
#### Return:
***EventEmitter**
------
<aname="dropSchema"/>
### dropSchema(schema)
Drop a single schema
#### Params:
<table>
<thead>
<th>Name</th><th>Type</th><th>Description</th>
</thead>
<tr>
<td>a</td>
<td>string</td>
<td>something else</td>
<td>schema</td>
<td>String</td>
<td>Name of the schema</td>
</tr>
</table>
#### Return:
***EventEmitter**
------
### authenticate (k)
<aname="dropAllSchemas"/>
### dropAllSchemas()
Drop all schemas
#### Return:
***EventEmitter**
------
<aname="sync"/>
### sync([options={}])
Sync all defined DAOs to the DB.
#### Params:
<table>
<thead>
<th>Name</th><th>Type</th><th>Description</th>
</thead>
<tr>
<td>[options={}]</td>
<td>Object</td>
<td></td>
</tr>
<tr>
<td>[options.force=false]</td>
<td>Boolean</td>
<td>If force is true, each DAO will do DROP TABLE IF EXISTS ..., before it tries to create its own table</td>
</tr>
<tr>
<td>[options.logging=console.log]</td>
<td>Boolean|function</td>
<td>A function that logs sql queries, or false for no logging</td>
</tr>
<tr>
<td>[options.schema='public']</td>
<td>String</td>
<td>The schema that the tables should be created in. This can be overriden for each table in sequelize.define</td>
</tr>
</table>
#### Return:
***EventEmitter**
------
<aname="authenticate"/>
### authenticate()
Test the connetion by trying to authenticate
#### Return:
***EventEmitter**
------
<aname="fn"/>
### fn(fn, args)
Creates a object representing a database function. This can be used in search queries, both in where and order parts, and as default values in column definitions.
If you want to refer to columns in your function, you should use sequelize.col, so that the columns are properly interpreted as columns and not a strings.
<td>One of READ UNCOMMITTED, READ COMMITTED, REPEATABLE READ, SERIALIZABLE. It is preferred to use sequelize.Transaction.ISOLATION_LEVELS as opposed to providing a string</td>
</tr>
<tr>
<td>callback</td>
<td>Function</td>
<td>Called when the transaction has been set up and is ready for use. If the callback takes two arguments it will be called with err, transaction, otherwise it will be called with transaction.</td>
</tr>
</table>
#### Return:
***Transaction**
------
_This document is automatically generated based on source code comments. Please do not edit it directly, as your changes will be ignored. Please write on [IRC](irc://irc.freenode.net/#sequelizejs), open an issue or a create a pull request if you feel something can be improved. For help on how to write source code documentation see [JSDoc](http://usejsdoc.org), [dox](https://github.com/visionmedia/dox) and [markdox](https://github.com/cbou/markdox)_
_This documentation was automagically created on Sun Feb 09 2014 20:14:56 GMT+0100 (CET)_
_This document is automatically generated based on source code comments. Please do not edit it directly, as your changes will be ignored. Please write on [IRC](irc://irc.freenode.net/#sequelizejs), open an issue or a create a pull request if you feel something can be improved. For help on how to write source code documentation see [JSDoc](http://usejsdoc.org), [dox](https://github.com/visionmedia/dox) and [markdox](https://github.com/cbou/markdox)_
_This documentation was automagically created on <?= new Date().toString() ?>_
