Indexed Database API について

HTML5 JavaScript

Indexed Database API（以下、indexedDB）について、これまで追いかけてきた情報をとりまとめたので公開します。

indexedDBは当初は仕様が固まっておらず、サンプルコードも当然のように動かなかったので（今も動きませんが…）、検証するにはかなりハードな状況でした。最近になってどうにか動くようになってきたので、@komasshu さんと色々やり取りしながら一通りの動作を確認しました。

現時点で利用できるブラウザは Chrome 9 以降 または Firefox 4 beta 8 以降となります。まだまだ仕様は動いていますので、検証の際は、なるべく最新の開発版を使うことをおすすめします。本エントリーでは、Chrome 9 beta 、Firefox 4 beta 8 にて検証します。また、資料は、2011年1月20日時点の W3C Editor's Draft を参照しています。


1. Indexed Database API とは
indexedDBは、ブラウザが持つ NoSQL ベースのデータベースです。オリジン（Origin*1）ごとに固有の領域を持ち、複数のデータベースを保持することができます。


2. 基本的な使い方
(1) データベースの作成（接続）
現時点では indexedDB（IDBFactory）にベンダープリフィックスを付けてアクセスします。Chrome であれば、webkitIndexedDB。Firefoxであれば moz_indexedDB（beta8）、または mozIndexedDB（beta9）です。


サンプルコード1

//Chrome、Firefoxのベンダープリフィックス対応
var indexedDB = window.indexedDB || window.webkitIndexedDB || window.mozIndexedDB || window.moz_indexedDB;

//データベース作成（接続）
var db = null;
var req = indexedDB.open("library");

//成功時コールバック
req.onsuccess = function(evt) {
    db = evt.result;
};

//失敗時コールバック
req.onerror = function(err) {
    alert(err.code + ":" + err.message);
};

データベース操作の結果は、リクエスト（IDBRequest)のコールバックに登録することになります。


(2) オブジェクトストア・インデックスの作成
オブジェクトストアは、データを格納するための入れ物です。RDBMSのテーブルに相当します。オブジェクトストア、及びインデックスの作成と削除はデータベースのバージョン変更時にしか行うことができませんので、注意が必要です。


サンプルコード2

//DBのバージョン変更
var verReq = db.setVersion("1.0");
verReq.onsuccess = function(evt) {

    //オブジェクトストア作成（in-line key として isbn を指定）
    var store = db.createObjectStore("books", "isbn", false);

    //Chromeの場合、以下のように記載
    //var store = db.createObjectStore("books", {"keyPath": "isbn"}, false);

    //インデックス作成
    store.createIndex("name", false);
};

オブジェクトストアには、各データを一意に識別するキーが必要です。キーは、createObjectStore の第2引数で指定します。キーには、2種類あり、キーを指定した場合の in-line key 、省略した場合の out-of-line key があります。キーの種類、及び第3引数の autoIncrement の値でデータ追加時の動作が異なります。


・in-line key
データ内のプロパティをキーとします。データ追加時には、該当プロパティに値が存在する必要があります。
autoIncrement が true の場合、該当プロパティは存在しなくても問題ありません。


・out-of-line key
データの外にキーを持ちます。データ追加時には、別途キーを渡す必要があります。
autoIncrement が true の場合、別途キーを渡す必要はありません。


(3) データの追加・削除
オブジェクトストアに格納できるデータは、その名の通りオブジェクト（structured clone*2）です。データはトランザクションを経由して操作します。


サンプルコード3

//Chromeのベンダープリフィックス対応
var IDBTransaction = window.IDBTransaction || window.webkitIDBTransaction;

//データ作成
var book = {
    name: "徹底解説 HTML5 APIガイドブック コミュニケーション系API編",
    description: "AjaxやHTTPで高速なリアルタイム通信アプリケーション開発を可能にする新APIの仕様と使い方を詳細に解説。",
    author: "小松 健作",
    isbn: "4798028215"
};

