小巧，快速，可靠。
任选三项。

SQLite 库的 Tcl 接口

SQLite 库的设计初衷是易于从 Tcl 或 Tcl/Tk 脚本中使用。SQLite 最初是作为 Tcl 扩展 开发的，并且 SQLite 的主要 测试套件 是用 TCL 编写的。SQLite 可以与任何编程语言一起使用，但它与 TCL 的关系非常深厚。

本文档概述了 SQLite 的 Tcl 编程接口。

API

SQLite 库的接口由单个名为 sqlite3 的 Tcl 命令组成。由于只有一个命令，因此接口没有放在单独的命名空间中。

sqlite3 命令主要用于以下方式打开或创建数据库

sqlite3  dbcmd  ?database-name?  ?options?

为了仅获取信息，sqlite3 命令可以接受一个参数，可以是 "-version"，"-sourceid" 或 "-has-codec"，它将返回指定的数据，没有其他效果。

使用其他参数，sqlite3 命令将打开第二个非选项参数中指定的数据库，如果没有这样的数据库，则指定 ""。如果打开成功，将创建名为第一个参数的新的 Tcl 命令，并返回 ""。（这种方法类似于在 Tk 中创建小部件的方式。）如果打开失败，将引发错误，不会创建 Tcl 命令，并返回错误消息字符串。

如果数据库不存在，则默认行为是自动创建它（尽管可以使用 "-create false" 选项来更改此行为）。

数据库的名称通常只是存储数据库的磁盘文件的名称。如果数据库的名称是特殊名称 ":memory:"，则将在内存中创建一个新的数据库。如果数据库的名称为空字符串，则将在一个空文件中创建数据库，该文件将在数据库连接关闭时自动删除。URI 文件名 可以用于在 sqlite3 命令上提供 "-uri yes" 选项时。

sqlite3 命令理解的选项包括

-create BOOLEAN

如果为 true，则如果数据库不存在，则创建一个新的数据库。如果为 false，则尝试打开之前不存在的数据库文件将引发错误。默认行为是 "true"。

-nomutex BOOLEAN

如果为 true，则禁用数据库连接的所有互斥锁。这将在单线程应用程序中提供少量性能提升。

-readonly BOOLEAN

如果为 true，则以只读方式打开数据库文件。如果为 false，则如果文件系统权限允许，则以读写方式打开数据库，或者如果文件系统写权限被操作系统拒绝，则以只读方式打开。默认设置为 "false"。请注意，如果之前拥有数据库的进程没有干净地退出，并在后面留下了 热日志，则需要写权限才能在打开后恢复数据库，并且无法以只读方式打开数据库。

-uri BOOLEAN

如果为 true，则将文件名参数解释为 URI 文件名。如果为 false，则该参数是文字文件名。默认值为 "false"。

-vfs VFSNAME

使用参数指定的替代 VFS。

-fullmutex BOOLEAN

如果为 true，则多个线程可以安全地尝试使用数据库。如果为 false，则此类尝试不安全。默认值取决于扩展的构建方式。

-nofollow BOOLEAN

如果为 true，并且数据库名称是指向符号链接，则不会跟随它以打开真实的数据库文件。如果为 false，则会跟随符号链接。默认值为 "false"。

打开 SQLite 数据库后，可以使用 dbcmd 的方法来控制它。目前定义了 40 种方法。

每个方法的使用将在后续部分解释，但顺序与以上显示的顺序不同。

"eval" 方法

最有用的 dbcmd 方法是 "eval"。eval 方法用于在数据库上执行 SQL。eval 方法的语法如下所示

dbcmd  eval  ?-withoutnulls?  sql   ?array-name?  ?script?

eval 方法的职责是执行第二个参数中给出的 SQL 语句或语句。例如，要在数据库中创建一个新表，您可以这样做

sqlite3 db1 ./testdb
db1 eval {CREATE TABLE t1(a int, b text)}

