小巧。快速。可靠。
任選三項。

Tcl 介面到 SQLite 函式庫

SQLite 函式庫設計為從 Tcl 或 Tcl/Tk 腳本中使用時非常容易。SQLite 最初為 Tcl 延伸模組，而 SQLite 的主要 測試套件 是用 TCL 編寫的。SQLite 可與任何程式語言搭配使用，但它與 TCL 的關聯非常深遠。

本文檔概述了 SQLite 的 Tcl 程式設計介面。

API

到 SQLite 函式庫的介面包含單一 Tcl 指令，稱為 sqlite3 由於只有一個指令，因此介面並未放置在個別的命名空間中。

sqlite3 指令大多用於開啟或建立資料庫，如下所示

sqlite3  dbcmd  ?database-name?  ?options?

若要僅取得資訊，可以給予 sqlite3 指令一個引數，為「-version」、「-sourceid」或「-has-codec」，它將傳回指定的資料，且不產生其他效應。

對於其他引數，sqlite3 指令會開啟在第二個非選項引數中指定名稱的資料庫，或在沒有此類名稱時指定為「」。如果開啟成功，會建立一個由第一個引數命名的 Tcl 指令，並傳回「」。(此方法類似於在 Tk 中建立小工具的方式。)如果開啟失敗，則會在未建立 Tcl 指令的情況下引發錯誤，並傳回錯誤訊息字串。

如果資料庫尚未存在，預設行為是自動建立資料庫（不過可以使用「-create false」選項變更此行為）。

資料庫名稱通常只是資料庫儲存其中的磁碟檔案名稱。如果資料庫名稱是特殊名稱「:memory:」，則會在記憶體中建立新的資料庫。如果資料庫名稱是空字串，則會在資料庫連線關閉時自動刪除的空檔案中建立資料庫。如果在 sqlite3 命令中提供「-uri yes」選項，可以使用 URI 檔案名稱。

sqlite3 命令了解的選項包括

-create 布林值

如果為 true，則會在資料庫尚未存在時建立新的資料庫。如果為 false，則會嘗試開啟先前不存在的資料庫檔案，並會產生錯誤。預設行為是「true」。

-nomutex 布林值

如果為 true，則會停用資料庫連線的所有互斥鎖。這會在單執行緒應用程式中提供一些效能提升。

-readonly 布林值

如果為 true，則以唯讀方式開啟資料庫檔案。如果為 false，則會在檔案系統權限允許的情況下，同時開啟資料庫進行讀取和寫入；如果作業系統拒絕檔案系統寫入權限，則只會開啟進行讀取。預設設定為「false」。請注意，如果先前擁有資料庫的程序並未正常結束，並留下 熱記錄檔，則在開啟後需要寫入權限才能復原資料庫，而且無法以唯讀方式開啟資料庫。

-uri 布林值

如果為 true，則會將檔案名稱引數詮釋為 URI 檔案名稱。如果為 false，則引數是文字檔案名稱。預設值為「false」。

-vfs VFSNAME

使用引數命名的替代 VFS。

-fullmutex 布林值

如果為 true，多個執行緒可以安全地嘗試使用資料庫。如果為 false，則此類嘗試不安全。預設值取決於如何建置擴充功能。

-nofollow 布林值

如果為 true，且資料庫名稱是指向符號連結，則不會追蹤它來開啟真正的資料庫檔案。如果為 false，則會追蹤符號連結。預設為「false」。

開啟 SQLite 資料庫後，可以使用 dbcmd 的方法來控制它。目前定義了 40 種方法。

每個方法的使用方式將在後續說明中解釋，但不會按照上述順序。

「eval」方法

最實用的 dbcmd 方法是「eval」。eval 方法用於在資料庫上執行 SQL。eval 方法的語法如下所示

dbcmd  eval  ?-withoutnulls?  sql   ?陣列名稱?  ?指令碼?

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 值會導致對應的陣列元素改為取消設定。

如果陣列變數名稱省略或為空字串，則每個欄位的數值會儲存在與欄位本身名稱相同的變數中。例如

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 變數同時有字串和「位元組陣列」表示法，TCL 會將值插入為字串。如果它只有「位元組陣列」表示法，則會將值插入為 BLOB。若要強制將值插入為 BLOB，即使它也有文字表示法，請使用「@」字元取代「$」。如下所示

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

如果變數沒有位元組陣列表示法，則「@」會像「$」一樣運作。請注意，在所有情況下「:」都像「$」一樣運作，因此下列是表達相同陳述式的另一種方式

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

如果 SQL 文字是用雙引號 "..." 而不是大括號 {...} 括起來，有時在變數名稱之前使用 ":" 而不是 "$" 會很有用。當 SQL 包含在雙引號 "..." 中時，TCL 會執行 $-變數的替換，如果沒有特別小心，可能會導致 SQL 注入。但是，無論是用雙引號 "..." 還是大括號 {...} 括住 SQL，TCL 都絕不會替換 :- 變數，因此使用 :- 變數可以增加對抗 SQL 注入的防禦措施。

