If the current working directory contains a file called database.json this file will be loaded upon requiring persist. The file should follow a format like this:

{
  "default": "dev",

  "dev": {
    "driver": "sqlite3",
    "filename": ":memory:"
  },

  "test": {
    "driver": "sqlite3",
    "filename": ":memory:"
  },

  "prod": {
    "driver": "sqlite3",
    "filename": "prod.db",
    "sqlDir": "./prodSql",
    "pooling": {
      "name": "testPool",
      "max": 2,
      "min": 1,
      "idleTimeoutMillis": 30000
    }
  }
}

"default" specifies which environment to load.

The environment to read from the database.json file. If not set will use the value of default from the database.json.

Example

persist.env = 'prod';

Connects to a database.

Arguments

Defines a model object for use in persist.

The primary key column does not need to be specified and will default to the name 'id' with the attributes dbColumnName='id', type='integer'. You can override the database name using dbColumnName or setting the primaryKey attribute on any column.

Arguments

• modelName - The name of the model. This name will map to the database name.
• properties - Hash of properties (or columns). The value of each property can simply be the type name (ie type.STRING) or it can be a hash of more options.
• type - type of the property (ie type.STRING)
• defaultValue - this can be a value or a function that will be called each time this model object is created
• dbColumnName - the name of the database column. (default: name of the property, all lower case, seperated by '_')
• primaryKey - Marks this column as being the primary key column. You can have only one primary key column.
• opts - Options for this column.
• tableName - The name of the table (default: modelName pluralized).

Returns

Defines a model object for use in persist. Columns are defined by the program in this method. Uses an existing database connection to retrieve column data.

Arguments

• modelName - The name of the model. This name will map to the table name.
• dbConfig - Hash of dbConfig. Should contain the driver, as well as the database name.
• database - The database connection to use.
• driver - The name of the database driver to use.

Returns

Chains multiple statements together in order and gets the results.

Arguments

• chainables - An array of chainable queries. These can be save, updates, selects, or deletes. Each item in the array will be executed, wait for the results, and then execute the next. This can also be a hash of queries in which case the results will contain a hash of results where each key corresponds to a key in the results.
• callback(err, results) - Callback called when all the items have been executed.

Example

// array chaining
connection.chain([
  person3.save,
  Person.min('age'),
  Person.max('age'),
  phone3.delete,
  person2.delete,
  Person.orderBy('name').all,
  Phone.orderBy('number').first,
  Phone.count,
  Phone.deleteAll,
  Phone.all,
  Person.getById(1),
  persist.runSql('SELECT * FROM Person')
], function(err, results) {
  // results[0] = person3
  // results[1] = 21
  // results[2] = 25
  // results[3] = []
  // results[4] = []
  // results[5] = -- all people ordered by name
  // results[6] = -- first phone ordered by number
  // results[7] = 100
  // results[8] = []
  // results[9] = [] -- nobody left
  // results[10] = -- the person with id 1
  // results[11] = Results of select.
});

// mapped chaining
connection.chain({
  minAge: Person.min('age'),
  maxAge: Person.max('age')
}, function(err, results) {
  // results.minAge = 21
  // results.maxAge = 25
});

Begins a transaction on the connection.

Arguments

Runs a sql statement that does not return results (INSERT, UPDATE, etc).

Arguments

• sql - The SQL statement to run.
• values - The values to substitute in the SQL statement. This is DB specific but typically you would use "?".
• callback(err, results) - Callback called when SQL statement completes. results will contain the number of affected rows or last insert id.

Example

connection.runSql("UPDATE people SET age = ?", [32], function(err, results) {
  // people updated
});

Runs a sql statement that returns results (ie SELECT).

Arguments

• sql - The SQL statement to run.
• values - The values to substitute in the SQL statement. This is DB specific but typically you would use "?".
• callback(err, results) - Callback called when SQL statement completes. results will contain the row data.

Example

connection.runSqlAll("SELECT * FROM people WHERE age = ?", [32], function(err, people) {
  // people contains all the people with age 32
});

Runs a sql statement that returns results (ie SELECT). This is different from runSqlAll in that it returns each row in a seperate callback.

Arguments

• sql - The SQL statement to run.
• values - The values to substitute in the SQL statement. This is DB specific but typically you would use "?".
• callback(err, row) - Callback called for each row returned.
• doneCallback(err) - Callback called after all the rows have returned.