上面的代码创建了一个名为 t1 的新表，它有 a 和 b 两列。还能有什么比这更简单呢？

查询结果作为列值列表返回。如果查询请求 2 列，并且有 3 行匹配该查询，则返回的列表将包含 6 个元素。例如

db1 eval {INSERT INTO t1 VALUES(1,'hello')}
db1 eval {INSERT INTO t1 VALUES(2,'goodbye')}
db1 eval {INSERT INTO t1 VALUES(3,'howdy!')}
set x [db1 eval {SELECT * FROM t1 ORDER BY a}]

上面的代码将变量 $x 设置为

1 hello 2 goodbye 3 howdy!

您还可以通过指定一个数组变量的名称和一个紧随 SQL 代码的脚本，逐行处理查询结果。对于查询结果的每一行，所有列的值都将插入到数组变量中，并且将执行脚本。例如

db1 eval {SELECT * FROM t1 ORDER BY a} values {
    parray values
    puts ""
}

最后这段代码将给出以下输出

values(*) = a b
values(a) = 1
values(b) = hello

values(*) = a b
values(a) = 2
values(b) = goodbye

values(*) = a b
values(a) = 3
values(b) = howdy!

对于结果中每一行中的每一列，该列的名称将用作数组中的索引，并且该列的值将存储在相应的数组条目中。（注意：如果结果集中有两列或更多列具有相同的名称，则具有该名称的最后一列将覆盖先前的值，并且具有相同名称的早期列将无法访问。）特殊数组索引 * 用于存储列名称列表，顺序为它们出现的顺序。

通常，NULL SQL 结果使用 nullvalue 设置存储在数组中。但是，如果使用 -withoutnulls 选项，则 NULL SQL 值会导致相应的数组元素被 unset 而不是。

如果数组变量名被省略或为空字符串，则每一列的值将存储在一个与该列名称相同的变量中。例如

db1 eval {SELECT * FROM t1 ORDER BY a} {
    puts "a=$a b=$b"
}

由此，我们得到以下输出

a=1 b=hello
a=2 b=goodbye
a=3 b=howdy!

Tcl 变量名可以出现在第二个参数的 SQL 语句中的任何位置，只要该位置是放置字符串或数字文字的合法位置。变量的值将替换变量名。如果变量不存在，则使用 NULL 值。例如

db1 eval {INSERT INTO t1 VALUES(5,$bigstring)}

请注意，无需引用 $bigstring 值。这将自动发生。如果 $bigstring 是一个大型字符串或二进制对象，则这种技术不仅更容易编写，而且效率也更高，因为它避免了对 $bigstring 内容进行复制。

如果 $bigstring 变量同时具有字符串和 "bytearray" 表示，则 TCL 将该值插入为字符串。如果它只有 "bytearray" 表示，则该值将插入为 BLOB。要强制将值插入为 BLOB，即使它也具有文本表示，请使用 "@" 字符代替 "$"。像这样

db1 eval {INSERT INTO t1 VALUES(5,@bigstring)}

如果变量没有 bytearray 表示，则 "@" 的作用与 "$" 相同。请注意，":" 在所有情况下都与 "$" 相同，因此以下是一种表示相同语句的另一种方法

db1 eval {INSERT INTO t1 VALUES(5,:bigstring)}

在变量名之前使用 ":" 而不是 "$" 有时可能有用，如果 SQL 文本包含在双引号 "..." 中而不是花括号 {...} 中。当 SQL 包含在双引号 "..." 中时，TCL 将执行 $-变量的替换，如果不小心使用，会导致 SQL 注入。但是，无论使用双引号 "..." 还是花括号 {...} 来包含 SQL，TCL 都不会替换 :-变量，因此使用 :-变量增加了额外的防御措施，防止 SQL 注入。

"close" 方法

顾名思义，SQLite 数据库的 "close" 方法只是关闭数据库。这将导致删除 dbcmd Tcl 命令。以下是一个打开然后立即关闭数据库的示例

sqlite3 db1 ./testdb
db1 close

