SQLiteConnector

概要

SQLite向けに実装された DBConnector の派生クラスです。 このクラスはモバイル版でのみ利用できます。

このクラスはコネクションプールをサポートしません。

コンストラクタ

構文

new SQLiteConnnector({ database, version })
new SQLiteConnnector({ database, version, onConfigure, onCreate, onUpgrade, onDowngrade, onOpen })

引数

単一の、以下のプロパティを持つオブジェクトです。

• database: string

  データベース名です。

• version: number

  データベースのバージョンです。この値はSQLiteの PRAGMA コマンド（PRAGMA user_version=<バージョン>）によって設定されるユーザバージョンです。

  指定する値は 1 以上の整数でなければなりません。

  プロパティ database で指定したデータベースが既に存在し、ユーザバージョンが設定されている場合、設定されたユーザバージョンと引数として与えた version プロパティの値の比較によって、データベースのバージョン変更のためのコールバック関数が呼び出されます。

• onConfigure: function （省略可）

  データベースに初めて接続する際に、一度だけ呼び出されるコールバック関数です。

  コールバック関数として、引数を持たない関数を指定します。 コールバック関数が Promise を返す場合、プロパティ onOpen に設定したコールバック関数の呼び出しの前に、その履行を待ち合わせます。 コールバック関数の返す Promise でない値や Promise の履行の際に与えられる値は無視されます。

  プロパティ onConfigure に設定されたコールバック関数は、プロパティ onCreate, onUpgrade, onDowngrade, onOpen に設定したコールバック関数より先に呼び出されます。

  このプロパティの指定は任意です。指定がない場合、何も行われません。

• onCreate: function （省略可）

  データベースに初めて接続する際に、一度だけ呼び出されるコールバック関数です。 このコールバック関数は、指定のデータベースが未作成の場合にのみ呼び出されます。

  コールバック関数として、引数を持たない関数を指定します。 コールバック関数が Promise を返す場合、プロパティ onOpen に設定したコールバック関数の呼び出しの前に、その履行を待ち合わせます。 コールバック関数の返す Promise でない値や Promise の履行の際に与えられる値は無視されます。

  プロパティ onConfigure にコールバック関数が設定されている場合、onCreate に設定したコールバック関数はそれより後に呼び出されます。

  プロパティ onOpen にコールバック関数が設定されている場合、onCreate に設定したコールバック関数はそれより先に呼び出されます。

  このプロパティの指定は任意です。指定がない場合、何も行われません。

• onUpgrade: function （省略可）

  データベースに初めて接続する際に、一度だけ呼び出されるコールバック関数です。 このコールバック関数は、指定のデータベースが作成済みかつ、引数として与えた version プロパティの値が対象のデータベースのユーザバージョンより新しい（大きい）場合にのみ呼び出されます。

  コールバック関数として、以下の引数を持つ関数を指定します。

  • oldVersion: number

    データベースに設定されているユーザバージョンです。 第1引数として与えられます。

  • newVersion: number

    引数のプロパティ version で指定した新しいユーザバージョンです。 第2引数として与えられます。

  コールバック関数が Promise を返す場合、プロパティ onOpen に設定したコールバック関数の呼び出しの前に、その履行を待ち合わせます。 コールバック関数の返す Promise でない値や Promise の履行の際に与えられる値は無視されます。

  プロパティ onConfigure にコールバック関数が設定されている場合、onUpgrade に設定したコールバック関数はそれより後に呼び出されます。

  プロパティ onOpen にコールバック関数が設定されている場合、onUpgrade に設定したコールバック関数はそれより先に呼び出されます。

  このプロパティの指定は任意です。指定がない場合、何も行われません。

