search

yathit / ydn-db

Javascript database module for Indexeddb, Web SQL and localStorage storage mechanisms supporting version migration, advanced query, SQL and transaction.
Apache License 2.0
503 stars 41 forks source link

readme

Setup

To use this , include one of the ydn-db minified js files from download page in your HTML page.

Supported browsers

This library can be used in almost any browser.

Features

Examples

Schema definition

var schema = {
  stores: [{
    name: 'people',
    indexes: [{
       name: 'age'
    }, {
       name: 'age, name',
       keyPath: ['age', 'name']
    }]
  ]
}
db = new ydn.db.Storage('db-name', schema);

If the database exists, it will be opened and updated with the given schema if necessary. In doing so, object stores and indexes will be created or deleted.

Simple usage

Simple usage for opening, storing and retrieving by a primary key id1.

db = new ydn.db.Storage('db-name', schema);
db.put('people', {name: 'John', age: 10, sex: 'Male'}, 'id1');
db.get('people', 'id1').done(function(record) {
  console.log(record);
});

Query

The following snippet shows querying from the people object store using index age by a key range bounded by 25. The result will be sorted by age.

var q = db.from('people').where('age', '>=', 25);
var limit = 10;
q.list(limit).done(function(objs) {
  console.log(objs);
});

Sorting using an index with filtering on another index.

var q = db.from('people').where('age', '=', 25);
q.order('name').list().done(function(objs) {
  console.log(objs);
});

Note that the above sort query requires a compound index ['age', 'name'].

Transaction

By default, database requests are executed in separate transactions and executed in order. The following code snippet shows running all database requests in a single transaction.

var req = db.run(function update_prop (run_db) {
    run_db.get('player', 1).done(function(data) {
        data.health += 10;
        run_db.put('player', data).done(function(key) {
          if (data.health > 100) {
            req.abort();
          }
        });
      }
    }, ['player'], 'readwrite');
    req.then(function() {
      console.log('updated.');
    }, function(e) {
      console.log('transaction aborted');
});

Events

ydn.db.Storage dispatch events for connection and error. Additionally modification of records events can be installed by defining in schema.

Data heavy query should be execute after database connection is established by listening ready event.

db.onReady(function (err) {
  if (err) {
    console.error(err);
    return;
  }
  // heavy database operations should start from this.
);

Library developer guide

If you haven't try Closure Tools before, setup can be time consuming and painful. I recommend to read Michael Bolin book's Closure: The Definitive Guide. A good understanding of closure coding pattern is necessary to understand and follow this library codes.

Apache ant is used to build javascript compiler. ydn-base repo build.xml defines compiler and others tools setting. You must change according to your local machine setting. Specifically check property values of closure-library.dir and closure-compiler.dir, which point to respective directries.

Downloads the following three repos a directory.

svn checkout http://closure-library.googlecode.com/svn/trunk/
git clone git@bitbucket.org:ytkyaw/ydn-db.git
git clone https://bitbucket.org/ytkyaw/ydn-base.git

that should create three directories for closure-library, ydn-base and ydn-db.

Run local apache (recommended) or a static server on that directory.

Go to ydn-db folder and run ant deps and ant ydn-base.deps to generate closure dependency tree.

Use HTML files in the /test folder for getting started. These files are also used for debug development.

Note: we use master track version of closure tools. Compiling with pre-build jar may encounter compile error.

Note: precompile files are built by using custom compiler to strip debug messages. See detail on ydn-base/tools/strip_debug.txt.

Additional features requires the following optional repos.

  1. Full text search https://github.com/yathit/ydn-db-fulltext.git
  2. Dependency for ydn-db-fulltext https://github.com/yathit/fullproof
  3. Dependency for ydn-db-fulltext https://github.com/yathit/natural
  4. Synchronization https://bitbucket.org/ytkyaw/ydn-db-sync (private)

Testing

You should be able to run /ydn-db/test/all-test.html or run tests individually. Since all tests are async, disable run the 'in parallel' check box. These test files are for basic testing and debugging.

The coverage test is performed by JsTestDriver test. Notice that ant gen-alltest-js generates jsTestDriver.conf to prepare the testing configuration.

java -jar JsTestDriver.jar --tests all

End-to-end testing for distribution can be found in the test/qunit folder as well as online [qunit test kits] (http://dev.yathit.com/index/demos.html).

Deployment

For update bower, create a tag

git tag -a v1.3.3 -m "bug fixes"

and push the tag to github

git push origin master v1.3.3

Contributing

Sending pull requests is easiest. For large or architectual changes, please email one of the authors in the source code.

We follow the Google JavaScript Style Guide. All commits on the master branch must pass the most stringent compilation settings and pass all unit tests.

A few coding dialects we follow:

Library design

Bug reports

Please file an issue for bug reports describing how we could reproduce your problem. We will try address any subtle problems, memory and speed performance issues, and even extending the features of the IndexedDB API.

You may also ask questions in Stackoverflow #ydn-db with ydb-db hash, or follow us on Twitter @yathit.

License

Licensed under the Apache License, Version 2.0