如果您直接删除 dbcmd，则它将与调用 "close" 方法具有相同的效果。因此，以下代码等效于前面的代码

sqlite3 db1 ./testdb
rename db1 {}

"transaction" 方法

"transaction" 方法用于在 SQLite 数据库事务中执行 TCL 脚本。事务在脚本完成时提交，或者如果脚本失败则回滚。如果事务发生在另一个事务中（即使是使用 BEGIN 手动启动的事务），则它将是无操作。

transaction 命令可用于安全地将多个 SQLite 命令组合在一起。当然，您始终可以使用 BEGIN 手动启动事务。但是，如果发生错误，导致 COMMIT 或 ROLLBACK 永远不会运行，则数据库将无限期地保持锁定状态。此外，BEGIN 不会嵌套，因此您必须确保在启动新事务之前没有其他事务处于活动状态。"transaction" 方法会自动处理所有这些细节。

语法如下所示

dbcmd  transaction  ?transaction-type?   script

transaction-type 可以是 deferred，exclusive 或 immediate 之一。默认值为 deferred。

"cache" 方法

上面 介绍的 "eval" 方法会保留最近评估的 SQL 命令的 准备好的语句 缓存。"cache" 方法用于控制此缓存。此命令的第一种形式为

dbcmd  cache size  N

此命令设置可以缓存的最大语句数量。上限为 100。默认值为 10。如果将缓存大小设置为 0，则不会进行缓存。

该命令的第二种形式是：

dbcmd  cache flush

cache-flush 方法将当前缓存中所有准备好的语句完成。

“complete” 方法

“complete” 方法接受一个假定的 SQL 字符串作为其唯一的参数。如果字符串是完整的 SQL 语句，则返回 TRUE；如果还有更多内容要输入，则返回 FALSE。

在构建交互式应用程序时，“complete” 方法很有用，因为它可以知道用户何时完成了输入 SQL 代码行。这实际上只是对 sqlite3_complete() C 函数的接口。

“config” 方法

“config” 方法使用 sqlite3_db_config() 接口查询或更改数据库连接的某些配置设置。运行此方法而不带任何参数将获得可用配置设置及其当前值的 TCL 列表。

dbcmd  config

以上将返回类似以下内容：

defensive 0 dqs_ddl 1 dqs_dml 1 enable_fkey 0 enable_qpsg 0 enable_trigger 1 enable_view 1 fts3_tokenizer 1 legacy_alter_table 0 legacy_file_format 0 load_extension 0 no_ckpt_on_close 0 reset_database 0 trigger_eqp 0 trusted_schema 1 writable_schema 0

添加单个配置设置的名称以查询该设置的当前值。可选择添加布尔值以更改设置。

以下四个配置更改建议用于最大限度地提高应用程序安全性。关闭 trust_schema 设置可以防止在触发器、视图、CHECK 约束、生成列和表达式索引中使用虚拟表和可疑的 SQL 函数。关闭 dqs_dml 和 dqs_ddl 设置可以防止使用双引号字符串。启用 defensive 可以防止对影子表进行直接写入。

db config trusted_schema 0
db config defensive 1
db config dqs_dml 0
db config dqs_ddl 0

“copy” 方法

“copy” 方法将数据从文件复制到表中。它返回从文件中成功处理的行数。copy 方法的语法如下所示：

dbcmd  copy  冲突算法   表名   文件名      ?列分隔符?   ?空值指示符?

冲突算法必须是 INSERT 语句的 SQLite 冲突算法之一：rollback、abort、fail、ignore 或 replace。有关更多信息，请参见 SQLite 语言部分中的 ON CONFLICT。冲突算法必须以小写形式指定。

表名必须已经作为表存在。文件名必须存在，并且每一行都必须包含与表中定义的相同数量的列。如果文件中的某一行包含的列数多于或少于定义的列数，则 copy 方法将回滚所有插入操作并返回错误。