Example

connection.runSqlEach("SELECT * FROM people WHERE age = ?", [32], function(err, person) {
  // a single person
}, function(err) {
  // all done
});

Gets a query object bound to a connection object.

Arguments

• connection - The connection to bind the query object to.

Returns

Saves the model object to the database

Arguments

• connection - The connection to use to save the object with.
• callback(err) - The callback to be called when the save is complete

Example

person1.save(connection, function() {
  // person1 saved
});

Updates the model object to the database

Arguments

• connection - The connection to use to update the object with.
• params - Object containing properties to update.
• callback(err) - The callback to be called when the update is complete

Example

person1.update(connection, { name: 'Tom' }, function() {
  // person1 saved
});

Updates the model object specified with id to the database. This will only update the values specified and will not retreive the item from the database first.

Arguments

• connection - The connection to use to update the object with.
• id - The id of the row you would like to update.
• params - Object containing properties to update.
• callback(err) - The callback to be called when the update is complete

Example

Person.update(connection, 5, { name: 'Tom' }, function() {
  // person with id = 5 updated with name 'Tom'.
});

// or chaining
connection.chain([
  Person.update(5, { name: 'Tom' })
], function(err, results) {
  // person with id = 5 updated with name 'Tom'.
});

Deletes the model object from the database

Arguments

• connection - The connection to use to delete the object with.
• callback(err) - The callback to be called when the delete is complete

Example

person1.delete(connection, function() {
  // person1 deleted
});

Gets an object from the database by id.

Arguments

• connection - The connection to use to delete the object with.
• id - The if of the item to get.
• callback(err, obj) - The callback to be called when the delete is complete

Example

Person.getById(connection, 1, function(err, person) {
  // person is the person with id equal to 1. Or null if not found
});

Creates a custom method that is a composition of clauses. this is set to refer to the query. you're constructing.

Arguments

• clauseName - The name of the clause to be attached to the model
• clauses - The function that describes the clause composition using a query.

Example

Person.defineClause('clauseName', function(arg1, arg2, ...) {
  return this.where('id < ?', arg1).orderBy('id').limit(5);
});

Person.clauseName(5).all(connection, function(err, people) {
  // All the people with id < 5, ordered by id and limited to 5
});

Person.defineClause('clauseName2', function(connection, callback) {
  return this
  .where('id < 5')
  .orderBy('id')
  .limit(5)
  .all(connection, callback);
});

Person.clauseName2(connection, function(err, people) {
  // All the people with id < 5, ordered by id and limited to 5
});

If preset this function will be called when an update or save occures. You would typically create this method in your model file.

Arguments

If preset this function will be called after an object is loaded from the database. You would typically create this method in your model file.

Arguments

• obj - The object that was just loaded from the database.
• connection - The connection persist is currently using to do the save
• callback() - The callback to be called when the onLoad is complete

Example

Person.onLoad = function(obj, connection, callback) {
  obj.fullName = obj.firstName + ' ' + obj.lastName;
  callback();
};

Model validation is loosely implemented. Instead, it's left to the developers to integrate any valiation library that fits their needs. If present this function will be called during a save or update operation.

Arguments

• obj - The model object
• connection - The connection persist is currently using to do the save or update
• callback(success, message) - The callback to be called when the validate is complete.
• success - False if validation failed, True otherwise
• message - A string containing an error message, or a custom-defined object containing vaidation information

Example