「關閉」方法

顧名思義，「關閉」方法只會關閉 SQLite 資料庫。這會產生刪除 dbcmd Tcl 命令的副作用。以下是開啟然後立即關閉資料庫的範例

sqlite3 db1 ./testdb
db1 close

如果你直接刪除 dbcmd，效果會和呼叫「關閉」方法一樣。因此，下列程式碼等同於前一個

sqlite3 db1 ./testdb
rename db1 {}

「交易」方法

「交易」方法用於在 SQLite 資料庫交易中執行 TCL 程式碼。當程式碼完成時，交易會提交，如果程式碼失敗，則會回滾。如果交易發生在另一個交易中（即使是手動使用 BEGIN 開始的交易），則為無操作。

交易命令可以用於安全地將多個 SQLite 命令分組在一起。當然，你隨時都可以手動使用 BEGIN 開始交易。但是，如果發生錯誤，導致 COMMIT 或 ROLLBACK 永遠不會執行，則資料庫將會無限期地保持鎖定狀態。此外，BEGIN 沒有巢狀，因此在開始新的交易之前，你必須確保沒有其他交易處於活動狀態。「交易」方法會自動處理所有這些細節。

語法如下所示

dbcmd  transaction  ?transaction-type?   script

交易類型可以是延遲、獨佔或立即。預設為延遲。

「快取」方法

「eval」方法（如上文所述）會為最近評估的 SQL 指令保留已準備好陳述的快取。「快取」方法用於控制這個快取。此指令的第一個形式為

dbcmd  快取大小  N

這會設定可快取的陳述最大數量。上限為 100。預設為 10。如果您將快取大小設定為 0，則不會進行快取。

此指令的第二個形式為

dbcmd  快取清除

快取清除方法會完成快取中目前所有已準備好的陳述。

「完成」方法

「完成」方法會將假設的 SQL 字串作為其唯一引數。如果字串是完整的 SQL 陳述，則會傳回 TRUE；如果還有更多內容要輸入，則會傳回 FALSE。

在建立互動式應用程式時，「完成」方法非常有用，因為它可以讓您知道使用者是否已完成輸入一行 SQL 程式碼。這其實只是sqlite3_complete() C 函式的介面。

「設定」方法

「設定」方法會使用sqlite3_db_config()介面查詢或變更資料庫連線的特定設定值。執行此方法時不帶任何引數，以取得可用設定值及其目前值的 TCL 清單

dbcmd  設定

上述指令會傳回類似以下內容

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 設定可防止虛擬表格和可疑的 SQL 函數用於觸發器、檢視、CHECK 約束、已產生欄位和運算式索引中。關閉 dqs_dml 和 dqs_ddl 設定可防止使用雙引號字串。開啟防禦設定可防止直接寫入影子表格。 

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

「複製」方法

「複製」方法會將資料從檔案複製到表格中。它會傳回從檔案中成功處理的列數。複製方法的語法如下所示

dbcmd  copy  衝突演算法   表格名稱   檔案名稱      ?欄位分隔符號?   ?空值指標?

衝突演算法必須是 INSERT 陳述式的 SQLite 衝突演算法之一：rollback、abort、fail、ignore 或 replace。請參閱 SQLite 語言部分的 ON CONFLICT 以取得更多資訊。衝突演算法必須以小寫指定。

表格名稱必須已存在為表格。檔案名稱必須存在，且每一列都必須包含與表格中定義的相同欄位數。如果檔案中的某一行包含多於或少於定義的欄位數，複製方法會回滾所有插入，並傳回錯誤。

欄位分隔符號是選用的欄位分隔符號字串。預設值是 ASCII tab 字元 \t。

Null 指標是一個選用的字串，用來表示欄位值為 null。預設值為空字串。請注意，欄位分隔符號和 null 指標是選用的位置引數；如果指定了 null 指標，則必須指定欄位分隔符號引數，且欄位分隔符號引數必須在 null 指標引數之前。

複製方法實作類似於 .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 程序，則會使用 SQL 參數的名稱呼叫該程序，並將程序的傳回值繫結到 SQL 參數。或者，如果程序傳回錯誤，則 SQL 陳述式會中止並顯示該錯誤。如果程序傳回 TCL_OK 或 TCL_ERROR 以外的某些程式碼，則 SQL 參數會繫結到 NULL，就像預設一樣。

"bind_fallback" 方法有一個單一可選參數。如果參數為空字串，則會取消 bind_fallback 並回復預設行為。如果參數為非空字串，則參數為 TCL 命令（通常是程序的名稱），每當看到與任何 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 錯誤代碼（通常在成功時為 SQLITE_OK 的 0，或在發生某些錯誤時為 SQLITE_ERROR 的 1）。如 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 清單