列分隔符是一个可选的列分隔符字符串。默认值为 ASCII 制表符 \t。

空值指示符是一个可选字符串，表示列值为 NULL。默认值为一个空字符串。请注意，列分隔符和空值指示符是可选的位置参数；如果指定了空值指示符，则必须指定列分隔符参数并在空值指示符参数之前。

copy 方法实现了类似于 .import SQLite shell 命令的功能。

“timeout” 方法

“timeout” 方法用于控制 SQLite 库在放弃数据库事务之前等待锁释放的最长时间。默认超时时间为 0 毫秒。（换句话说，默认行为是不等待。）

SQLite 数据库允许多个并发读取者或单个写入者，但不能同时存在两者。如果任何进程正在写入数据库，则不允许其他进程读取或写入。如果任何进程正在读取数据库，则允许其他进程读取，但不允许写入。整个数据库共享一个锁。

当 SQLite 尝试打开数据库并发现它被锁定时，它可以选择延迟一小段时间并尝试再次打开文件。此过程会重复进行，直到查询超时，SQLite 返回失败。超时时间是可调整的。默认情况下它设置为 0，因此如果数据库被锁定，SQL 语句将立即失败。但是，您可以使用“timeout” 方法将超时值更改为正数。例如

db1 timeout 2000

“timeout” 方法的参数是等待锁释放的最大毫秒数。因此，在上面的示例中，最大延迟将为 2 秒。

“busy” 方法

“busy” 方法与“timeout” 一样，仅在数据库被锁定时才会起作用。但是，“busy” 方法让程序员能够更详细地控制要采取的操作。“busy” 方法指定一个回调 TCL 过程，该过程在 SQLite 尝试打开锁定的数据库时被调用。在调用之前，会向回调追加一个整型参数。该参数是当前锁定事件之前调用 busy 回调的次数。目的是让回调在一段时间内执行一些其他有用的工作（例如，服务 GUI 事件），然后返回，以便可以再次尝试获取锁。如果回调过程希望 SQLite 再次尝试打开数据库，则应返回“0”；如果希望 SQLite 放弃当前操作，则应返回“1”。

如果调用 busy 方法而不带参数，则将返回上次由 busy 方法设置的回调过程的名称。如果尚未设置回调过程，则将返回空字符串。

“enable_load_extension” 方法

SQLite 的扩展加载机制（使用 load_extension() SQL 函数访问）默认情况下处于关闭状态。这是一项安全预防措施。如果应用程序想要使用 load_extension() 函数，则必须首先使用此方法开启此功能。

此方法接受一个布尔参数，用于开启或关闭扩展加载功能。

为了获得最佳安全性，除非真正需要，否则不要使用此方法，并在调用此方法之前运行 PRAGMA trusted_schema=OFF 或 "db config trusted_schema 0" 方法。

此方法映射到 sqlite3_enable_load_extension() C/C++ 接口。

“exists” 方法

“exists” 方法类似于“onecolumn” 和“eval”，它执行 SQL 语句。不同之处在于“exists” 方法始终返回一个布尔值，如果它执行的 SQL 语句中的查询返回了一行或多行，则为 TRUE；如果 SQL 返回空集，则为 FALSE。

“exists” 方法通常用于测试表中是否存在行。例如

if {[db exists {SELECT 1 FROM table1 WHERE user=$user}]} {
   # 处理如果 $user 存在的情况
} else {
   # 处理如果 $user 不存在的情况
}

“last_insert_rowid” 方法

“last_insert_rowid” 方法返回一个整型值，表示最近插入的数据库行的 ROWID。

“function” 方法

“function” 方法使用 SQLite 引擎注册新的 SQL 函数。参数是新的 SQL 函数的名称以及实现该函数的 TCL 命令。函数参数在调用之前追加到 TCL 命令。

出于安全原因，建议应用程序首先设置 PRAGMA trusted_schema=OFF 或在使用此方法之前运行 "db config trusted_schema 0" 方法。

语法如下所示

