January 2015

Here are the release notes for January 2015. Modules in scope and dependencies can be found on GitHub

January 5th 2015

This is a large update with every single library updated. The main changes are

• Transactions are now supported for all drivers, and rollback is implemented for Drive, Memory, Sheets, Properties and Scratch. For more information on transactions see Working with transactions. Transactions behavior can be turned on and off with an option when taking a handler. See locking behavior for details. A transaction looks like this

var result = handler.transaction ( function (db) {


  // all these operations are protected by an exclusive lock
  var r = handler...

  var r = handler...

  // return a normal results to package to say whether transaction succeeded
  // if rollback is supported, everything will be rolled back to pre transaction state on error
  return r;

});

if (result.transaction.code < 0 ) {
  // there was an error
}

• Locking behavior is now consistent across all databases. By default, named locks are used to protect complete transactions, or to protect non transactional individual operations that update the database. SAVE, UPDATE and REMOVE operations are locked by default, whereas QUERY, GET, COUNT are not. Locking and transaction behavior can be changed by an option when taking a handler. You can decide whether multi user access is likely and trade off performance against consistency. Valid values are TRANSACTIONS.ENABLED (default) and TRANSACTIONS.DISABLED, and LOCKING.ENABLED (default), LOCKING.DISABLED and LOCKING.AGGRESSIVE (locks every database access including QUERY, GET and COUNT).

 var handler = new cDbAbstraction.DbAbstraction (driver , {
    "transactions": cDbAbstraction.dhConstants.TRANSACTIONS.ENABLED,
    "locking" : cDbAbstraction.dhConstants.LOCKING.ENABLED
  });

• DriverOrchestrate now has constraints implemented to allow the same complex queries as all the other back ends. Orchestrate uses Lucene for querying, which is fairly far away from the others but I have finally got around to simulating noSQL queries with Lucene. I still do not really recommend Orchestrate in a multi-user environment as there seems to be a significant delay (I’ve compensated somewhat for it but it’s still flaky) between updates being committed and them percolating through the Orchestrate system.
• DriverScratch. This is a new back end that is entirely transient, living in cache. Since the syntax for all backends is the same, using a transient backend for testing is a great way to avoid leaving lots of test data around. You can play around with DriverScratch until you are ready to use real data. By default, data will live for 1 hour, but the clock will restart each time you access it. I plan to use this backend for communication between triggered tasks, and also as an interactive logger for running scripts. By default the cache used is private for the library/user, but you can modify that to be public, pass your own cache over, or use cachecommunity settings to restrict access as described in Driver DbAbstraction. The siloed and dbid can be anything you want – they need to be known by collaborators, so you should think about an application/api key type structure as a standard as suggested below. You take a handler like this

var handler = new cDbAbstraction.DbAbstraction ( cDriverScratch , {
  dbid:'your invented api key',
  siloid:'your invented application key',
  scratchexpiry:60*60, // default is die after one hour
  private:false, // default is true for cache restricted to you
  cachecommunity:'optionally some community to share with'
  
 });

• DataHandler is still supported, but only default values are now available for these new capabilities. I recommend switching to getting handlers via DbAbstraction. DataHandler will likely be deprecated later in the year. 
• DataStore. Cloud datastore does not support creating indexes on the fly through the JSON API. This means that some complex queries don’t work and return an error 412. I haven’t found a workaround for this yet. 
• Caching updates. Voiding cache is handled automatically, so you don’t have the danger of picking up a stale cached result. Cache is voided for a database when it detects a change has been made. With this change, it’s no longer necessary to select disablecache when getting a handle, or on individual operations, although the option is still supported.
• Testing. All these changes have been exercised using Running things in parallel using HTML service to simulate a complex simultaneous multi-user environment.

Structural changes. 

In order to accommodate transactions, all drivers have had some fairly major structural changes. Please report any unusual behavior on the forum.