陳述 的追蹤每次執行新的 SQL 陳述時，都會以兩個引數呼叫回呼。第一個引數是整數，為指向底層 sqlite3_stmt 物件的指標值。此整數可將 SQL 陳述文字與 剖析 或 列 回呼的結果關聯起來。第二個引數是正在執行的 SQL 陳述的未展開文字。所謂「未展開」，是指文字中的變數替換未展開為變數值。這與「追蹤」方法的行為不同，後者會展開變數替換。

剖析 的追蹤在每個 SQL 陳述完成時，以兩個引數呼叫回呼。第一個引數是整數，為底層 sqlite3_stmt 物件的值。第二個引數是陳述的大約執行時間（以奈秒為單位）。執行時間是根據應用程式執行平台的功能提供的最佳估計值。

列 的追蹤在 SQL 陳述有新的結果列可用時，以單一引數呼叫回呼。引數是整數，為底層 sqlite3_stmt 物件指標的值。

關閉 的追蹤在資料庫連線關閉時，以單一引數呼叫回呼。引數是整數，為指向正在關閉的底層 sqlite3 物件的指標值。

資料庫連線上只能註冊單一追蹤回呼。每次使用「追蹤」或「追蹤_v2」都會取消所有先前的追蹤回呼。

「備份」方法

「備份」方法會製作一個備份副本的即時資料庫。指令語法如下

dbcmd  backup  ?來源資料庫?  備份檔名

選用的 來源資料庫 引數會指出目前連線中哪個資料庫應該備份。預設值為 main（或換句話說，就是主資料庫檔案）。若要備份 TEMP 資料表，請使用 temp。若要備份使用 ATTACH 指令新增到連線的輔助資料庫，請使用在 ATTACH 指令中指定的那個資料庫名稱。

備份檔名 是備份寫入的檔案名稱。備份檔名 不必事先存在，但如果存在，它必須是格式良好的 SQLite 資料庫。

「還原」方法

「還原」方法將內容從一個獨立的資料庫檔案複製到目前的資料庫連線，覆寫任何已存在的內容。指令語法如下

dbcmd  restore  ?目標資料庫?  來源檔名

選用的 目標資料庫 參數會說明目前連線中哪一個資料庫應被覆寫為新內容。預設值為 main (或換句話說，主資料庫檔案)。若要重新填入 TEMP 資料表，請使用 temp。若要覆寫使用 ATTACH 指令加入連線的輔助資料庫，請使用該資料庫在 ATTACH 指令中指定的資料庫名稱。

來源檔名 是現有格式良好的 SQLite 資料庫檔案名稱，內容將從中擷取。

「序列化」方法

「序列化」方法會建立一個 BLOB，它是底層資料庫的完整副本。語法如下

dbcmd  serialize  ?資料庫?

選用參數是將序列化的架構或資料庫名稱。預設值為「main」。

此常式會傳回一個 TCL 位元組陣列，其中包含已識別資料庫的完整內容。此位元組陣列可以寫入檔案，然後當成一般的 SQLite 資料庫使用，或者可以透過 TCP/IP 連線傳送給其他應用程式，或是傳遞給其他資料庫連線的「解除序列化」方法。

此方法僅在 SQLite 編譯時加上 -DSQLITE_ENABLE_DESERIALIZE 時才會運作

「解除序列化」方法

「解除序列化」方法會取得包含 SQLite 資料庫檔案的 TCL 位元組陣列，並將其加入資料庫連線。語法如下

dbcmd  deserialize  ?database?  value

選項 database 引數會識別哪個附加資料庫應接收解除序列化。預設值為「main」。

此命令會導致 SQLite 與前一個資料庫斷線，並重新附加到記憶體中資料庫，內容為 value。如果 value 不是包含定義良好的 SQLite 資料庫的位元組陣列，則後續命令可能會傳回 SQLITE_CORRUPT 錯誤。

此方法僅在 SQLite 編譯時加上 -DSQLITE_ENABLE_DESERIALIZE 時才會運作

「中斷」方法

「中斷」方法會呼叫 sqlite3_interrupt() 介面，導致任何待處理查詢暫停。

「版本」方法

傳回目前的函式庫版本。例如，「3.23.0」。

「剖析」方法

此方法用於剖析應用程式執行的 SQL 陳述式。語法如下

dbcmd  profile  ?script?

除非 script 是空字串，此方法會安排在執行每個 SQL 陳述式後評估 script。在呼叫 script 之前，會附加兩個引數：已執行的 SQL 陳述式的文字，以及執行陳述式時經過的時間（以奈秒為單位）。

資料庫控制代碼一次只能註冊一個設定檔指令碼。如果在呼叫設定檔方法時已註冊指令碼，則會以新的指令碼取代先前的設定檔指令碼。如果 script 引數是空字串，則會取消先前註冊的任何設定檔回呼，但不會註冊新的設定檔指令碼。

「unlock_notify」方法

unlock_notify 方法用於存取 sqlite3_unlock_notify() 介面，以進行 SQLite 核心函式庫的測試。不建議應用程式使用此方法。

此頁面最後修改於 2023-03-25 03:02:51 UTC