dbcmd  function   sql-name   ?options?   script

以下示例创建了一个名为“hex” 的新 SQL 函数，该函数将数字参数转换为十六进制编码的字符串。

db function hex {format 0x%X}

“function” 方法接受以下选项：

-argcount INTEGER

指定 SQL 函数接受的参数数量。-1 的默认值表示接受任意数量的参数。

-deterministic

此选项表示该函数在给定相同的参数值时始终返回相同的结果。SQLite 查询优化器使用此信息来缓存使用常量输入的函数调用的结果，并重用结果，而不是重复调用函数。

-directonly

此选项限制函数只能由直接的顶级 SQL 语句使用。触发器、视图、CHECK 约束、生成列或索引表达式将无法访问该函数。建议对所有应用程序定义的 SQL 函数使用此选项，并且强烈建议对所有具有副作用或公开应用程序内部状态的 SQL 函数使用此选项。

安全警告：没有此开关，攻击者可能会更改数据库文件的模式以在触发器、视图或 CHECK 约束中包含新函数，从而欺骗应用程序使用攻击者选择的参数运行该函数。因此，如果新函数具有副作用或公开有关应用程序的内部状态，并且没有使用 -directonly 选项，则这可能是一个潜在的安全漏洞。

-innocuous

此选项表示该函数没有副作用，也不会泄漏任何无法直接从其输入参数计算得到的信息。当指定此选项时，即使设置了 PRAGMA trusted_schema=OFF，该函数也可以在触发器、视图、CHECK 约束、生成列和/或索引表达式中使用。除非真正需要，否则不鼓励使用此选项。

-returntype integer|real|text|blob|any

此选项用于配置函数返回的结果类型。如果此选项设置为“any”（默认值），则 SQLite 尝试根据 Tcl 值的内部类型确定函数实现返回的每个值的类型。或者，如果它设置为“text”或“blob”，则返回的值始终分别为文本或 blob 值。如果此选项设置为“integer”，则 SQLite 尝试将函数返回的值强制转换为整型值。如果无法在不丢失数据的情况下执行此操作，则会尝试将其强制转换为实型值，最后回退到文本值。如果此选项设置为“real”，则会尝试返回一个实型值，如果无法执行此操作，则回退到文本值。

“nullvalue” 方法

“nullvalue” 方法更改作为“eval” 方法结果返回的 NULL 的表示形式。

db1 nullvalue NULL

“nullvalue” 方法有助于区分 NULL 和空列值，因为 Tcl 缺乏 NULL 表示形式。NULL 值的默认表示形式为空字符串。

“onecolumn” 方法

“onecolumn” 方法类似于 eval，它评估作为参数给出的 SQL 查询语句。不同之处在于“onecolumn” 返回一个单元素，该元素是查询结果第一行的第一列。

这是一种便利方法。它可以让用户无需对“eval” 的结果执行“[lindex ... 0]”即可提取单个列结果。

“changes” 方法

“changes” 方法返回一个整型值，表示最近一次“eval” 方法在数据库中插入、删除和/或修改的行数。

“total_changes” 方法

“total_changes” 方法返回一个整型值，表示自当前数据库连接首次打开以来在数据库中插入、删除和/或修改的行数。

“authorizer” 方法

“authorizer” 方法提供对 sqlite3_set_authorizer C/C++ 接口的访问。authorizer 的参数是一个过程的名称，该过程在编译 SQL 语句时被调用，以授权某些操作。回调过程接受 5 个参数，描述要编码的操作。如果回调返回文本字符串“SQLITE_OK”，则允许该操作。如果它返回“SQLITE_IGNORE”，则操作将被静默禁用。如果返回值为“SQLITE_DENY”，则编译失败并出现错误。

如果参数为空字符串，则禁用授权器。如果省略参数，则返回当前授权器。

“bind_fallback” 方法

“bind_fallback” 方法使应用程序可以控制在没有 TCL 变量与参数名称匹配时如何处理参数绑定。

