SQLite的PRAGMA 声明（二十三）

返回：SQLite—系列文章目录   

上一篇：SQLite从出生到现在（发布历史记录）（二十二）

下一篇：用于 SQLite 的异步 I/O 模块（二十四）

PRAGMA 语句是特定于 SQLite 的 SQL 扩展，用于 修改 SQLite 库的操作或查询 SQLite 库 内部（非表）数据。PRAGMA声明使用相同的 接口作为其他 SQLite 命令（例如 SELECT、INSERT）但 在以下重要方面有所不同：

• pragma 命令特定于 SQLite，并且是 与任何其他 SQL 数据库引擎不兼容。
• 将来可能会删除特定的 pragma 语句并添加其他语句 SQLite的版本。不能保证向后兼容性。
• 如果发出未知的编译指示，则不会生成任何错误消息。 未知的编译指示被简单地忽略。这意味着如果 Pragma 语句 库不会通知用户这一事实。
• 某些编译指示在 SQL 编译阶段生效，而不是 执行阶段。这意味着如果使用 C 语言 sqlite3_prepare（）、sqlite3_step（）、sqlite3_finalize（） API（或包装器中的类似 API） 接口），编译指示可以在 sqlite3_prepare（） 调用期间运行， 而不是像普通 SQL 语句那样在 sqlite3_step（） 调用期间。 或者，编译指示可能会像往常一样在 sqlite3_step（） 期间运行 SQL 语句。编译指示是否在 sqlite3_prepare（） 期间运行 或 sqlite3_step（） 取决于编译指示和特定版本 的 SQLite。
• SQL 语句的 EXPLAIN 和 EXPLAIN QUERY PLAN 前缀 仅影响语句在 sqlite3_step（） 期间的行为。 这意味着在 sqlite3_prepare（） 期间生效的 PRAGMA 语句的行为方式相同，无论 不是它们以“解释”开头。

用于 SQLite 的 C 语言 API 提供了 SQLITE_FCNTL_PRAGMA 文件控件，该控件为 VFS 实现提供了 有机会添加新的 PRAGMA 语句或覆盖 内置 PRAGMA 语句。

---

PRAGMA 命令语法

pragma-stmt： 隐藏

普拉格玛架构名称.pragma-name(pragma-value)=pragma-value

pragma-value： 隐藏

签名号码名字有符号文字

签名号码： 显示

编译指示可以采用零个参数，也可以采用一个参数。参数可能是 在括号中，也可以用等号将其与 pragma 名称分开。 这两种语法产生相同的结果。 在许多编译指示中，参数是布尔值。布尔值可以是以下项之一：

1 是 真 开
0 否 假 关

关键字参数可以选择出现在引号中。 （例如：“yes” [FALSE]。一些编译指示 将字符串文本作为其参数。当 pragma 采用关键字时 参数，它通常也需要一个数字等价物。 例如，“0”和“否”的意思相同，“1”和“是”也是如此。 查询设置的值时，许多编译指示返回数字 而不是关键字。

杂注在杂注名称之前可能有一个可选的架构名称。 schema-name 是 ATTACH-ed 数据库的名称 或 main 和 TEMP 数据库的 “main” 或 “temp”。如果可选 省略架构名称，假定为“main”。在某些编译指示中，架构 名称毫无意义，只是被忽略。在下面的文档中， 架构名称有意义的编译指示显示 “模式。”前缀。

---

PRAGMA函数

返回结果且无副作用的 PRAGMA 可以是 作为表值函数从普通 SELECT 语句访问。 对于每个参与的 PRAGMA，相应的表值函数 与PRAGMA同名，前缀为7个字符的“pragma_”。 PRAGMA 参数和架构（如果有）将作为参数传递给 table-value 函数，架构作为可选的最后一个参数。

例如，有关索引中列的信息可以是 使用index_info编译指示读取，如下所示：

PRAGMA index_info('idx52');

或者，可以使用以下方法读取相同的内容：

SELECT * FROM pragma_index_info('idx52');

表值函数格式的优点是查询 可以只返回 PRAGMA 列的子集，可以包含 WHERE 子句， 可以使用聚合函数，表值函数可以只是 联接中的多个数据源之一。 例如，若要获取架构中所有索引列的列表，一个 可以查询：

SELECT DISTINCT m.name || '.' || ii.name AS 'indexed-columns'
  FROM sqlite_schema AS m,
       pragma_index_list(m.name) AS il,
       pragma_index_info(il.name) AS ii
 WHERE m.type='table'
 ORDER BY 1;

附注事项：

• 表值函数仅适用于内置 PRAGMA，而不适用于 PRAGMA 使用 SQLITE_FCNTL_PRAGMA 文件控件定义。

• 表值函数仅适用于返回结果和 没有副作用。

• 此功能可用于实现信息架构，方法是首先使用

  ATTACH ':memory:' AS 'information_schema';
  

  然后在该架构中创建实现官方信息架构的 VIEW 使用表值 PRAGMA 函数的表。

• 添加了 PRAGMA 功能的表值函数 在 SQLite 版本 3.16.0 （2017-01-02） 中。SQLite 的早期版本 无法使用此功能。

---

PRAGMA列表