Person = persist.define("Person", {
  "name": type.STRING,
  "age": type.INTEGER
};

//Single message validation
Person.validate = function (obj, connection, callback) {
  if (obj.name === 'bad name') {
    return callback(false, 'You had a bad name');
  }
  return callback(true);
};

//Multiple message validation
Person.validate = function (obj, connection, callback) {
  var errors = [];

  if (obj.name === 'bad name') {
    errors.push({name:'You had a bad name'});
  }
  
  if (obj.age < 0) {
    errors.push({age:'Age must be greater than 0'});  
  }
  
  if(errors.length > 0) {
    return callback(false, errors);
  }
  
  return callback(true);
};

The following events can be registered when defining a new model:

• beforeCreate and afterCreate: fired before/after a new object is being added to the DB
• beforeUpdate and afterUpdate: fired before/after an existing object is being updated in the DB
• beforeSave and afterSave: fired before/after an object is either created or updated.
• beforeDelete and afterDelete: fired before/after an object is removed from the DB

Each event function has the signature: function(obj) where 'obj' is the model instance that fired the event.

Limitation

Events are currently fired ONLY when invoking save/update/delete functions on model instances. So for instance, Model.update(connection,id,data) will not fire the save & update events.

Example

Phone = persist.define("Phone", {
  "number": persist.String,
  "created_at": persist.DATETIME,
  "updated_at": persist.DATETIME
})
.on("beforeCreate", function(obj){
  obj.created_at = new Date();
})
.on("beforeSave", function(obj){
  // updated when creating or updating the model instance
  obj.updated_at = new Date();
});

Gets items from a query calling the callback for each item returned.

Arguments

Gets the first item from a query.

Arguments

Gets the last item from a query.

Arguments

Orders the results of a query.

Arguments

• propertyName - Name of the property to order by.
• direction - The direction to orderBy. Can be persist.Ascending or persist.Descending.

Returns

The query object suitable for chaining.

Example

Person.orderBy('name').all(connection, function(err, people) {
  // all the people ordered by name
});

Limits the number of results of a query.

Arguments

• count - Number of items to return.
• offset - (Optional) The number of items to skip.

Returns

The query object suitable for chaining.

Example

Person.orderBy('name').limit(5, 5).all(connection, function(err, people) {
  // The 5-10 people ordered by name
});

Filters the results by a where clause.

Arguments

• clause - A clause to filter the results by.
• values - (Optional) A single value or array of values to substitute in for '?'s in the clause.
• hash - A hash of columns and values to match on (see example)

Returns

The query object suitable for chaining.

Example

Person.where('name = ?', 'bob').all(connection, function(err, people) {
  // All the people named 'bob'
});

Person.where('name = ? or age = ?', ['bob', 23]).all(connection, function(err, people) {
  // All the people named 'bob' or people with age 23
});

Person.where({'name': 'bob', 'age': 23}).all(connection, function(err, people) {
  // All the people named 'bob' with the age of 23
});

Arguments

• property - The property to invoke the IN clause on.
• values - An array of values to include in the IN clause.

Returns

The query object suitable for chaining.

Example

Person.whereIn('name', ['bob', 'alice', 'cindy']).all(connection, function(err,people) {
  // All the people named 'bob', 'alice', or 'cindy'
});

Person.include("phones").whereIn('phones.number', ['111-2222','333-4444']).all(connection, function(err,people){
  // All the people whose phone numbers are '111-2222' or '333-4444'
});

Counts the number of items that would be returned by the query.

Arguments

Gets the minimum value in the query of the given field.

Arguments

Gets the maximum value in the query of the given field.

Arguments

Gets the sum of all values in the query of the given field.

Arguments

Deletes all the items specified by the query.

Arguments

Updates all the items specified by the query.

Arguments

Includes the associated data linked by (hasMany or hasMany(through)) the propertyName when retrieving data from the database. This will replace obj.propertyName with an array of results as opposed to the default before which is a query.

Internally this will do a join to the associated table in the case of a one to many. And will do a join to the associated through table and the associated table in the case of a many to many.

Arguments

• propertyName - This can be a single property name or an array of property names to include.

Example

Person.include("phones").where('name = ?', 'bob').all(connection, function(err, people) {
  // all people named 'bob' and all their phone numbers
  // so you can do... people[0].phones[0].number
  // as opposed to... people[0].phones.all(function(err, phones) {});
});

Commits a transaction.

Arguments

• callback(err) - Callback called when the transaction has committed.

Example

connection.tx(function(err, tx) {
  person1.save(connection, function(err) {
    tx.commit(function(err) {
      // person1 saved and committed to database
    });
  });
});

Rollsback a transaction.

Arguments

• callback(err) - Callback called when the transaction has rolledback.

Example

connection.tx(function(err, tx) {
  person1.save(connection, function(err) {
    tx.rollback(function(err) {
      // person1 not saved. Transaction rolledback.
    });
  });
});

Gets an item from the result set by id.

Arguments

• id - The id of the item to get.

Example

Person.all(connection, function(err, people) {
  var person2 = people.getById(2);
});