persistence.js

persistence.js is a asynchronous Javascript object-relational mapper library. It can be used both in the web browser and on the server using node.js. It currently supports 4 types of data stores:

• HTML5 WebSQL database, a somewhat controversial part of HTML5 that is supported in Webkit browsers, specifically on mobile devices, including iPhone, Android and Palm's WebOS.
• Google Gears, a browser plug-in that adds a number of feature to the browser, including a in-browser database.
• MySQL, using the node-mysql, node.js module on the server.
• In-memory, as a fallback. Keeps the database in memory and is cleaned upon a page refresh (or server restart), unless saved to localStorage.

There is also an experimental support for Qt 4.7 Declarative UI framework (QML) which is an extension to JavaScript.

For browser use, persistence.js has no dependencies on any other frameworks, other than the Google Gears initialization script, in case you want to enable Gears support.

Plug-ins

There are a few persistence.js plug-ins available that add functionality:

• persistence.search.js, adds simple full-text search capabilities, see docs/search.md for more information.
• persistence.migrations.js, supports data migrations (changes to the database schema), see docs/migrations.md for more information.
• persistence.sync.js, supports database synchronization with a remote server, see docs/sync.md for more information.
• jquery.persistence.js, adds jQuery integration, including jQuery-mobile ajax request interception and re-routing to persistencejs, see docs/jquery.md for more information and demo/jquerymobile for a simple demo.

A Brief Intro to Async Programming

In browsers, Javascript and the web page's rendering engine share a single thread. The result of this is that only one thing can happen at a time. If a database query would be performed synchronously, like in many other programming environments like Java and PHP the browser would freeze from the moment the query was issued until the results came back. Therefore, many APIs in Javascript are defined as asynchronous APIs, which mean that they do not block when an "expensive" computation is performed, but instead provide the call with a function that will be invoked once the result is known. In the meantime, the browser can perform other duties.

For instance, a synchronous database call call would look as follows:

var results = db.query("SELECT * FROM Table");
for(...) { ... }

The execution of the first statement could take half a second, during which the browser doesn't do anything else. By contrast, the asynchronous version looks as follows:

db.query("SELECT * FROM Table", function(results) {
  for(...) { ... }
});

Note that there will be a delay between the db.query call and the result being available and that while the database is processing the query, the execution of the Javascript continues. To make this clear, consider the following program:

db.query("SELECT * FROM Table", function(results) {
  console.log("hello");
});
console.log("world");

Although one could assume this would print "hello", followed by "world", the result will likely be that "world" is printed before "hello", because "hello" is only printed when the results from the query are available. This is a tricky thing about asynchronous programming that a Javascript developer will have to get used to.

Using persistence.js in the browser

Browser support

• Modern webkit browsers (Google Chrome and Safari)
• Firefox (through Google Gears)
• Opera
• Android browser (tested on 1.6 and 2.x)
• iPhone browser (iPhone OS 3+)
• Palm WebOS (tested on 1.4.0)
• Other browsers supporting localStorage (e.g. Firefox)

(The following is being worked on:) Internet Explorer is likely not supported (untested) because it lacks __defineGetter__ and __defineSetter__ support, which persistence.js uses heavily. This may change in IE 9.

Setting up

• Using bower:

bower install persistence

Add a <script> to your index.html:

lib/persistence.js needs to be added, as well as any data stores you want to use. Note that the mysql and websql stores both depend on the sql store. A typical setup requires you to add at least lib/persistence.js, lib/persistence.store.sql.js and lib/persistence.store.websql.js as follows:

<script src="/bower_components/persistencejs/lib/persistence.js"></script>
<script src="/bower_components/persistencejs/lib/persistence.store.sql.js"></script>
<script src="/bower_components/persistencejs/lib/persistence.store.websql.js"></script>

If you want to use the in-memory store (in combination with localStorage) you also need the persistence.store.memory.js included.

• Using directly from source:

  git clone git://github.com/zefhemel/persistencejs.git

Copy directories you will need following almost the same instructions above.

Setup your database

You need to explicitly configure the data store you want to use, configuration of the data store is store-specific. The WebSQL store (which includes Google Gears support) is configured as follows:

persistence.store.websql.config(persistence, 'yourdbname', 'A database description', 5 * 1024 * 1024);

The first argument is always supposed to be persistence. The second in your database name (it will create it if it does not already exist, the third is a description for you database, the last argument is the maximum size of your database in bytes (5MB in this example).

Setting up for Cordova with SQLitePlugin/WebSQL

Use following if you want to use persistencejs in a Cordova mobile app and you plan to use the Cordova SQLitePlugin:

persistence.store.cordovasql.config(
  persistence,
  'yourdbname',
  '0.0.1',                // DB version
  'My database',          // DB display name
  5 * 1024 * 1024,        // DB size (WebSQL fallback only)
  0,                      // SQLitePlugin Background processing disabled
  2                       // DB location (iOS only), 0 (default): Documents, 1: Library, 2: Library/LocalDatabase
                          //   0: iTunes + iCloud, 1: NO iTunes + iCloud, 2: NO iTunes + NO iCloud
                          //   More information at https://github.com/litehelpers/Cordova-sqlite-storage#opening-a-database
);

For more information on the SQLitePlugin background processing please refer to the SQLitePlugin readme.

The Cordova support in persistencejs will try to work with the SQLitePlugin if it is loaded; if not it will automatically fall back to WebSQL.

Please note that to use Cordova store, you must use the master branch, because it is not included up to release v0.3.0.

The in-memory store

The in-memory store is offered as a fallback for browsers that do not support any of the other supported stores (e.g. WebSQL or Gears). In principal, it only keeps data in memory, which means that navigating away from the page (including a reload or tab close) will result in the loss of all data.

A way around this is using the persistence.saveToLocalStorage and persistence.loadFromLocalStorage functions that can save the entire database to the localStorage, which is persisted indefinitely (similar to WebSQL).

If you're going to use the in-memory store, you can configure it as follows:

persistence.store.memory.config(persistence);

Then, if desired, current data can be loaded from the localStorage using:

persistence.loadFromLocalStorage(function() {
  alert("All data loaded!");
});

And saved using:

persistence.saveToLocalStorage(function() {
  alert("All data saved!");
});

Drawbacks of the in-memory store:

• Performance: All actions that are typically performed by a database (sorting, filtering), are now all performed in-memory using Javascript.
• Limited database size: Loading and saving requires serialization of all data from and to JSON, which gets more expensive as your dataset grows. Most browsers have a maximum size of 5MB for localStorage.
• Synchronous behavior: Although the API is asynchronous, all persistence actions will be performed synchronously on the main Javascript thread, which may make the browser less responsive.

Schema definition

A data model is declared using persistence.define. The following two definitions define a Task and Category entity with a few simple properties. The property types are based on SQLite types, specifically supported types are (but any SQLite type is supported):

• TEXT: for textual data
• INT: for numeric values
• BOOL: for boolean values (true or false)
• DATE: for date/time value (with precision of 1 second)
• JSON: a special type that can be used to store arbitrary JSON data. Note that this data can not be used to filter or sort in any sensible way. If internal changes are made to a JSON property, persistence.js may not register them. Therefore, a manual call to anObj.markDirty('jsonPropertyName') is required