SQLiteバージョン3.0は、SQLite2.8.13を基にしていますが、 ファイル形式とAPIに互換性を持たないSQLiteの新バージョンです。 SQLiteバージョン3.0は以下の要望に答えるために作成されました。
これらの機能を実装するためには、 データベース・ファイル形式への非互換な変更を必要とするので、 バージョン 3.0へ移行する必要がありました。 同時に、非互換な変更を一気に片づけるのが良いだろうという理屈で、 APIのクリーンアップなどの他の非互換な変更を導入しました。
バージョン 3.0のAPIは、バージョン2.X APIと似ていますが、 いくつかの大きな変更も伴います。 最も著しいのは、すべてのAPIファンクションとデータ構造の最初につく 「 sqlite_ 」プレフィックスは「 sqlite3_ 」に変わったことです。 これによって、両 API間の混乱を避けて、 SQLite 2.XとSQLite3.0の両方を同時にリンクすることができるようになりました。
UTF-16文字列のためのCデータ型式が何であるべきであるかに関する協定はまったくありません。 したがって、SQLiteは、UTF-16文字列を参照するのに何にでも使えるvoid*型を使用します。 クライアント・ソフトはvoid*をシステムにとって適切なデータ型式にキャストすることができます。
SQLite3.0のAPIは、いくつかのデータ構造と#defineと個別の関数83個を含んでいます。 (完全な APIリファレンス を別のドキュメントとして用意しました。) 幸い、インタフェースはサイズから考えるほどには複雑でありません。 簡単なプログラムなら3つの関数だけで間に合わせることができます。 （sqlite3_open()、 sqlite3_exec()、 sqlite3_close() 。） データベース・エンジンの実行を更にコントロールするには、 sqlite3_prepare() を使ってSQLステートメントをバイトコードへコンパイルした上で、 sqlite3_step() でバイトコードを実行します。 名前が sqlite3_column_ で始まっているルーチン郡は、クエリーの結果セットに関する情報を取り出すのに使います。 多くのインタフェース・ファンクションは UTF-8とUTF-16バージョンの両方とも入っています。 そして、ユーザ定義SQL関数とユーザ定義テキスト照合順序を実装するのに使われる ルーチンのコレクションがあります。
typedef struct sqlite3 sqlite3; int sqlite3_open(const char*, sqlite3**); int sqlite3_open16(const void*, sqlite3**); int sqlite3_close(sqlite3*); const char *sqlite3_errmsg(sqlite3*); const void *sqlite3_errmsg16(sqlite3*); int sqlite3_errcode(sqlite3*);
sqlite3_open() ルーチンは、バージョン2APIのようなsqlite3構造体へのポインタを返す方式ではなく、 整数値でエラーコードを返します。 sqlite3_open() と sqlite3_open16() の違いは sqlite3_open16() が UTF-16(ホストシステムのバイトオーダーで)をデータベース・ファイル名に取ることです。 新しいデータベース・ファイルを作成する必要があるとき、 sqlite3_open16() は内部テキスト表現をUTF-16に設定しますが、 sqlite3_open() はUTF-8に設定します。
データベース・ファイルのオープンや新規作成は、ファイルが実際に必要になってから実行されます。 ネイティブ・テキスト表現やデフォルト・ページサイズなどのオプションとパラメータは、 PRAGMAステートメントを使って設定できます。
sqlite3_errcode()ルーチンは、最後に呼び出した主要API呼び出しの結果コードを返します。sqlite3_errmsg()は、最後に起こったエラーのエラーメッセージを英語テキストで返します。 エラーメッセージは、UTF-8で表現され、次に何かSQLite APIファンクションを呼び出すと消えます。システム・バイトオーダーのUTF-16で表現されたエラーメッセージを返すこと以外、sqlite3_errmsg16()はsqlite3_errmsg()と同じように機能します。
SQLiteバージョン3のエラーコードはバージョン2から変更されていません。 エラーコードは以下の通りです:
#define SQLITE_OK 0 /* Successful result */ #define SQLITE_ERROR 1 /* SQL error or missing database */ #define SQLITE_INTERNAL 2 /* An internal logic error in SQLite */ #define SQLITE_PERM 3 /* Access permission denied */ #define SQLITE_ABORT 4 /* Callback routine requested an abort */ #define SQLITE_BUSY 5 /* The database file is locked */ #define SQLITE_LOCKED 6 /* A table in the database is locked */ #define SQLITE_NOMEM 7 /* A malloc() failed */ #define SQLITE_READONLY 8 /* Attempt to write a readonly database */ #define SQLITE_INTERRUPT 9 /* Operation terminated by sqlite_interrupt() */ #define SQLITE_IOERR 10 /* Some kind of disk I/O error occurred */ #define SQLITE_CORRUPT 11 /* The database disk image is malformed */ #define SQLITE_NOTFOUND 12 /* (Internal Only) Table or record not found */ #define SQLITE_FULL 13 /* Insertion failed because database is full */ #define SQLITE_CANTOPEN 14 /* Unable to open the database file */ #define SQLITE_PROTOCOL 15 /* Database lock protocol error */ #define SQLITE_EMPTY 16 /* (Internal Only) Database table is empty */ #define SQLITE_SCHEMA 17 /* The database schema changed */ #define SQLITE_TOOBIG 18 /* Too much data for one row of a table */ #define SQLITE_CONSTRAINT 19 /* Abort due to contraint violation */ #define SQLITE_MISMATCH 20 /* Data type mismatch */ #define SQLITE_MISUSE 21 /* Library used incorrectly */ #define SQLITE_NOLFS 22 /* Uses OS features not supported on host */ #define SQLITE_AUTH 23 /* Authorization denied */00 #define SQLITE_ROW 100 /* sqlite_step() has another row ready */ #define SQLITE_DONE 101 /* sqlite_step() has finished executing */
typedef int (*sqlite_callback)(void*,int,char**, char**); int sqlite3_exec(sqlite3*, const char *sql, sqlite_callback, void*, char**);
sqlite3_execファンクションは、SQLiteバージョン2のときと同じように動作します。 2番目のパラメータで指定されたSQLステートメントが、コンパイルされて実行されます。 クエリーの結果はコールバック・ルーチンに返されます。 詳しくは APIリファレンス を見てください。
SQLiteバージョン3では、sqlite3_execルーチンは prepared statement インタフェース呼び出しのためのラッパに過ぎません。
typedef struct sqlite3_stmt sqlite3_stmt; int sqlite3_prepare(sqlite3*, const char*, int, sqlite3_stmt**, const char**); int sqlite3_prepare16(sqlite3*, const void*, int, sqlite3_stmt**, const void**); int sqlite3_finalize(sqlite3_stmt*); int sqlite3_reset(sqlite3_stmt*);
sqlite3_prepareは、あとで実行するときのために単独のSQLステートメントをコンパイルします。 現在、このインタフェースはデータベースにアクセスするために都合のよい方法です。
sqlite3_prepare() のためのSQLステートメントはUTF-8文字列です。 sqlite3_prepare16()は、SQL入力としてUTF-16文字列を要求する以外、同じように動作します。 入力文字列の最初のSQLステートメントだけがコンパイルされます。 4番目のパラメータは、入力文字列における次の(コンパイルされていない)SQLiteステートメントが有ったなら、それが入ります。 sqlite3_finalize()ルーチンは構築済みSQLステートメントを解放します。 データベースを閉じる前にすべての構築済み・ステートメントを解放しなければなりません。sqlite3_reset()ルーチンは、再び構築済みSQLステートメントを実行することができるようにそれをリセットします。
SQLステートメントは、「?」｢nnn｣｢:nnn:｣という形のトークンを含むことが出来ます。（nnnは整数。） そのようなトークンは、後で sqlite3_bind インタフェースによって埋められる不特定のリテラル値(または、ワイルドカード)を表します。 各ワイルドカードに関連する番号は、「?」に続く「nnn」によって与えられます。 →「?」のあとに整数が続いていない場合、同じSQLステートメントの中の先行するワイルドカードの番号より一つ大きな番号です。同じSQLステートメントの中で同じワイルドカードが何度も存在できます。その場合、そのワイルドカードのすべてのインスタンスが同じ値で埋められます。 結合されていないワイルドカードは、NULLの値を持ちます。
int sqlite3_bind_blob(sqlite3_stmt*, int, const void*, int n, void(*)(void*)); int sqlite3_bind_double(sqlite3_stmt*, int, double); int sqlite3_bind_int(sqlite3_stmt*, int, int); int sqlite3_bind_int64(sqlite3_stmt*, int, long long int); int sqlite3_bind_null(sqlite3_stmt*, int); int sqlite3_bind_text(sqlite3_stmt*, int, const char*, int n, void(*)(void*)); int sqlite3_bind_text16(sqlite3_stmt*, int, const void*, int n, void(*)(void*)); int sqlite3_bind_value(sqlite3_stmt*, int, const sqlite3_value*);
構築済み SQLステートメントのワイルドカードに値を割り当てるのに使用されるsqlite3_bindルーチンのセットがあります。 結合（バインド）されていないワイルドカードはNULLとして解釈されます。 結合はsqlite3_reset()によってリセットされません。 しかし、ワイルドカードはsqlite3_reset()の後、新しい値へ再結合しているかもしれません。
SQLステートメントは、構築された後(結合はオプションです)、sqlite3_step()を使って実行できます。
int sqlite3_step(sqlite3_stmt*);
sqlite3_step()ルーチンは、結果セットの一行を返す場合SQLITE3_ROWを返し、普通に実行できた場合でもエラーの場合でも、実行が完了済みの場合SQLITE3_DONEを返します。 また、データベース・ファイルを開くことができないなら、SQLITE3_BUSYを返すかもしれません。 戻り値がSQLITE3_ROWなら、結果セットの行に関する情報を引き出すのに以下のルーチンを使用することができます。
const void *sqlite3_column_blob(sqlite3_stmt*, int iCol); int sqlite3_column_bytes(sqlite3_stmt*, int iCol); int sqlite3_column_bytes16(sqlite3_stmt*, int iCol); int sqlite3_column_count(sqlite3_stmt*); const char *sqlite3_column_decltype(sqlite3_stmt *, int iCol); const void *sqlite3_column_decltype16(sqlite3_stmt *, int iCol); double sqlite3_column_double(sqlite3_stmt*, int iCol); int sqlite3_column_int(sqlite3_stmt*, int iCol); long long int sqlite3_column_int64(sqlite3_stmt*, int iCol); const char *sqlite3_column_name(sqlite3_stmt*, int iCol); const void *sqlite3_column_name16(sqlite3_stmt*, int iCol); const unsigned char *sqlite3_column_text(sqlite3_stmt*, int iCol); const void *sqlite3_column_text16(sqlite3_stmt*, int iCol); int sqlite3_column_type(sqlite3_stmt*, int iCol);
sqlite3_column_count() ファンクションは、結果セットのカラムの数を返します。sqlite3_column_count()は、sqlite3_prepare()の後ならいつでも呼び出すことが出来ます。 sqlite3_data_count()は、sqlite3_step()の次に働くことを除いて、sqlite3_column_count()と同じです。前回の呼び出しでsqlite3_step()がSQLITE_DONEかエラーコードを返していたなら、sqlite3_data_count()は0を返しますが、sqlite3_column_count()は、結果セットのカラム数を返し続けます。
返されたデータは、その他の sqlite3_column_***() 関数を使って検査できます。これらの関数は、カラムナンバーを 2 番目の引数にとります。 カラムは、左から右へ 0 から始まるインデックスが付きます。 1 から始まるインデックスを付けられる引数ではないことに注意を払ってください。
sqlite3_column_type()ファンクションはNカラム目の値のデータ型式を返します。 戻り値は下記のうちの一つです。
#define SQLITE_INTEGER 1 #define SQLITE_FLOAT 2 #define SQLITE_TEXT 3 #define SQLITE_BLOB 4 #define SQLITE_NULL 5
sqlite3_column_decltype()ルーチンはCREATE TABLEステートメントのカラムで宣言されている型をテキストで返します。 戻り値は空の文字列の場合があります。sqlite3_column_name()はNカラム目の名前を返します。sqlite3_column_bytes()は、BLOB型カラムのバイト数、または、UTF－8エンコーディングでのTEXT文字列のバイト数を返します。 sqlite3_column_bytes16()はBLOBの場合同じ値を返しますが、TEXT文字列の場合はUTF16エンコーディングでのバイト数を返します。 sqlite3_column_blob()は、BLOBデータを返します。 sqlite3_column_text()は、UTF-8でTEXTデータを返します。 sqlite3_column_text16()は、UTF-16でTEXTデータを返します。 sqlite3_column_int()は、ホストマシンのネイティブint形式でINTEGERデータを返します。 sqlite3_column_int64()は、64ビットINTEGERを返します。 sqlite3_column_double()は、浮動小数点データを返します。
データを検索するのに sqlite3_column_type()でフォーマットを特定する必要はありません。 異なったフォーマットが要求されたら、データは自動的に変換されます。
以下のルーチンを使用するとユーザ定義関数を作成することができます。
typedef struct sqlite3_value sqlite3_value; int sqlite3_create_function( sqlite3 *, const char *zFunctionName, int nArg, int eTextRep, void*, void (*xFunc)(sqlite3_context*,int,sqlite3_value**), void (*xStep)(sqlite3_context*,int,sqlite3_value**), void (*xFinal)(sqlite3_context*) ); int sqlite3_create_function16( sqlite3*, const void *zFunctionName, int nArg, int eTextRep, void*, void (*xFunc)(sqlite3_context*,int,sqlite3_value**), void (*xStep)(sqlite3_context*,int,sqlite3_value**), void (*xFinal)(sqlite3_context*) ); #define SQLITE_UTF8 1 #define SQLITE_UTF16 2 #define SQLITE_UTF16BE 3 #define SQLITE_UTF16LE 4 #define SQLITE_ANY 5
nArgパラメータにはファンクションの引数の数を指定します。 値が0の場合は、どんな引数も容認されるのを示します。 eTextRepパラメータは、このファンクションの引数で、どんなテキスト表現が要求されるか指定します。 このパラメータの値は上記で定義されたパラメータの1つであるべきです。 SQLiteバージョン3は、異なったテキスト表現を使用することで同じファンクションの複数の実装を容認します。 データベース・エンジンは、必要とするテキスト変換が最小になるようにファンクションを選びます。
通常の関数には、 xStepとxFinalをNULLに設定して、xFuncだけを指定します。 集約関数には、xStepとxFinalを指定して、xFuncをNULLに設定します。個別のsqlite3_create_aggregate() APIは有りません。
関数名は UTF-8で指定します。 関数名をUTF-16ホスト・バイトオーダーで指定するのを除いて、sqlite3_create_function16() APIはsqlite_create_function()と同じように機能します。
関数の引数が SQLiteバージョン2.X.のような文字列へのポインタではなく、今ではsqlite3_value構造体へのポインタだということに注意してください。以下のルーチンは、これらの値から有用な情報を取り出すときに使われます。:
const void *sqlite3_value_blob(sqlite3_value*); int sqlite3_value_bytes(sqlite3_value*); int sqlite3_value_bytes16(sqlite3_value*); double sqlite3_value_double(sqlite3_value*); int sqlite3_value_int(sqlite3_value*); long long int sqlite3_value_int64(sqlite3_value*); const unsigned char *sqlite3_value_text(sqlite3_value*); const void *sqlite3_value_text16(sqlite3_value*); int sqlite3_value_type(sqlite3_value*);
ファンクションの実装は、コンテキストを取得するためと結果を報告するために以下の APIを使用します。
void *sqlite3_aggregate_context(sqlite3_context*, int nbyte); void *sqlite3_user_data(sqlite3_context*); void sqlite3_result_blob(sqlite3_context*, const void*, int n, void(*)(void*)); void sqlite3_result_double(sqlite3_context*, double); void sqlite3_result_error(sqlite3_context*, const char*, int); void sqlite3_result_error16(sqlite3_context*, const void*, int); void sqlite3_result_int(sqlite3_context*, int); void sqlite3_result_int64(sqlite3_context*, long long int); void sqlite3_result_null(sqlite3_context*); void sqlite3_result_text(sqlite3_context*, const char*, int n, void(*)(void*)); void sqlite3_result_text16(sqlite3_context*, const void*, int n, void(*)(void*)); void sqlite3_result_value(sqlite3_context*, sqlite3_value*); void *sqlite3_get_auxdata(sqlite3_context*, int); void sqlite3_set_auxdata(sqlite3_context*, int, void*, void (*)(void*));
以下のルーチンは、ユーザ定義の照合順序を実装するのに使います。
sqlite3_create_collation(sqlite3*, const char *zName, int eTextRep, void*, int(*xCompare)(void*,int,const void*,int,const void*)); sqlite3_create_collation16(sqlite3*, const void *zName, int eTextRep, void*, int(*xCompare)(void*,int,const void*,int,const void*)); sqlite3_collation_needed(sqlite3*, void*, void(*)(void*,sqlite3*,int eTextRep,const char*)); sqlite3_collation_needed16(sqlite3*, void*, void(*)(void*,sqlite3*,int eTextRep,const void*));
sqlite3_create_collation()ファンクションは、照合順序を実装するために照合順序名と比較関数を指定します。 比較関数は、テキスト値を比較するのに使用されるだけです。 eTextRepパラメータには、比較関数が機能するテキスト表現を特定するためにSQLITE3_UTF8、SQLITE3_UTF16LE、 SQLITE3_UTF16BE、SQLITE3_ANYのどれか一つを指定します。 UTF-8、UTF-16LE、UTF-16BEテキスト表現それぞれのための比較関数が、同じ照合順序のために存在できます。sqlite3_create_collation16()は、UTF-8ではなくホスト・バイト・オーダのUTF-16で照合順序名を指定すること以外、同じように機能します。
sqlite3_collation_needed()ルーチンは、データベース・エンジンが未知の照合順序に遭遇したときに呼び出すコールバックを登録します。 コールバックは適切な照合関数を探して、必要ならsqlite_3_create_collation()を呼び出すことが出来ます。コールバックの4番目の引数は、UTF-8の照合順序の名前です。 sqlite3_collation_needed16() の場合、コールバックにはUTF-16ホスト・バイトオーダーで照合順序の名前が送られます。