当 eval 方法 在 SQL 语句中看到一个命名的 SQL 参数（例如 "$abc" 或 ":def" 或 "@ghi"）时，它会尝试查找具有相同名称的 TCL 变量，并将该 TCL 变量的值绑定到 SQL 参数。如果不存在这样的 TCL 变量，则默认行为是将 SQL NULL 值绑定到参数。但是，如果指定了 bind_fallback proc，则该 proc 将使用 SQL 参数的名称调用，并且 proc 的返回值将绑定到 SQL 参数。或者，如果 proc 返回错误，则 SQL 语句将使用该错误中止。如果 proc 返回的代码不是 TCL_OK 或 TCL_ERROR，则 SQL 参数将绑定到 NULL，与默认情况一样。

“bind_fallback” 方法只有一个可选参数。如果参数为空字符串，则取消 bind_fallback 并恢复默认行为。如果参数是非空字符串，则该参数是一个 TCL 命令（通常是 proc 的名称），每当看到不匹配任何 TCL 变量的 SQL 参数时都会调用该命令。如果“bind_fallback” 方法没有给出任何参数，则返回当前的 bind_fallback 命令。

例如，以下设置会导致 TCL 在 SQL 语句包含不匹配任何全局 TCL 变量的参数时抛出错误


proc bind_error {nm} {
  error "no such variable: $nm"
}
db bind_fallback bind_error

“progress” 方法

此方法注册一个回调函数，该函数在查询处理期间定期调用。有两个参数：调用之间 SQLite 虚拟机操作码的数量，以及要调用的 TCL 命令。将进度回调设置为空字符串会将其禁用。

进度回调可用于显示冗长查询的状态或在冗长查询期间处理 GUI 事件。

“collate” 方法

此方法注册新的文本排序顺序。有两个参数：排序顺序的名称和实现排序顺序比较函数的 TCL 过程的名称。

例如，以下代码实现了一个名为“NOCASE”的排序顺序，该排序顺序不区分大小写地按文本顺序排序


proc nocase_compare {a b} {
  return [string compare [string tolower $a] [string tolower $b]]
}
db collate NOCASE nocase_compare

“collation_needed” 方法

此方法注册一个回调例程，当 SQLite 引擎需要特定排序顺序但没有注册该排序顺序时，该例程将被调用。回调可以注册排序顺序。回调使用单个参数调用，该参数是所需排序顺序的名称。

“commit_hook” 方法

此方法注册一个回调例程，该例程在 SQLite 尝试将更改提交到数据库之前调用。如果回调抛出异常或返回非零结果，则事务回滚而不是提交。

“rollback_hook” 方法

此方法注册一个回调例程，该例程在 SQLite 尝试执行回滚之前调用。脚本参数将不加更改地运行。

“status” 方法

此方法返回最近评估的 SQL 语句的状态信息。status 方法接受一个参数，该参数应该是“steps”或“sorts”。如果参数是“steps”，则该方法返回先前 SQL 语句评估的完整表扫描步骤的数量。如果参数是“sorts”，则该方法返回排序操作的数量。此信息可用于检测未使用索引来加速搜索或排序的查询。

status 方法基本上是对 sqlite3_stmt_status() C 语言接口的包装。

“update_hook” 方法

此方法注册一个回调例程，该例程在 UPDATE、INSERT 或 DELETE 语句修改每行之后调用。在调用回调之前，将附加四个参数

回调不能做任何会修改调用更新挂钩的数据库连接的事情，例如运行查询。

“preupdate” 方法

此方法可以注册一个在 UPDATE、INSERT 或 DELETE 语句修改每行之前调用，或执行与即将进行的更新相关的某些操作的回调例程。

要注册或删除 preupdate 回调，请使用以下语法

dbcmd  preupdate  hook  ?SCRIPT?
注册 preupdate 回调后，在每次修改行之前，将使用以下参数运行回调回调不能做任何会修改调用 preupdate 挂钩的数据库连接的事情，例如运行查询。