//トランザクションの開始とオブジェクトストアの取得
var store = db.transaction([], IDBTransaction.READ_WRITE).objectStore("books");

//データ追加
store.add(book);    //putでも同様の結果が得られる


//データ削除
store.delete("4798028215");

オブジェクトストア作成時に、isbn を in-line key に指定しているので、データ作成時に値をセットした isbn が key になります。ただし Chrome では、まだ in-line key の指定が無視されるので、コメントのように記述しないと動作しません。createObjectStoreに第2引数に{"keyPath": "isbn"}のように指定すると動作するようです。

有効なキーは、string、date、long、float です。null 及び floatの Inifinite は有効なキーですが、NaN は無効です。また、undefined は許可されていません。


(4) データの検索・変更
データの検索方法には、1件だけ取得する get と 複数取得するための openCursor があり、データを変更したい場合、openCursor で取得してから行います。


サンプルコード4　〜　データの検索

//トランザクションの開始とオブジェクトストアの取得
var store = db.transaction().objectStore("books");

//Firefox4の場合、transactionの引数の省略ができないのでnullを入れておく
//var store = db.transaction(null).objectStore("books");

//get
var req = store.get("4798028215");
req.onsuccess = function(evt) {
    var value = evt.result;
    console.log(value);
};

//openCursor、インデックス経由で取得
var req = store.index("name").openCursor("徹底解説 HTML5 APIガイドブック コミュニケーション系API編");
req.onsuccess = function(evt) {
    var cursor = evt.result;
    if ( cursor ) {
        console.log(cursor.value);

        //Firefox4の場合、index経由だとvalueにkeyが入っているので再度検索
        //var getReq = store.get(key).onsuccess = function(getEvt){
        //    console.log(getEvt.result);
        //};
        cursor.continue();
    }
};

get の結果に複数のデータがある場合は、最初の1件のみ取得できます。また、インデックスを利用する場合も get 、openCorsor 等、同様のメソッドがあるので同じ方法で取得することができます。


サンプルコード5　〜　データの変更

//Chromeのベンダープリフィックス対応
var IDBKeyRange= window.IDBKeyRange|| window.webkitIDBKeyRange;

//トランザクションの開始とオブジェクトストアの取得（READ_WRITE）
var store = db.transaction([], IDBTransaction.READ_WRITE).objectStore("books");

//キーを範囲指定するにはIDBKeyRangeを使う。
var req = store.openCursor(IDBKeyRange.lowerBound("4844329278", false));

req.onsuccess = function(evt) {
    var cursor = evt.result;
    if ( cursor ) {
        //description変更、changedフラグ追加
        var book = cursor.value;
        book.description = "updated";        
        book.changed = true;

        //データ変更反映
        cursor.update(book);
        cursor.continue();
    }
};

データの変更を行う場合は、トランザクションを READ_WRITE で開始します。カーソルを使ってデータを取得後、変更し、同じくカーソルの update メソッドを介して変更を反映します。プロパティの追加なども問題なくできます。


(5) その他 Tips
・データのソート
オブジェクトストア内のデータは、キーの昇順で格納されています。そのため、昇順で取得する必要があれば、そのまま取得します。降順で取得したければ、openCursor 時の第2引数で、IDBCursor.PREV を指定します。インデックスでも同様です。

//Chromeでの実行例
var req = db.transaction().objectStore("books").index("name").getCursor("", webkitIDBCursor.PREV);
req.onsuccess = function(evt) {
    var cursor = evt.result;
    if ( cursor ) {

        //降順にデータ取得
        console.log(cursor.value);
        cursor.continue();
    }
};

応用として、最少値、最大値を取得したい場合は、対象のプロパティにインデックスを作成して、最初の1件を取得すれば求められます。

キーの順序は、string、date、longとfloatとなっており、longとfloatはその数値で比較されます。


・トランザクションのコミットとロールバック
トランザクションのコミットは、別のトランザクションが開始されるか、トランザクションが発生したメソッドが終了すれば、暗黙的にコミットされます。ロールバックはエラーやタイムアウトが発生した場合には自動的にロールバックされますが、明示的に指定したい場合は、abort を使います。

