From 6919c9586d68f6fd9baacea0b8bc21d6eb9beb7b Mon Sep 17 00:00:00 2001 From: Tim Griesser Date: Mon, 14 Oct 2013 08:17:05 -0400 Subject: [PATCH] documentation updates for 0.4.10 release --- docs/assets/behavior.js | 4 +- docs/clients/base/grammar.html | 11 ++- docs/clients/base/sqlite3/grammar.html | 3 +- docs/clients/pool.html | 31 +++++---- docs/clients/server/mysql/grammar.html | 2 + docs/clients/server/mysql/schemagrammar.html | 4 +- docs/knex.html | 4 +- docs/lib/common.html | 9 ++- docs/lib/schemabuilder.html | 8 +++ index.html | 71 +++++++++++++++++--- knex.js | 4 +- 11 files changed, 116 insertions(+), 35 deletions(-) diff --git a/docs/assets/behavior.js b/docs/assets/behavior.js index 3ce0f727..46141d05 100644 --- a/docs/assets/behavior.js +++ b/docs/assets/behavior.js @@ -545,8 +545,8 @@ f.event={add:function(a,c,d,e,g){var h,i,j,k,l,m,n,o,p,q,r,s;if(!(a.nodeType===3 "type": "heading", "data": { "level": 2, - "title": "Knex.js 0.4.9", - "slug": "knexjs-049" + "title": "Knex.js 0.4.10", + "slug": "knexjs-0410" }, "depth": 2 } diff --git a/docs/clients/base/grammar.html b/docs/clients/base/grammar.html index 5213226f..0b4c7c14 100644 --- a/docs/clients/base/grammar.html +++ b/docs/clients/base/grammar.html @@ -33,14 +33,17 @@ to keep the interface database agnostic.

},

Compiles the select statement, or nested sub-selects by calling each of the component compilers, trimming out the empties, and returning a generated query string.

compileSelect: function(qb) { - var sql = {}; + var sql = []; if (_.isEmpty(qb.columns)) qb.columns = ['*']; for (var i = 0, l = components.length; i < l; i++) { var component = components[i]; var result = _.result(qb, component); if (result != null) { - sql[component] = this['compile' + Helpers.capitalize(component)](qb, result); + sql.push(this['compile' + Helpers.capitalize(component)](qb, result)); } + }

If there is a transaction, and we have either forUpdate or forShare specified, +call the appropriate additions to the select statement.

if (qb.transaction && qb.flags.selectMode) { + sql.push(this['compile' + qb.flags.selectMode](qb)); } return _.compact(sql).join(' '); },

Compiles an aggregate query.

compileAggregate: function(qb) { @@ -180,6 +183,10 @@ query to be used for insert and update without issue.< return 'delete from ' + table + ' ' + where; },

Compiles a truncate query.

compileTruncate: function(qb) { return 'truncate ' + this.wrapTable(qb.table); + },

Adds a for update clause to the query, relevant with transactions.

compileForUpdate: function() { + return 'for update'; + },

Adds a for share clause to the query, relevant with transactions.

compileForShare: function() { + return 'for share'; },

Puts the appropriate wrapper around a value depending on the database engine, unless it's a knex.raw value, in which case it's left alone.

wrap: function(value) { var segments; diff --git a/docs/clients/base/sqlite3/grammar.html b/docs/clients/base/sqlite3/grammar.html index 194893ad..eafc9e5b 100644 --- a/docs/clients/base/sqlite3/grammar.html +++ b/docs/clients/base/sqlite3/grammar.html @@ -49,7 +49,8 @@ then join them all together with select unions to complete the queries.

sql.push('delete from sqlite_sequence where name = ' + table); sql.push('delete from ' + table); return sql; - } + },

For share and for update are not available in sqlite3.

compileForUpdate: function() {}, + compileForShare: function() {} }, baseGrammar); diff --git a/docs/clients/pool.html b/docs/clients/pool.html index 92bf5af5..dff4c612 100644 --- a/docs/clients/pool.html +++ b/docs/clients/pool.html @@ -16,29 +16,30 @@ the pool if it doesn't already exist.