回调正在执行时，并且仅在此期间，可以使用指示的语法执行以下 preupdate 操作

dbcmd  preupdate  count
dbcmd  preupdate  depth
dbcmd  preupdate  new  INDEX
dbcmd  preupdate  old  INDEX

count 子方法返回正在插入、更新或删除的行中的列数。

depth 子方法返回更新嵌套深度。对于直接插入、更新或删除操作，这将为 0；对于顶级触发器调用的插入、更新或删除，这将为 1；对于由触发器调用触发器引起的更改，这将为更高的值。

old 和 new 子方法分别返回正在更新的行中选定的原始或更改的列值。

请注意，Tcl 接口（和底层 SQLite 库）必须在预处理符号 SQLITE_ENABLE_PREUPDATE_HOOK 定义的情况下构建，才能使用 preupdate 方法。

“wal_hook” 方法

此方法注册一个回调例程，该例程在事务提交后调用，此时数据库处于 WAL 模式。在调用回调命令之前，将向其附加两个参数

此方法可能决定自行或作为后续空闲回调运行 检查点。请注意，SQLite 仅允许一个 WAL 挂钩。默认情况下，此单个 WAL 挂钩用于自动检查点。如果您设置了显式 WAL 挂钩，则该单个 WAL 挂钩必须确保检查点正在发生，因为自动检查点机制将被禁用。

此方法应返回一个整数，该整数等效于 SQLite 错误代码（通常在成功的情况下为 0 表示 SQLITE_OK，在某些错误发生的情况下为 1 表示 SQLITE_ERROR）。与 sqlite3_wal_hook() 一样，返回不对应于 SQLite 错误代码的整数的结果是未定义的。如果脚本返回的值不能解释为整数，或者如果脚本抛出 Tcl 异常，则不会向 SQLite 返回错误，但会引发 Tcl 后台错误。

“incrblob” 方法

此方法打开一个 TCL 通道，该通道可用于读写数据库中已存在的 BLOB。语法如下

dbcmd  incrblob  ?-readonly?   ?DB?  TABLE  COLUMN  ROWID

该命令返回一个新的 TCL 通道，用于读写 BLOB。该通道使用底层的 sqlite3_blob_open() C 语言接口打开。使用 TCL 的 close 命令关闭通道。

“errorcode” 方法

此方法返回导致最近一次 SQLite 操作的数字错误代码。

“trace” 方法

“trace” 方法注册一个回调函数，该函数在编译每个 SQL 语句时调用。SQL 的文本将作为单个字符串附加到命令中，然后调用它。这可用于（例如）保留应用程序执行的所有 SQL 操作的日志。

“trace_v2” 方法

“trace_v2” 方法注册一个回调函数，该函数在编译每个 SQL 语句时调用。语法如下

dbcmd  trace_v2  ?callback?  ?mask?

此命令会导致在发生某些情况时调用“callback” 脚本。条件由 mask 参数确定，该参数应为 TCL 列表，其中包含以下关键字中的一个或多个

statement 的跟踪会在每次运行新 SQL 语句时使用两个参数调用回调。第一个参数是一个整数，表示指向底层 sqlite3_stmt 对象的指针的值。此整数可用于将 SQL 语句文本与 profile 或 row 回调的结果相关联。第二个参数是正在运行的 SQL 语句的未扩展文本。所谓“未扩展”，是指文本中的变量替换不会扩展为变量值。这与“trace” 方法的行为不同，后者会扩展变量替换。

profile 的跟踪会在每个 SQL 语句完成时使用两个参数调用回调。第一个参数是一个整数，表示指向底层 sqlite3_stmt 对象的指针的值。第二个参数是语句的近似运行时间（以纳秒为单位）。运行时间是根据应用程序运行平台的功能提供的最佳估计。

row 的跟踪会在每次从 SQL 语句获得新的结果行时使用单个参数调用回调。参数是一个整数，表示指向底层 sqlite3_stmt 对象指针的值。