• onDowngrade: function （省略可）

  データベースに初めて接続する際に、一度だけ呼び出されるコールバック関数です。 このコールバック関数は、指定のデータベースが作成済みかつ、引数として与えた version プロパティの値が対象のデータベースのユーザバージョンより古い（小さい）場合にのみ呼び出されます。

  コールバック関数として、以下の引数を持つ関数を指定します。

  • oldVersion: number

    データベースに設定されているユーザバージョンです。 第1引数として与えられます。

  • newVersion: number

    引数のプロパティ version で指定した新しいユーザバージョンです。 第2引数として与えられます。

  コールバック関数が Promise を返す場合、プロパティ onOpen に設定したコールバック関数の呼び出しの前に、その履行を待ち合わせます。 コールバック関数の返す Promise でない値や Promise の履行の際に与えられる値は無視されます。

  プロパティ onConfigure にコールバック関数が設定されている場合、onDowngrade に設定したコールバック関数はそれより後に呼び出されます。

  プロパティ onOpen にコールバック関数が設定されている場合、onDowngrade に設定したコールバック関数はそれより先に呼び出されます。

  このプロパティの指定は任意です。指定がない場合、何も行われません。

• onOpen: function （省略可）

  データベースに初めて接続する際に、一度だけ呼び出されるコールバック関数です。

  コールバック関数として、引数を持たない関数を指定します。 コールバック関数が返す値は無視されます。

  プロパティ onOpen に設定されたコールバック関数は、プロパティ onConfigure, onCreate, onUpgrade, onDowngrade に設定したコールバック関数より後に呼び出されます。

  このプロパティの指定は任意です。指定がない場合、何も行われません。

例外

• TypeError
  • 引数のプロパティ database に文字列が指定されていない場合
  • 引数のプロパティ version に数値が指定されていない場合
  • 引数のプロパティ version の値が整数でなかった場合
  • 引数のプロパティ version の値が 0 以下だった場合
  • 引数のプロパティ onConfigure に関数でも nullish でもない値が指定された場合
  • 引数のプロパティ onCreate に関数でも nullish でもない値が指定された場合
  • 引数のプロパティ onUpgrade に関数でも nullish でもない値が指定された場合
  • 引数のプロパティ onDowngrade に関数でも nullish でもない値が指定された場合
  • 引数のプロパティ onOpen に関数でも nullish でもない値が指定された場合

解説

SQLiteConnector のインスタンスを生成します。

引数のプロパティとして以下のコールバック関数を指定できます：

• onConfigure
• onCreate
• onUpgrade
• onDowngrade
• onOpen

これらのコールバック関数は、生成された SQLiteConnector インスタンスを使って初めてデータベースへ接続する際に呼び出されます。

それぞれのコールバック関数が呼び出される条件は以下の通りです：

• onConfigure

  データベースへ接続する際に呼び出されます。

• onCreate

  データベースへ接続する際、プロパティ database で指定したデータベースがまだ作成されていない場合に呼び出されます。

• onUpgrade

  データベースへ接続する際、プロパティ database で指定したデータベースが作成済みで、プロパティ version で指定したバージョンが、対象のデータベースのユーザバージョンより新しかった場合に呼び出されます。

• onDowngrade

  データベースへ接続する際、プロパティ database で指定したデータベースが作成済みで、プロパティ version で指定したバージョンが、対象のデータベースのユーザバージョンより古かった場合に呼び出されます。

• onOpen

  データベースへ接続する際に呼び出されます。

それぞれのコールバック関数の実行順序は以下の通りです：

1. onConfigure
2. 接続先のデータベースの状態によって分岐：
   • データベース未作成: onCreate
   • データベース作成済みかつ、現在のユーザバージョンより新しいバージョンが指定された: onUpgrade
   • データベース作成済みかつ、現在のユーザバージョンより古いバージョンが指定された: onDowngrade
3. onOpen

コールバック関数の呼び出しはデータベース接続の際に呼び出されますが、データベース接続自体は SQLiteConnector のインスタンス生成のタイミングとは一致しません。

メソッド

end()

• この関数は何も行いません。

execute()

• SQL文を実行します。

connect()

• この関数は何も行いません。

disconnect()

• この関数は何も行いません。

createTable()

• 指定されたテーブル定義情報からテーブルを作成します。

dropTable()

• 指定されたテーブルを削除します。

getSchema()

• データベースの定義情報を取得します。

fixPreparedStatementQuery()

• この関数は何も行いません。

asIdentifier()

• 文字列をデータベースで使用する識別子として変換します。

asString()

• 文字列をデータベースで使用する文字列リテラルに変換します。

asValue()

• データをデータベースで使用する値リテラルに変換します。