//トランザクション開始
var tx = db.transaction([], IDBTransaction.READ_WRITE);

/*
 複数のデータ操作
*/

//トランザクションの中断とロールバック
tx.abort();


データベースのバージョン変更時は、リクエストの result に入っているトランザクションを使ってロールバックします。

//トランザクション開始
var req = db.setVersion("1.1");
req.onsuccess = function(evt) {
    var tx = evt.result;

    /*
     スキーマの変更など
     */

    //トランザクションの中断とロールバック
    tx.abort();
};


3. 簡易API一覧
IDBFactory

メソッド・プロパティ 説明 コメント
open(name) nameで指定されたDBを作成する。
既に存在していればDBに接続する。		 ○ ○ 以前あった第2引数のdescriptionは
なくなりました
deleteDatabase(name) nameで指定されたDBを削除する。 - - 未実装

IDBRequest

メソッド・プロパティ 説明 コメント
onsuccess リクエスト成功時コールバック ○ ○
onerror リクエスト失敗時コールバック ○ ○
readyState リクエストの状態
LOADING: 実行中
DONE: 完了		 ○ ○

IDBDatabase

メソッド・プロパティ 説明 コメント
name DB名 ○ ○
objectStoreNames DBに格納されている全オブジェクトストアの名前 ○ ○
version DBのバージョン ○ ○
close() DB接続を閉じる。 - ○
createObjectStore(name, keyPath, autoIncrement) nameで指定されたオブジェクトストアを作成する。 △ ○ Chrome は keyPath を{"keyPath": "keyPath"}のようにオブジェクトで渡します。
deleteObjectStore(name) nameで指定されたオブジェクトストアを削除する。 ○ ○
setVersion(version) DBバージョンを更新する。 ○ ○ 以下のメソッドは、バージョン更新のコールバックでしか実行できない。
createObjectStore
deleteObjectStore
createIndex
deleteIndex
transaction(storeNames, mode, timeout) storeNamesで指定されたオブジェクトストア（デフォルト：全オブジェクトストア）を対象としてトランザクションを開始する。
modeでトランザクションの種類を指定する。
READ_ONLY: 読込専用
READ_WRITE: 書込可能
VERSION_CHANGE: バージョン更新
（デフォルト：READ_ONLY）
timeout
ミリ秒単位（デフォルト：ブラウザ固有）		 ○ ○ 引数はすべてオプションだが、Firefox は transaction() のような記述ができない。Chrome、Firefoxともにtimeoutは無視される。

IDBObjectStore

メソッド・プロパティ 説明 コメント
name オブジェクトストア名 ○ ○
keyPath キーのプロパティ名 ○ ○
indexNames オブジェクトストアに設定されたインデックス名 ○ ○
put(value, key) オブジェクトストアにデータを追加する。keyは、オブジェクトストア作成時に、キーとキーの自動生成を指定しない場合に必須となる。 ○ ○
add(value, key) putと同様。 ○ ○
delete(key) key（リテラルのキー値）のデータを削除する。 ○ ○
get(key) key（リテラルのキー値または、IDBKeyRange）のデータを取得する。複数ある場合は、最初の1件を返す。 △ ○ ChromeはIDBKeyRangeでの指定ができない。
clear() すべてのデータを削除する。keyは - ○
openCursor(range, direction) range（リテラルのキー値または、IDBKeyRange）で指定された範囲のデータを取得する。directionで取得順序を指定する。（IDBCursor）
NEXT: 昇順
NEXT_NO_DUPLICATE: 昇順（重複なし）
PREV: 降順
PREV_NO_DUPLICATE: 降順（重複なし）		 △ △ rangeについて、ChromeはIDBKeyRangeでの指定ができない。逆にFirefoxでは、リテラルのキー値での指定ができない。
createIndex(name, keyPath, unique) keyPathで指定したプロパティを対象とするインデックスを作成する。uniqueで一意性を指定する。 ○ ○
index(name) インデックスを取得する。 ○ ○
deleteIndex(indexName) インデックスを削除する。 ○ ○

