PRAGMA command は、SQLite ライブラリの動作を変更したり （テーブル以外の）内部データについてライブラリに問い合わせるために使う特殊な コマンドです。 PRAGMA コマンドは、（SELECT、INSERT のような）他の SQLite コマンドと同じ インターフェースを使って発行しますが、以下の重要な点が異なっています。
利用できるプラグマは、基本的な 4 つのカテゴリーに分類されます。
| sql-statement ::= | PRAGMA name [= value] | PRAGMA function(arg) |
整数値をとるプラグマは、シンボル名を受け入れます。 文字列 "on"、"true"、"yes" は、1 と等価です。 文字列 "off"、"false"、"no" は、0 と等価です。 これらの文字列は大文字小文字を区別せず、クオートも必要ありません。 認識できない文字列は、1 として扱われ、エラーにはなりません。 値 が返されるときは、整数値として返されます。
PRAGMA auto_vacuum;
PRAGMA auto_vacuum = 0 | none | 1 | full | 2 | incremental;
データベース内の auto-vacuum フラグを設定または問い合わせします。
通常（つまり、auto_vacuum が 0 または "none" のとき）、データベースからデータを削除する トランザクションがコミットされる時、データベースファイルの大きさは変化しません。 使われなくなったデータベースファイルページが "freelist" に追加されると、次回の挿入で 再利用されます。 データベースファイルは小さくなりません。 このモードにおいて、VACUUM コマンドを未使用空間の回収に 使用できます。
auto-vacuum フラグが 1 （full）のとき、フリーリストページはファイルの終端に移動され、 そしてコミットするたびに、ファイルがフリーリストページ削除のために切り詰められます。 しかしながら auto-vacuum は、ファイルからフリーリストページを切り詰めるだけであることに 注意してください。 auto-vacuum は、VACUUM コマンドがするようにデータベースを デフラグしたり個々のデータベースページを詰め込み直したりはしません。 実際、auto-vacuum はファイル内でページの移動をするので、フラグメンテーションを 悪化させる場合があります。
auto-vacuum は、各データベースページを参照側から逆向きにトレースできるよう若干の 付加的な情報をデータベースが保存している場合のみ、可能になります。 そのため、auto-vacuum は、テーブルが作成される前にオンになっていなければなりません。 auto-vacuum は、テーブルが作成された後は有効化も無効化もできません。
auto-vacuum の値が 2（incremental）の場合、auto-vacuum に必要な付加情報は データベースファイルに追加されますが、auto_vacuum==full のように各コミットごとに auto-vacuum が自動的に起こったりはしません。 incremental モードでは、vacuum を実行するために個々に incremental_vacuum プラグマを 呼び出さなければなりません。
データベース接続は、full と incremental の間で好きなように autovacuum モードを 変えられます。 しかしながら接続は、データベース内にテーブルが作成された後で "none" モードにまたは "none" モードから変更することはできません。
PRAGMA cache_size;
PRAGMA cache_size = Number-of-pages;
SQLite が同時にメモリー内に保持するデータベースディスクページの最大数を問い合わせまたは 変更します。 各ページは、メモリーを 1.5K 使用します。 デフォルトキャッシュサイズは、2000 です。 データベースの多くの行を変更する UPDATE あるいは DELETE をしていて SQLite の メモリー使用量を気にしない場合、速度改善のためにキャッシュの大きさを増やすことができます。
cache_size プラグマを使ってキャッシュサイズを変更したとき、変更は現在のセッション内のみ 持続します。 データベースを閉じてから再開すると、キャッシュの大きさはデフォルト値に戻ります。 default_cache_size プラグマが、 恒久的なキャッシュサイズを調べるために使えます。
PRAGMA case_sensitive_like;
PRAGMA case_sensitive_like = 0 | 1;
LIKE 演算子のデフォルト動作は、latin1 キャラクター用に大文字小文字の違いを無視します。 従ってデフォルトでは、'a' LIKE 'A' は true です。 case_sensitive_like プラグマをオンにするとこの動作を変更できます。 case_sensitive_like を有効化すると 'a' LIKE 'A' は false になりますが、 'a' LIKE 'a' は true のままです。
PRAGMA count_changes;
PRAGMA count_changes = 0 | 1;
count-changes フラグを問い合わせあるいは変更します。 通常、count-changes フラグをセットしないと INSERT、UPDATE、DELETE ステートメントは データを返しません。 count-changes がセットされている場合、これらの各コマンドは、コマンドによって挿入、変更、 削除された行の数を一つの整数値からなる単一のデータ行として返します。 返される変更の数は、トリガーによって実行された挿入、変更、削除を含みません。
PRAGMA default_cache_size;
PRAGMA default_cache_size = Number-of-pages;
SQLite が同時にメモリー上に確保するデータベースディスクページの最大数を問い合わせあるいは 変更します。 各ページは、ディスク上で 1K メモリー内で 1.5K 使用します。 このプラグマは、恒久的にキャッシュサイズを変更する追加の機能と共に cache_size プラグマのように動作します。 このプラグマで一度キャッシュサイズを変更すると、その設定が保持されデータベースを 開くたびに再使用されます。
PRAGMA default_synchronous;
このプラグマは、バージョン 2.8 で利用可能になりましたが、バージョン 3.0 で削除されました。 これは、使用を推奨されない危険なプラグマです。 このプラグマの使用からバージョン 2.8 ユーザーを救うため、このドキュメントでは動作を 説明しません。
PRAGMA empty_result_callbacks;
PRAGMA empty_result_callbacks = 0 | 1;
empty-result-callbacks フラグを問い合わせあるいは変更します。
empty-result-callbacks フラグは、sqlite3_exec API のみに影響します。 通常、empty-result-callbacks フラグがクリアされている場合、データ行を一行も返さない コマンドに対しては、sqlite3_exec() に与えたコールバック関数が呼び出されません。 同様の状況において empty-result-callbacks がセットされている場合、三番目のパラメーターを 0（NULL）にセットして正確に一度だけコールバック関数が呼び出されます。 これは、データーを返さない問い合わせにおいてもカラム名を取り出すために sqlite3_exec() API を使うことができるようにします。
PRAGMA encoding;
PRAGMA encoding = "UTF-8";
PRAGMA encoding = "UTF-16";
PRAGMA encoding = "UTF-16le";
PRAGMA encoding = "UTF-16be";
最初の形式は、メインデータベースが作成済みの場合、"UTF-8"、"UTF-16le"、 （リトルエンディアン UTF-16 エンコーディング）、"UTF-16be"、 （ビッグエンディアン UTF-16 エンコーディング）のうち一つをメインデータベースが使用中の テキストエンコーディングとして返します。 メインデータベースが作成されていない場合、返される値はこのセッションで メインデータベースが作成される時に使われる予定のテキストエンコーディングです。
このプラグマの二番目以降の形式は、メインデータベースがまだ作成されていない場合のみ 有効です。 この場合、このセッションでメインデータベースが作成される時に使用するエンコーディングを 設定します。 文字列 "UTF-16" は、"マシンネイティブのバイトオーダーによる UTF-16 エンコーディング" と 解釈されます。 データベースファイルの作成後に二番目以降の形式が使われた場合、それらは効果を持たず 静かに無視されます。
データベースに対して一度エンコーディングが設定されると、それは変更できません。
ATTACH コマンドによって作成されたデータベースは、メインデータベースと同じ エンコーディングを使用します。
PRAGMA full_column_names;
PRAGMA full_column_names = 0 | 1;
このフラグは、カラムのための式が table-column 名あるいはワイルドカード "*" の場合に、 SELECT ステートメントによって返されるデータのカラムに対して SQLite が命名する方法に 影響します。 通常、二つ以上のテーブルを結合した SELECT ステートメントの結果カラムは、 <table-name/alias><column-name> と命名され、 一つのテーブルに対して問い合わせる SELECT ステートメントの場合は、 単純に <column-name> と命名されます。 full-column-names フラグが設定されている場合このようなカラムは、結合が行われたかどうかに かかわらず常に、<table-name/alias><column-name> と命名されます。
short-column-names と full-column-names の両方が設定されている場合、 full-column-names フラグと結びつく動作を行います。
PRAGMA fullfsync
PRAGMA fullfsync = 0 | 1;
fullfsync を問い合わせあるいは変更します。 このフラグは、F_FULLFSYNC 同期メソッドをサポートするシステム上でそれを使用するかどうかの 決定に影響を与えます。 デフォルト値はオフです。 これを書いている時点（2006-02-10）で、Mac OS X のみが F_FULLFSYNC をサポートしています。
PRAGMA incremental_vacuum(N);
incremental_vacuum プラグマは、フリーリストから最大 N ページの削除を 引き起こします。 データベースファイルは同じ量切り詰められます。 incremental_vacuum プラグマは、 auto_vacuum==incremental モードでない場合あるいは フリーリスト上に一ページもない場合効果を持ちません。 フリーリスト上に N ページ以下存在する場合、すべてのフリーリストがクリアされます。
バージョン 3.4.0（incremental_vacuum をサポートした最初のバージョン）の時点で、この機能は 実験的です。 将来的には、本格的な VACUUM コマンドがするように 拡張 incremental_vacuum がデフラグとノードの再詰め込みを行うことが見込まれます。 そして、incremental_vacuum は、プラグマから個別の SQL コマンドへ、場合によっては VACUUM コマンドの変種まで進化するかもしれません。 それらは変更される可能性が高いため、プログラマーは現在の構文や機能性に夢中に ならないように注意してください。
PRAGMA legacy_file_format;
PRAGMA legacy_file_format = ON | OFF
このプラグマは、legacy_file_format を問い合わせあるいは変更します。 このフラグがオンの場合、新しい SQLite データベースは、3.0.0 まで遡って SQLite の すべてのバージョンで読み書きできるファイル形式で作成されます。 フラグがオフの場合、新しいデータベースは、SQLite の古いバージョンで読み書きできない 可能性がある最新のファイル形式を使って作成されます。
このフラグは、新たに作成されるデータベースにのみ影響を与えます。 既存のデータベースには影響を与えません。
PRAGMA locking_mode;
PRAGMA locking_mode = NORMAL | EXCLUSIVE
このプラグマは、データベース接続の locking-mode を設定あるいは問い合わせます。 locking-mode は、NORMAL または EXCLUSIVE のどちらかです。
NORMAL locking-mode（デフォルト）において、データベース接続は、それぞれの読み取りあるいは 書き込みトランザクションの完了でデータベースファイルをアンロックします。 locking-mode が EXCLUSIVE に設定されている場合、データベース接続は決してファイルロックを 解放しません。 EXCLUSIVE モードでデータベースを読み込む初回に共有ロックを得てそのまま保持します。 データベースへ書き込む初回に排他ロックを得てそのまま保持します。
EXCLUSIVE モードの接続で得たデータベースロックは、データベース接続を閉じるか、あるいは このプラグマを使って locking-mode を NORMAL に設定し直し （読み込みあるいは書き込みのために）データベースファイルをアクセスするか、どちらかの 場合に解放されます。 単に locking-mode を NORMAL に設定しても、次回データベースファイルにアクセスするまでは、 ロックが解放されないということです。
locking-mode を EXCLUSIVE に設定するのには二つの理由があります。 一つは、アプリケーションが実際に他のプロセスのデータベースファイルへのアクセスを 阻止したい場合です。 もう一つは、少数のファイルシステム操作が、このモードで有効化された最適化によって 保存されるということです。 これは組み込み環境で重要となるかもしれません。
特定のデータベースで locking_mode を指定する例です。
PRAGMA main.locking_mode=EXCLUSIVE;
locking_mode は名前付きデータベースにのみ適用されます。 データベース名修飾子が "locking_mode" キーワードに前置されない場合、以降の ATTACH コマンドによって追加されるすべての新しい データベースを含めてすべてのデータベースに対して locking_mode が適用されます。
（TEMP テーブルとインデックスが格納される）"temp" データベースは、常に排他ロックモード を使用します。 temp のロックモードは変更できません。 他のすべてのデータベースは、デフォルトで標準ロックモードを使い、このプラグマの影響を うけます。
PRAGMA page_size;
PRAGMA page_size = bytes;
データベースの page-size を設定あるいは問い合わせます。 page-size は、データベースの作成前のみ設定できます。 ページサイズは 512 またはそれ以上から 8192 またはそれ以下で 2 のべき乗でなければ なりません。 コンパイル時に SQLITE_MAX_PAGE_SIZE を設定しておくことで、上限を変更できます。 最大値は 32768 です。
PRAGMA max_page_count;
PRAGMA max_page_count = N;
データベースファイルの最大ページ数を設定あるいは問い合わせます。 プラグマの両形式が、最大ページ数を返します。 二番目の形式は、最大ページ数の変更を試みます。 最大ページ数は、現在のデータベースのサイズ以下に減少できません。
PRAGMA read_uncommitted;
PRAGMA read_uncommitted = 0 | 1;
READ UNCOMMITTED 隔離レベルを問い合わせ、設定、クリアします。 SQLite のデフォルト隔離レベルは、SERIALIZABLE です。 すべてのプロセスとスレッドは、READ UNCOMMITTED 隔離レベルを選択できますが、 それにもかかわらず、共通のページとスキーマキャッシュを共有する接続以外は SERIALIZABLE が 使われます。 キャッシュ共有は、 sqlite3_enable_shared_cache() API を使って有効化でき、同じスレッドで実行中の接続間でのみ利用可能です。 キャッシュ共有はデフォルトでオフです。
PRAGMA short_column_names;
PRAGMA short_column_names = 0 | 1;
short-column-names を問い合わせあるいは変更します。 このフラグは、カラムのための式が table-column 名あるいはワイルドカード "*" の場合に、 SELECT ステートメントによって返されるデータのカラムに対して SQLite が命名する方法に 影響します。 通常、二つ以上のテーブルを結合した SELECT ステートメントの結果カラムは、 <table-name/alias><column-name> と命名され、一つのテーブルに対して 問い合わせる SELECT ステートメントの場合は、単純に <column-name> と命名されます。 full-column-names フラグが設定されている場合このようなカラムは、結合が行われたかどうかに かかわらず常に、<table-name/alias><column-name> と命名されます。
short-column-names と full-column-names の両方が設定されている場合、 full-column-names フラグと結びつく動作を行います。
PRAGMA synchronous;
PRAGMA synchronous = FULL; (2)
PRAGMA synchronous = NORMAL; (1)
PRAGMA synchronous = OFF; (0)
Query or change the setting of the "synchronous" flag. The first (query) form will return the setting as an integer. When synchronous is FULL (2), the SQLite database engine will pause at critical moments to make sure that data has actually been written to the disk surface before continuing. This ensures that if the operating system crashes or if there is a power failure, the database will be uncorrupted after rebooting. FULL synchronous is very safe, but it is also slow. When synchronous is NORMAL, the SQLite database engine will still pause at the most critical moments, but less often than in FULL mode. There is a very small (though non-zero) chance that a power failure at just the wrong time could corrupt the database in NORMAL mode. But in practice, you are more likely to suffer a catastrophic disk failure or some other unrecoverable hardware fault. With synchronous OFF (0), SQLite continues without pausing as soon as it has handed data off to the operating system. If the application running SQLite crashes, the data will be safe, but the database might become corrupted if the operating system crashes or the computer loses power before that data has been written to the disk surface. On the other hand, some operations are as much as 50 or more times faster with synchronous OFF.
In SQLite version 2, the default value is NORMAL. For version 3, the default was changed to FULL.
PRAGMA temp_store;
PRAGMA temp_store = DEFAULT; (0)
PRAGMA temp_store = FILE; (1)
PRAGMA temp_store = MEMORY; (2)
Query or change the setting of the "temp_store" parameter. When temp_store is DEFAULT (0), the compile-time C preprocessor macro TEMP_STORE is used to determine where temporary tables and indices are stored. When temp_store is MEMORY (2) temporary tables and indices are kept in memory. When temp_store is FILE (1) temporary tables and indices are stored in a file. The temp_store_directory pragma can be used to specify the directory containing this file. FILE is specified. When the temp_store setting is changed, all existing temporary tables, indices, triggers, and views are immediately deleted.
It is possible for the library compile-time C preprocessor symbol TEMP_STORE to override this pragma setting. The following table summarizes the interaction of the TEMP_STORE preprocessor macro and the temp_store pragma:
TEMP_STORE PRAGMA
temp_storeStorage used for
TEMP tables and indices0 any file 1 0 file 1 1 file 1 2 memory 2 0 memory 2 1 file 2 2 memory 3 any memory
PRAGMA temp_store_directory;
PRAGMA temp_store_directory = 'directory-name';
Query or change the setting of the "temp_store_directory" - the directory where files used for storing temporary tables and indices are kept. This setting lasts for the duration of the current connection only and resets to its default value for each new connection opened.
When the temp_store_directory setting is changed, all existing temporary tables, indices, triggers, and viewers are immediately deleted. In practice, temp_store_directory should be set immediately after the database is opened.
The value directory-name should be enclosed in single quotes. To revert the directory to the default, set the directory-name to an empty string, e.g., PRAGMA temp_store_directory = ''. An error is raised if directory-name is not found or is not writable.
The default directory for temporary files depends on the OS. For Unix/Linux/OSX, the default is the is the first writable directory found in the list of: /var/tmp, /usr/tmp, /tmp, and current-directory. For Windows NT, the default directory is determined by Windows, generally C:\Documents and Settings\user-name\Local Settings\Temp\. Temporary files created by SQLite are unlinked immediately after opening, so that the operating system can automatically delete the files when the SQLite process exits. Thus, temporary files are not normally visible through ls or dir commands.
PRAGMA database_list;
For each open database, invoke the callback function once with information about that database. Arguments include the index and the name the database was attached with. The first row will be for the main database. The second row will be for the database used to store temporary tables.
PRAGMA foreign_key_list(table-name);
For each foreign key that references a column in the argument table, invoke the callback function with information about that foreign key. The callback function will be invoked once for each column in each foreign key.
PRAGMA [database].freelist_count;
Return the number of unused pages in the database file. Running a "PRAGMA incremental_vaccum(N);" command with a large value of N will shrink the database file by this number of pages.
PRAGMA index_info(index-name);
For each column that the named index references, invoke the callback function once with information about that column, including the column name, and the column number.
PRAGMA index_list(table-name);
For each index on the named table, invoke the callback function once with information about that index. Arguments include the index name and a flag to indicate whether or not the index must be unique.
PRAGMA table_info(table-name);
For each column in the named table, invoke the callback function once with information about that column, including the column name, data type, whether or not the column can be NULL, and the default value for the column.
PRAGMA [database.]schema_version;
PRAGMA [database.]schema_version = integer ;
PRAGMA [database.]user_version;
PRAGMA [database.]user_version = integer ;
The pragmas schema_version and user_version are used to set or get the value of the schema-version and user-version, respectively. Both the schema-version and the user-version are 32-bit signed integers stored in the database header.
The schema-version is usually only manipulated internally by SQLite. It is incremented by SQLite whenever the database schema is modified (by creating or dropping a table or index). The schema version is used by SQLite each time a query is executed to ensure that the internal cache of the schema used when compiling the SQL query matches the schema of the database against which the compiled query is actually executed. Subverting this mechanism by using "PRAGMA schema_version" to modify the schema-version is potentially dangerous and may lead to program crashes or database corruption. Use with caution!
The user-version is not used internally by SQLite. It may be used by applications for any purpose.
PRAGMA integrity_check;
PRAGMA integrity_check(integer)
The command does an integrity check of the entire database. It looks for out-of-order records, missing pages, malformed records, and corrupt indices. If any problems are found, then strings are returned (as multiple rows with a single column per row) which describe the problems. At most integer errors will be reported before the analysis quits. The default value for integer is 100. If no errors are found, a single row with the value "ok" is returned.
PRAGMA parser_trace = ON; (1)
PRAGMA parser_trace = OFF; (0)
Turn tracing of the SQL parser inside of the SQLite library on and off. This is used for debugging. This only works if the library is compiled without the NDEBUG macro.
PRAGMA vdbe_trace = ON; (1)
PRAGMA vdbe_trace = OFF; (0)
Turn tracing of the virtual database engine inside of the SQLite library on and off. This is used for debugging. See the VDBE documentation for more information.
PRAGMA vdbe_listing = ON; (1)
PRAGMA vdbe_listing = OFF; (0)
Turn listings of virtual machine programs on and off. With listing is on, the entire content of a program is printed just prior to beginning execution. This is like automatically executing an EXPLAIN prior to each statement. The statement executes normally after the listing is printed. This is used for debugging. See the VDBE documentation for more information.