SQLiteバージョン3.0は、SQLiteの新バージョンであり、派生元のSQLite 2.8.13コード・ベースとは、非互換性のファイル・フォーマットおよびAPIを備えています。SQLiteバージョン3.0は次の機能要求に答えるために作成されました:
これらの機能を実装するためには、データベース・ファイル・フォーマットに非互換な変更が必要であり、バージョン3.0に移行せざるを得 ませんでした。APIの磨き上げなど他の非互換な変更は、非互換な大幅変更は一斉にやるのが最良であるというセオリーの下で、同時に導入しました。
バー ジョン3.0用のAPIは、バージョン2.X APIに似ていますが、いくつかの重要な変更があります。最初に目に付くのは、すべてのAPI機能とデータ構造の先頭に付く接頭辞が、"sqlite_" から"sqlite3_"へ変更されたことです。これは、2つのAPIの間の混乱を回避し、SQLite 2.XおよびSQLite 3.0の両方を同時にリンクすることを可能にします。
UTF-16文字列のためのCのデータ型が何であるべきかについて、明確な合意はあり ません。したがって、SQLiteは、UTF-16文字列を参照するために汎用型の void* を使用します。クライアント・ソフトウェアは、それらのシステムにとって適切なデータ型へ void* をキャストしてください。
SQLite 3.0のAPIは、83個の関数と、いくつかのデータ構造および #defines を含んでいます。(完全なAPIリファレンスは別個のドキュメントとして提供されます。)このインターフェースは、その量が意味するほど複雑ではないので安心してください。
単純なプログラムでは、いまでも3つの関数
だけで間に合います。
データベース・エンジンの実行に対するより多くの制御を行うには
を使用します。
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() ルーチンは整数エラーコードを返します。バージョン2インターフェースが行っていたように構造体へのポインターを返すのではありません。
sqlite3_open() と sqlite3_open16() の違いは、データベースファイルの名前として、sqlite3_open16()がUTF-16(ホスト・バイトオーダー)形式を受け取ることです。新し いデータベースファイルを作成する必要がある場合、sqlite3_open16()は内部のテキスト表現[1]をUTF-16形式にセットします。一方、sqlite3_open()はテキスト表現をUTF-8形式にセットします。
ファイルが実際に必要になるまでデータベース・ファイルの open/create は遅延されます。これは、ネイティブテキスト表現やデフォルトのページサイズのようなオプションおよびパラメーターを、PRAGMAステートメントを使って設定することを可能にします。
sqlite3_errcode()関数は、直近の主API呼び出しについてのリザルトコードを返します。
sqlite3_errmsg()関数は、直近のエラーについての英文エラーメッセージを返します。エラーメッセージはUTF-8形式で表現され、寿命は一時的です（次のSQLite API関数呼び出しによって消えるかもしれません。)
sqlite3_errmsg16()関数は、それがUTF-16(ホスト・バイトオーダー)形式のエラーメッセージを返すという点を除いて、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 */ #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**);
SQLiteバージョン2と同様に、sqlite3_exec関数は多くの働きをします。第2パラメーターの中で指定されたゼロ個以上 のSQLステートメントをコンパイルして実行し、クエリ結果をコールバック関数に返します。さらなる情報は、APIリファレンスを参照してください。
SQLiteバージョン3において、sqlite3_exec関数は、prepareステートメントのインタフェース呼び出しを包む単なるラッパーです。
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ステートメントだけがコンパイルされます。入力ストリング中の次の(未コンパイルの)SQL[2]ステートメントがもしあれば、第4引数にそのポインターが書き入れられます。
sqlite3_finalize()関数はprepare済みSQLステートメントを廃棄します。データベースを閉じる前に、prepare済みステートメントはすべてfinalizeしておかねばなりません。
sqlite3_reset()関数は、再実行できるようにprepare済みSQLステートメントをリセットします。
SQLステートメントには次の書式トークンを含むことができます。
"nnn"は整数で、"aaa"は識別名です。[3]
こ れらのトークンは、後ほどsqlite3_bindインターフェースによって埋め込まれる不定リテラル値(つまりワイルドカード)を表します。各ワイルド カードは対応する番号を持っており、それはステートメント中での出現順番、または、"?nnn"書式の場合には"nnn"の数値で決まります。同じワイル ドカードは同じSQLステートメント中で二度以上出現することが許されます。その場合、そのワイルドカードの全ての実体に、同じ値が埋め込まれるでしょ う。埋め込みをしなかった(unbound)ワイルドカードは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*);
sqlite3_bind関数群は、prepare済みSQLステートメント中のワイルドカードに、値を埋め込むために使用します。埋 め込みをしなかった(unbound)ワイルドカードは、NULLとして解釈されます。一旦埋め込んだものはsqlite3_reset()によってリ セットされません。しかし、ワイルドカードはsqlite3_reset()の後に新しい値を再埋め込みできます。
prepareを済ませた(必要ならbindも済ませた)後のSQLステートメントは、次のものを使用して実行されます:
int sqlite3_step(sqlite3_stmt*);
sqlite3_step()関数は、結果セットの単一の列を返している間は、SQLITE_ROWを返します。そして正常あるいはエ ラーにより実行が完了すると、SQLITE_DONEを返します。データベース・ファイルを開くことができない場合には、SQLITE_BUSYを返すか もしれません。
返り値がSQLITE_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_***()関数を使用して、調べることができます。それらの関数は皆、第二引数にカラム番号をとります。 カラムは左から右へ、0から順にインデックス番号が割り振られています。引数(1から始まるインデックス付け)とは、異なることに注意してください。
sqlite3_column_type()関数は、n番目のカラムの値についてデータ型を返します。返り値はこれらのうちの1つです:
#define SQLITE_INTEGER 1
#define SQLITE_FLOAT 2
#define SQLITE_TEXT 3
#define SQLITE_BLOB 4
#define SQLITE_NULL 5
データを取り出す場合、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引数は、関数の引数の個数を指定します。その値が-1なら、任意個数の引数を受け付けることを示します。[4]
eTextRep 引数は、この関数へ渡されるテキスト値に、どの表現形式(エンコード)を期待しているかを示します。この引数の値は上で定義された定数のうちの1つでなけ ればなりません。SQLiteバージョン3は、異なるテキスト表現形式(エンコード)を使用する同名関数を多重定義することを許しています。データベー ス・エンジンは、テキストの(エンコード)変換回数が最小となる関数を選択します。
通常関数は、xFunc引数へのみ設定し、xStep引数とxFinal引数はNULLを設定します。
集計関数は、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引数には、比較関数がどのテキスト表現形式(エンコード)で働くか明示するため SQLITE_UTF8、SQLITE_UTF16LE、SQLITE_UTF16BEあるいはSQLITE_ANYのうちの1つを指定します。[5]同 じ照合順序に対し、UTF-8、UTF-16LEおよびUTF-16BEテキスト表現形式(エンコード)のそれぞれについて個別の比較関数を設定できま す。照合順序の名が、UTF-8形式の代わりにUTF-16(ホスト・のバイトオーダー)形式で指定されるという点を除いて、 sqlite3_create_collation16()はsqlite3_create_collation()と同じ動作です。
sqlite3_collation_needed ()関数は、未知の照合順序に出合った場合にデータベース・エンジンが起動するコールバック関数を登録します。このコールバック関数は、適切な比較関数を 見つけ出し、また求められるようなsqlite_3_create_collation()を起動します。コールバック関数の第４引数はUTF-8形式の 照合順序名です。sqlite3_collation_need16()関数は、コールバック関数に、UTF-16(ホスト・バイトオーダー)形式の照合 順序名を渡します。