IDBIndex

メソッド・プロパティ 説明 コメント
name インデックス名 ○ ○
storeName インデックスの対象とするオブジェクトストア名 ○ ○
keyPath インデックスの対象とするプロパティ名 ○ ○
unique 一意であるか ○ ○
get(key) key（リテラルのキー値または、IDBKeyRange）のデータを取得する。複数ある場合は、最初の1件を返す。 △ △ ObjectStoreの同名のメソッドと同様。Firefoxの場合、インデックス経由の取得結果はキーとなる。
getKey(key) getと同様だが、取得対象がキーとなる。 △ ○
openCursor(range, direction) range（リテラルのキー値または、IDBKeyRange）で指定された範囲のデータを取得する。directionで取得順序を指定する。（IDBCursor）
NEXT: 昇順
NEXT_NO_DUPLICATE: 昇順（重複なし）
PREV: 降順
PREV_NO_DUPLICATE: 降順（重複なし）		 △ △ ObjectStoreの同名のメソッドと同様。Firefoxの場合、インデックス経由の取得結果はキーとなる。
openKeyCursor(range, direction) openCursorと同様だが、取得対象がキーとなる。 △ △

IDBCursor

メソッド・プロパティ 説明 コメント
direction 走査方向
NEXT: 昇順
NEXT_NO_DUPLICATE: 昇順（重複なし）
PREV: 降順
PREV_NO_DUPLICATE: 降順（重複なし）		 ○ ○
key カーソルを開くときに使用したキー ○ ○
value カーソルの現ポジションのデータ ○ △ Firefoxの場合、インデックス経由では、キーとなる。
continue(key) カーソルの現ポジションを次の走査方向へ進める。イベントが再発生し、カーソルの現ポジションが更新される。key（リテラルのキー値または、IDBKeyRange）を指定した場合、該当するキーまでカーソルを進める。 △ △ Chrome、Firefoxともにkeyの指定は受け付けない。
delete() カーソルの現ポジションのデータを削除する。 ○ ○
update(value) カーソルの現ポジションのデータをvalueで更新する。 - ○

IDBTransaction

メソッド・プロパティ 説明 コメント
mode トランザクションの種類
READ_ONLY: 読込専用
READ_WRITE: 書込可能
VERSION_CHANGE: バージョン更新		 ○ ○ 以前あった、SNAPSHOT_READはなくなりました。
db 接続しているデータベース。 ○ ○
objectStore(name) トランザクションの対象となるオブジェクトストアの中からnameで指定されたオブジェクトストアを取得する。 ○ ○
abort() トランザクションを中断し、ロールバックする。 ○ ○
onabort トランザクション中断時のコールバック ○ ○
oncomplete トランザクション完了時のコールバック ○ ○
ontimeout タイムアウト時のコールバック - -


4. おわりに
indexDB は、まだまだ実装途中です。バージョンが変われば、そのままのコードでは動かなくなる可能性がかなり高いので、本格的なアプリを作れるようになるには、もう少し時間がかかるでしょう。それでも是非、試してみたいという方は、本エントリーを参考にして頂ければ幸いです。もちろん、（自称）html5-developers-jp indexedDB担当としては、今後もメンテナンスしていきたいと思いますので、ご指摘、ご質問等あればコメントでもMLでもツイッターでもお気軽にどうぞ！


まだまだ書くこともたくさんありますが（手元のサンプルコードもリファクタリングして公開しないといけないですし…）、まずはこのぐらいで。
@komasshu さんのこてさきAjax indexedDB を触ってみたも合わせてどうぞ

*1:origin … プロトコル、ドメイン、ポートからなる、Webサイトを指し示す固有の情報。URLとは似て非なるもの。

*2:structured clone … オブジェクトから、関数と循環参照などを排除したもの。単純なリテラル、Date、Object、Arrayを含む。