Documentation Home -  API Home

database

Provides access to a simple database of key/value pairs. Keys are always strings. Values can be of type string, number, or boolean. Where other object types and values are to be persisted in the database you should make use of the JSON system library.

Note: Chrome Server operates a database transaction over the lifecycle of an HTTP request operation. If any error is thrown including user exceptions thrown during script evaluation, exceptions thrown during execution of the display function, and any exceptions or errors thrown by the Chrome Server system software, the transaction will be rolled back. When and if the request processing completes successfully the transaction will be committed. All transactions are operated in READ COMMITTED isolation mode.

The following example illustrates the basic load/save lifecycle operations on the database as they might be used in a typical page script:

// Variable to make available to the displayed form:
var username;

// Load the current name from the database
function loadName() {
   var name = database.load('name');
   if( !name ) {
      name = 'Not Yet Set';
   }
}

// Save the name to the database
function saveName(name) {
   database.save('name',name);
}

function display() {
   if( request.method === 'POST' ) {
      var name = request.getParameter('name');
      if( name ) {
         saveName(name);
      }
      renderer.redirect('/name');
   } else {
      username = loadName();
      renderer.display();
   }
}

Normally you will have access to the key used to persist a value; you cannot search the values for free text strings (this feature may be available in future versions of Chrome Server). However you can retrieve an object representing the list of keys ordered by the key value or by the creation or last-updated times via the keys() function.

The database object refers to the application global database. You can create additional named database instances for the application using the open(name) function.

Functions

database.open(name)

function
Parameters
namestringThe name of the database to open
Returns
databaseThe new or existing database as appropriate

Creates a new database for the application with the given name, or opens one if it already exists. The object returned can be manipulated exactly as the default database object but has a completely different namespace for its keys.

// Save a value in the global (anonymous) database
database.save('speedoflight','Very fast!');

// Create a new named database
var constantsDb = database.open('constants');

// Save a value in the named database with the same key
constantsDb.save('speedoflight',299792458);

// These two values loaded with the same key will be different
var lightDescription = database.load('speedoflight');
var lightSpeed = constantsDb.load('speedoflight');

Note that the databases exist in a flat table where the global database is anonymous (has no name) and all other database names occupy the same space. The names are therefore not hierarchical - for example the statement var db = database.open('foo').open('foo').open('foo'); effectively creates a single database, not three.

database.delete(key)

function
Parameters
keystringThe key for the value to delete from the database

Deletes the value with the given key from the database.

database.load(key)

function
Parameters
keystringThe key against which to store the value
Returns
objectThe stored string, number, or boolean value (or null if none exists for the given key)

Loads a value from the database with the given key. The value loaded will be equivalent to the previous value saved using the given key. The value loaded will always be a string, number, or boolean, or be null if no entry exists in the database for the key provided.

Where object values (e.g Date objects) have been saved to the database using the JSON.stringify(object) function you can recreate them from saved data using the JSON.parse(value) function.

database.save(key,value)

function
Parameters
keystringThe key value against which to store the value in the database. Must not be null or undefined.
valueobjectThe string, number, or boolean value to save. Must not be null or undefined.

Note that you cannot save Javascript objects such as Date() directly as values in the database or use them directly as keys; to save an object to the database first convert it to a string using the JSON system library.

system('json',1);

function saveCustomer(customer) {
   var s_customer = JSON.stringify(customer);
   database.save('customer',s_customer);
}

function loadCustomer(key) {
   var s_customer = database.load('customer');
   if( s_customer ) {
      return JSON.parse(s_customer);
   } else {
      throw 'Customer not found';
   }
}

When retrieving a value from the database you will usually want to perform a null check on the returned value (as shown in the function loadCustomer(key) in the example above) before trying to use it in subsequent application logic - code that does not perform checks of this type will be difficult to diagnose when the database does not contain the expected value(s).

database.keys()

function
Returns
DatabaseKeyListAn object representing the keys used to index values in the database object

Returns a DatabaseKeyList object to represent the set of keys used to index the data in the database object. The keys can be retrieved as a list, and can be sorted by the key name, the date that the value was initially created in the database, or when it was last updated. The sort order can be reversed.

Terms & Conditions