_.bindAll(this, 'acquire', 'release'); this.config = config; this.client = client; + if (!config || !client) { + throw new Error('The config and client are required to use the pool module.'); + } this.init(); }; - Pool.prototype = {

Some basic defaults for the pool... generally you don't really want to keep -mutable objects on the prototype, but in this case we're not supposed to be -messing around with them, so it should be alright.

defaults: function() { - var poolInstance = this; + Pool.prototype = {

Some basic defaults for the pool...

defaults: function() { + var pool = this; return { min: 2, max: 10, create: function(callback) { - var promise = poolInstance.client.getRawConnection() + var promise = pool.client.getRawConnection() .tap(function(connection) { connection.__cid = _.uniqueId('__cid'); - if (poolInstance.config.afterCreate) { - return nodefn.call(poolInstance.config.afterCreate, connection); + if (pool.config.afterCreate) { + return nodefn.call(pool.config.afterCreate, connection); } }); return nodefn.bindCallback(promise, callback); }, destroy: function(connection) { - if (poolInstance.config.beforeDestroy) { - return poolInstance.config.beforeDestroy(connection, function() { + if (pool.config.beforeDestroy) { + return pool.config.beforeDestroy(connection, function() { connection.end(); }); } @@ -57,10 +58,14 @@ options passed into the constructor.

this.poolInstance.release(connection, callback); },

Tear down the pool, only necessary if you need it.

destroy: function(callback) { var poolInstance = this.poolInstance; - poolInstance.drain(function() { - poolInstance.destroyAllNow(callback); - }); - delete this.poolInstance; + if (poolInstance) { + poolInstance.drain(function() { + poolInstance.destroyAllNow(callback); + }); + delete this.poolInstance; + } else { + callback(); + } return this; } diff --git a/docs/clients/server/mysql/grammar.html b/docs/clients/server/mysql/grammar.html index 89613f4e..2073b5ef 100644 --- a/docs/clients/server/mysql/grammar.html +++ b/docs/clients/server/mysql/grammar.html @@ -8,6 +8,8 @@ if (builder.type === 'insert') response = [response.insertId]; if (builder.type === 'delete' || builder.type === 'update') response = response.affectedRows; return response; + },

Adds a for share clause to the query, relevant with transactions.

compileForShare: function() { + return 'lock in share mode'; } }, baseGrammar);
\ No newline at end of file diff --git a/docs/clients/server/mysql/schemagrammar.html b/docs/clients/server/mysql/schemagrammar.html index 48e087a1..ef3e56b2 100644 --- a/docs/clients/server/mysql/schemagrammar.html +++ b/docs/clients/server/mysql/schemagrammar.html @@ -16,8 +16,8 @@ var sql = baseSchemaGrammar.compileCreateTable.call(this, builder, command); var conn = builder.client.connectionSettings; - if (conn.charset) sql += ' default character set ' + conn.charset; - if (conn.collation) sql += ' collate ' + conn.collation; + if (builder.flags.charset || conn.charset) sql += ' default character set ' + (builder.flags.charset || conn.charset); + if (builder.flags.collation || conn.collation) sql += ' collate ' + (builder.flags.collation || conn.collation); if (builder.flags.engine) { sql += ' engine = ' + builder.flags.engine; }

Checks if the table is commented

var isCommented = this.getCommandByName(builder, 'comment');

TODO: Handle max comment length.

var maxTableCommentLength = 60; diff --git a/docs/knex.html b/docs/knex.html index a557dc90..1d532369 100644 --- a/docs/knex.html +++ b/docs/knex.html @@ -1,4 +1,4 @@ -knex
knex.js

Knex.js 0.4.9

(c) 2013 Tim Griesser
+knex
knex.js
Knex.js  0.4.10
(c) 2013 Tim Griesser
 Knex may be freely distributed under the MIT license.
 For details and documentation:
 http://knexjs.org
@@ -52,7 +52,7 @@ rather than wait on an async load of a client library.
};
     });
Method to run a new Raw query on the current client.
    knex.raw = function(sql, bindings) {
       return new Raw(knex).query(sql, bindings);
-    };
Keep a reference to the current client.
    knex.client = client;
Keep in sync with package.json
    knex.VERSION = '0.4.9';
Runs a new transaction, taking a container and returning a promise
+    };
Keep a reference to the current client.
    knex.client = client;
Keep in sync with package.json
    knex.VERSION = '0.4.10';
Runs a new transaction, taking a container and returning a promise
 for when the transaction is resolved.
    knex.transaction = function(container) {
       return new Transaction(knex).run(container);
     };
Return the new Knex instance.
    return knex;
diff --git a/docs/lib/common.html b/docs/lib/common.html
index 6bfb3012..504dac12 100644
--- a/docs/lib/common.html
+++ b/docs/lib/common.html
@@ -69,8 +69,15 @@ and have it come out fine.
    transacting: function(t) {
       if (t) {
         if (this.transaction) throw new Error('A transaction has already been set for the current query chain');
+        var flags = this.flags;
         this.transaction = t;
-        this.usingConnection = t.connection;
+        this.usingConnection = t.connection;
Add "forUpdate" and "forShare" here, since these are only relevant
+within the context of a transaction.
        this.forUpdate = function() {
+          flags.selectMode = 'ForUpdate';
+        };
+        this.forShare = function() {
+          flags.selectMode = 'ForShare';
+        };
       }
       return this;
     }
diff --git a/docs/lib/schemabuilder.html b/docs/lib/schemabuilder.html
index 32f6cd5a..13737593 100644
--- a/docs/lib/schemabuilder.html
+++ b/docs/lib/schemabuilder.html
@@ -43,6 +43,14 @@
       if (!this.creating()) throw new Error('The `engine` modifier may only be used while creating a table.');
       this.flags.engine = name;
       return this;
+    },
Sets the character set for the table in MySql
    charset: function(charset) {
+      if (!this.creating()) throw new Error('The `engine` modifier may only be used while creating a table.');
+      this.flags.charset = charset;
+      return this;
+    },
Sets the collation for the table in MySql
    collate: function(collation) {
+      if (!this.creating()) throw new Error('The `engine` modifier may only be used while creating a table.');
+      this.flags.collation = collation;
+      return this;
     },
Adds a comment to the current table being created.
    comment: function(comment) {
       return this._addCommand('comment', {comment: comment});
     },
Indicate that the given columns should be dropped.
    dropColumn: function(columns) {
diff --git a/index.html b/index.html
index 73a8605e..755a7f0a 100644
--- a/index.html
+++ b/index.html
@@ -185,7 +185,7 @@
+

+ forUpdate.transacting(t).forUpdate() +
+ Dynamically added after a transaction is specified, + the forUpdate adds a FOR UPDATE in PostgreSQL and MySQL during a select statement. +

+ +

+ forShare.transacting(t).forShare() +
+ Dynamically added after a transaction is specified, + the forShare adds a FOR SHARE in PostgreSQL and a LOCK IN SHARE MODE + for MySQL during a select statement. +

count.count(column) @@ -1076,6 +1097,12 @@ knex.schema.table('users', function (table) { }); +

+ dropTableIfExistsknex.schema.dropTableIfExists(tableName) +
+ Drops a table conditionally if the table exists, specified by tableName. +

+

Schema Building:

@@ -1202,19 +1229,33 @@ knex.schema.table('users', function (table) { char(36) in other databases.

-

- enginetable.engine(val) -
- Sets the engine for the database, only available within a createTable call, and only - applicable to MySQL. -

-

commenttable.comment(value)
Sets the comment for a table.

+

+ enginetable.engine(val) +
+ Sets the engine for the database table, only available within a createTable call, and only + applicable to MySQL. +

+ +

+ charsettable.charset(val) +
+ Sets the charset for the database table, only available within a createTable call, and only + applicable to MySQL. +

+ +

+ collatetable.collate(val) +
+ Sets the collation for the database table, only available within a createTable call, and only + applicable to MySQL. +

+

specificTypetable.specificType(column, value)
@@ -1362,6 +1403,16 @@ knex.raw('select * from users where id = 1').then(function(resp) {

Change Log

+

+ 0.4.10 — Oct 14, 2013 — Diff
+

    +
  • Added forUpdate and forShare for select modes in transactions. (#84)
    • +
  • Fix bug where current query chain type is not copied on clone. (#90)
    • +
  • Charset and collate are now added as methods on the schema builder. (#89)
    • +
  • Internal pool fixes. (#90)
    • +
+

+

0.4.9 — Oct 7, 2013 — Diff

    diff --git a/knex.js b/knex.js index d8412ec8..7c98074c 100644 --- a/knex.js +++ b/knex.js @@ -1,4 +1,4 @@ -// Knex.js 0.4.9 +// Knex.js 0.4.10 // -------------- // (c) 2013 Tim Griesser @@ -91,7 +91,7 @@ define(function(require, exports, module) { knex.client = client; // Keep in sync with package.json - knex.VERSION = '0.4.9'; + knex.VERSION = '0.4.10'; // Runs a new transaction, taking a container and returning a promise // for when the transaction is resolved.