close 的跟踪会在数据库连接关闭时使用单个参数调用回调。参数是一个整数，表示指向正在关闭的底层 sqlite3 对象的指针的值。

数据库连接上只能注册一个跟踪回调。每次使用“trace”或“trace_v2”都会取消所有先前的跟踪回调。

“backup” 方法

“backup” 方法会对实时数据库进行备份。命令语法如下

dbcmd  backup  ?source-database?  backup-filename

可选的 source-database 参数指定当前连接中要备份的数据库。默认值为 main（换句话说，就是主数据库文件）。要备份 TEMP 表，请使用 temp。要备份使用 ATTACH 命令添加到连接的辅助数据库，请使用在 ATTACH 命令中分配给该数据库的名称。

backup-filename 是备份写入到的文件的名称。Backup-filename 不必事先存在，但如果存在，则必须是格式良好的 SQLite 数据库。

"restore" 方法

"restore" 方法将内容从单独的数据库文件复制到当前数据库连接，覆盖任何预先存在的内容。命令语法如下

dbcmd  restore  ?target-database?  source-filename

可选的 target-database 参数指定当前连接中要覆盖新内容的数据库。默认值为 main（换句话说，就是主数据库文件）。要重新填充 TEMP 表，请使用 temp。要覆盖使用 ATTACH 命令添加到连接的辅助数据库，请使用在 ATTACH 命令中分配给该数据库的名称。

source-filename 是现有格式良好的 SQLite 数据库文件的名称，从中提取内容。

"serialize" 方法

"serialize" 方法创建一个 BLOB，它是底层数据库的完整副本。语法如下

dbcmd  serialize  ?database?

可选参数是 要序列化的模式或数据库的名称。默认值为“main”。

此例程返回一个 TCL 字节数组，它包含标识的数据库的完整内容。此字节数组可以写入文件，然后用作普通的 SQLite 数据库，也可以通过 TCP/IP 连接发送到其他应用程序，或者传递到另一个数据库连接的“deserialize”方法。

此方法仅在 SQLite 使用 -DSQLITE_ENABLE_DESERIALIZE 编译时才有效

"deserialize" 方法

"deserialize" 方法接受包含 SQLite 数据库文件的 TCL 字节数组，并将它添加到数据库连接中。语法如下

dbcmd  deserialize  ?database?  value

database 参数指定哪个附加的数据库应该接收反序列化。默认值为“main”。

此命令会导致 SQLite 断开与先前数据库的连接，并重新附加到内存中包含 value 内容的数据库。如果 value 不是包含定义良好的 SQLite 数据库的字节数组，则后续命令可能会返回 SQLITE_CORRUPT 错误。

此方法仅在 SQLite 使用 -DSQLITE_ENABLE_DESERIALIZE 编译时才有效

"interrupt" 方法

"interrupt" 方法调用 sqlite3_interrupt() 接口，导致任何待处理的查询停止。

"version" 方法

返回当前库版本。例如，“3.23.0”。

"profile" 方法

此方法用于分析应用程序运行的 SQL 语句的执行情况。语法如下

dbcmd  profile  ?script?

除非 script 是空字符串，否则此方法将安排在执行每个 SQL 语句后评估 script。在调用 script 之前，会将两个参数附加到 script：执行的 SQL 语句的文本和执行语句时经过的时间（以纳秒为单位）。

数据库句柄在任何时候只能注册一个配置文件脚本。如果在调用 profile 方法时已经注册了脚本，则以前注册的配置文件脚本将被新的脚本替换。如果 script 参数为空字符串，则任何以前注册的配置文件回调都会被取消，但不会注册新的配置文件脚本。

"unlock_notify" 方法

"unlock_notify" 方法用于出于测试目的访问 SQLite 核心库的 sqlite3_unlock_notify() 接口。不建议应用程序使用此方法。

此页面上次修改时间为 2023-03-25 03:02:51 UTC