• analysis_limit
• application_id
• auto_vacuum
• automatic_index
• busy_timeout
• cache_size
• cache_spill
• case_sensitive_like¹
• cell_size_check
• checkpoint_fullfsync
• collation_list
• compile_options
• count_changes¹
• data_store_directory¹
• data_version
• database_list
• default_cache_size¹
• defer_foreign_keys
• empty_result_callbacks¹
• 编码
• foreign_key_check
• foreign_key_list
• foreign_keys
• freelist_count
• full_column_names¹
• fullfsync
• function_list
• hard_heap_limit
• ignore_check_constraints
• incremental_vacuum
• index_info
• index_list
• index_xinfo
• integrity_check
• journal_mode
• journal_size_limit
• legacy_alter_table
• legacy_file_format
• locking_mode
• max_page_count
• mmap_size
• module_list
• 优化
• page_count
• page_size
• parser_trace²
• pragma_list
• query_only
• quick_check
• read_uncommitted
• recursive_triggers
• reverse_unordered_selects
• schema_version³
• secure_delete
• short_column_names¹
• shrink_memory
• soft_heap_limit
• 统计³
• 同步
• table_info
• table_list
• table_xinfo
• temp_store
• temp_store_directory¹
• 线程
• trusted_schema
• user_version
• vdbe_addoptrace²
• vdbe_debug²
• vdbe_listing²
• vdbe_trace²
• wal_autocheckpoint
• wal_checkpoint
• writable_schema³

笔记：

1. 名称被划掉的 Pragma 将被弃用。不要使用它们。它们存在 为了历史兼容性。
2. 这些编译指示仅在使用非标准的构建中可用 编译时选项。
3. 这些编译指示用于测试 SQLite，不推荐使用 用于应用程序。

普拉格玛analysis_limit;
PRAGMA analysis_limit = N;

查询或更改近似 ANALYZE 设置的限制。 这是 通过 ANALYZE 命令在每个索引中检查的行。 如果省略参数 N，则分析极限 保持不变。 如果限制为零，则禁用分析限制，并禁用 ANALYZE 命令将检查每个索引的所有行。 如果 N 大于零，则分析限设置为 N 后续的 ANALYZE 命令将停止分析 每个索引在检查了大约 N 行之后。 如果 N 是负数或整数值以外的值， 然后编译指示的行为就像省略了 N 参数一样。 在所有情况下，返回的值都是使用的新分析限值 用于后续的 ANALYZE 命令。

此编译指示可用于帮助 ANALYZE 命令更快地运行 在大型数据库上。分析结果不那么好 当只检查每个索引的一部分，但结果是 通常足够好。将 N 设置为 100 或 1000 允许 ANALYZE 命令运行速度非常快，即使在数 GB 上也是如此 数据库文件。这种编译指示在组合时特别有用 使用 PRAGMA 优化。

本编译指示已在 SQLite 版本 3.32.0 （2020-05-22） 中添加。 当前实现仅使用 N 值 - 高阶位被静默忽略。未来版本 的 SQLite 可能会开始使用高阶位。

PRAGMA 架构。application_id;
PRAGMA 架构。application_id = 整数 ;

application_id PRAGMA 用于查询或设置 32 位 位于偏移量处的有符号 big-endian “应用程序 ID” 整数 68 进入数据库头。使用 SQLite 作为其应用程序文件格式的应用程序应将应用程序 ID 整数设置为 一个唯一的整数，以便 file（1） 等实用程序可以确定特定的 文件类型，而不仅仅是报告“SQLite3 数据库”。列表 通过查阅 SQLite 源存储库中的 magic.txt 文件，可以查看分配的应用程序 ID。

另请参阅user_version编译指示。

PRAGMA 架构。auto_vacuum;
PRAGMA 架构。auto_vacuum = 0 |无 |1 |完整 |2 |增量;

查询或设置数据库中的自动抽真空状态。

自动吸尘的默认设置为 0 或“无”， 除非使用 SQLITE_DEFAULT_AUTOVACUUM 编译时选项。 “无”设置表示自动吸尘被禁用。 当禁用自动清空功能并从数据库中删除数据时， 数据库文件的大小保持不变。未使用的数据库文件 页面被添加到“自由列表”中，并重新用于后续插入。所以 不会丢失任何数据库文件空间。但是，数据库文件不会 收缩。在此模式下，可以使用 VACUUM 命令重建整个数据库文件，并 从而回收未使用的磁盘空间。

当自动清空模式为 1 或“已满”时，自由列表页面为 移动到数据库文件的末尾，数据库文件被截断 在每次交易提交时删除自由列表页面。 但请注意，自动清空只会截断自由列表页面 从文件。自动清空不会对数据库进行碎片整理，也不会对数据库进行碎片整理。 以 VACUUM 命令的方式重新打包单个数据库页。事实上，因为 它在文件中移动页面，自动真空实际上可以 使碎片化变得更糟。

只有当数据库存储了一些 允许每个数据库页的附加信息 向后追溯到其引用。因此，自动吸尘必须 在创建任何表之前打开。这是不可能的 在创建表后启用或禁用自动清空。

当自动真空的值为 2 或“增量”时，则额外的 执行自动清空所需的信息存储在数据库文件中 但是自动清空不会在每次提交时自动发生，因为它 与 auto_vacuum=full 一起执行。在增量模式下，单独的incremental_vacuum编译指示必须 被调用以导致自动真空发生。

数据库连接可以在完全连接和增量连接之间切换 自动真空模式。但是，从 “none”到“full”或“incremental”只有在数据库出现时才会出现 是新的（无表 尚未创建）或运行 VACUUM 命令。自 更改自动吸尘模式，首先使用auto_vacuum编