統一資源識別碼

1. SQLite 中的 URI 檔案名稱

從版本 3.7.7（2011-06-23）開始，傳遞給 sqlite3_open()、sqlite3_open16() 和 sqlite3_open_v2() 介面以及 ATTACH 指令的 SQLite 資料庫檔案引數可以指定為一般檔案名稱或統一資源識別碼（URI）。使用 URI 檔案名稱的優點是，URI 上的查詢參數可用於控制新建立的資料庫連線的詳細資料。例如，可以使用「vfs=」查詢參數指定替代 VFS。或者，可以使用「mode=ro」作為查詢參數來以唯讀方式開啟資料庫。

2. 向下相容性

為了維持舊有應用程式的完整向下相容性，URI 檔案名稱功能預設為停用。可以使用 SQLITE_USE_URI=1 或 SQLITE_USE_URI=0 編譯時期選項啟用或停用 URI 檔案名稱。URI 檔案名稱的編譯時期設定可以在啟動時使用 sqlite3_config(SQLITE_CONFIG_URI,1) 或 sqlite3_config(SQLITE_CONFIG_URI,0) 設定呼叫來變更。不論編譯時期或啟動時期的設定，都可以透過將 SQLITE_OPEN_URI 位元包含在傳遞給 sqlite3_open_v2(N,P,F,V) 的 F 參數的位元組中，為個別資料庫連線啟用 URI 檔案名稱。

如果在最初開啟資料庫連線時識別了 URI 檔名，則在 ATTACH 陳述中也會識別 URI 檔名。類似地，如果在最初開啟資料庫連線時未識別 URI 檔名，則 ATTACH 將不會識別它們。

由於 SQLite 總是將任何不以「file:」開頭的檔名解釋為一般檔名，而實際檔名以「file:」開頭的情況非常罕見，因此，即使目前未使用 URI 檔名，大多數應用程式也可以安全地啟用 URI 處理。

3. URI 格式

根據 RFC 3986，URI 包含一個架構、一個授權、一個路徑、一個查詢字串和一個片段。架構始終是必需的。授權或路徑其中之一也始終是必需的。查詢字串和片段是可選的。

SQLite 使用「file:」URI 語法來識別資料庫檔案。SQLite 努力以與 Firefox、Chrome、Safari、Internet Explorer 和 Opera 等熱門網路瀏覽器，以及 Windows "cmd start" 或 "powershell start" 等命令列程式，或 macOS「open」或 Linux「xdg-open」命令完全相同的方式來解釋檔案：URI。以下是 URI 解析規則的簡潔摘要

URI 的架構必須為「file:」。任何其他架構都會導致輸入被視為一般檔案名稱。
可以省略授權，也可以為空白或「localhost」。任何其他授權都會導致錯誤。例外：如果 SQLite 使用 SQLITE_ALLOW_URI_AUTHORITY 編譯，則「localhost」以外的任何授權值都會作為 UNC 檔案名稱傳遞給底層作業系統。
如果存在授權，則路徑為選用。如果省略授權，則路徑為必要。
查詢字串為選用。如果存在查詢字串，則所有查詢參數都會傳遞到底層 VFS 的 xOpen 方法中。
片段為選用。如果存在，則會被忽略。

路徑、查詢字串或片段中可以出現零個或多個「%HH」形式的跳脫字元序列（其中H 代表任何十六進位數字）。

未形成良好 URI 的檔案名稱會被解釋為一般檔案名稱。

URI 會被處理為 UTF8 文字。在處理之前，sqlite3_open16() 的檔案名稱參數會從 UTF16 原生位元組順序轉換為 UTF8。

3.1. URI 路徑

URI 的路徑元件指定要開啟的 SQLite 資料庫的磁碟檔案。如果省略路徑元件，則資料庫會儲存在暫存檔案中，當資料庫連線關閉時，該檔案會自動刪除。如果權限區段存在，則路徑永遠是絕對路徑名稱。如果省略權限區段，則路徑是絕對路徑名稱（如果以「/」字元（ASCII 碼 0x2f）開頭）或相對路徑名稱（否則）。在 Windows 中，如果絕對路徑以「/X:/」開頭，其中 X 是任何單一 ASCII 字母字元（「a」到「z」或「A」到「Z」），則會將「X:」視為包含檔案的磁碟機磁碟代號，而不是頂層目錄。

一般來說，可以透過以下步驟將一般檔案名稱轉換成等效的 URI。唯一的例外是，帶有磁碟代號的相對 Windows 路徑名稱無法直接轉換成 URI；必須先將其變更為絕對路徑名稱。

將所有「?」字元轉換成「%3f」。
將所有「#」字元轉換成「%23」。
僅在 Windows 中，將所有「\」字元轉換成「/」。
將所有兩個或以上「/」字元序列轉換成單一「/」字元。
僅在 Windows 中，如果檔案名稱以磁碟代號開頭，則在前面加上單一「/」字元。
在前面加上「file:」架構。

3.2. 查詢字串

URI 檔名可以選擇性地加上查詢字串。查詢字串包含第一個「?」字元之後的文字，但排除以「#」開頭的選用片段。查詢字串會分成金鑰/值對。我們通常將這些金鑰/值對稱為「查詢參數」。金鑰/值對會以單一「&」字元分隔。金鑰在先，並以單一「=」字元與值分隔。金鑰和值都可能包含 %HH 跳脫序列。

查詢參數的文字會附加到 VFS 的 xOpen 方法的檔名引數。查詢參數中的任何 %HH 跳脫序列都會在附加到 xOpen 檔名之前解析。單一零位元組會將 xOpen 檔名引數與第一個查詢參數的金鑰、每個金鑰和值，以及每個後續金鑰與前一個值分隔開來。附加到 xOpen 檔名的查詢參數清單會以單一零長度金鑰終止。請注意，查詢參數的值可以是空字串。

3.3. 已識別的查詢參數

某些查詢參數會由 SQLite 核心來詮釋，並用於修改新連線的特性。所有查詢參數都會始終傳遞到 VFS 的 xOpen 方法，即使它們先前已由 SQLite 核心讀取和詮釋。

截至版本 3.15.0（2016-10-14），SQLite 已識別下列查詢參數。未來可能會新增新的查詢參數。

cache=shared cache=private: 快取查詢參數會決定新的資料庫是否使用共用快取模式或使用私人快取來開啟。
immutable=1: immutable 查詢參數是一個布林值，用於向 SQLite 指示基礎資料庫檔案儲存在唯讀媒體上，且無法修改，即使是由具有提升權限的另一個程序也無法修改。SQLite 始終以唯讀方式開啟 immutable 資料庫檔案，且會略過所有檔案鎖定和對 immutable 資料庫檔案的變更偵測。如果這個查詢參數（或 xDeviceCharacteristics 中的 SQLITE_IOCAP_IMMUTABLE 位元）斷言資料庫檔案為 immutable，且該檔案發生任何變更，則 SQLite 可能會傳回不正確的查詢結果和/或 SQLITE_CORRUPT 錯誤。
mode=ro mode=rw mode=rwc mode=memory: mode 查詢參數分別決定新的資料庫是否以唯讀、讀寫、讀寫且在不存在時建立，或資料庫為純粹的記憶體中資料庫，且從不與磁碟互動。
modeof=filename: 在 unix 系統上於 sqlite3_open_v2() 期間建立新的資料庫檔案時，SQLite 會嘗試將新資料庫檔案的權限設定為與現有檔案「filename」相符。
nolock=1: nolock 查詢參數是一個布林值，在為 true 時會停用對 VFS 的 xLock、xUnlock 和 xCheckReservedLock 方法的所有呼叫。例如，在嘗試存取不支援檔案鎖定的檔案系統上的檔案時，可以使用 nolock 查詢參數。注意：如果兩個或更多個資料庫連線嘗試與同一個 SQLite 資料庫互動，且其中一個或多個連線已啟用「nolock」，則可能會導致資料庫損毀。「nolock」查詢參數僅應在應用程式可以保證對資料庫的寫入已序列化時使用。
psow=0 psow=1: psow 查詢參數會覆寫正在開啟的資料庫檔案的 powersafe overwrite 屬性。psow 查詢參數適用於預設的 Windows 和 Unix VFS，但對於其他專有或非標準 VFS 來說可能沒有作用。
vfs=NAME: vfs 查詢參數會導致資料庫連線使用稱為 NAME 的 VFS 開啟。如果 NAME 不是內建於 SQLite 或先前已使用 sqlite3_vfs_register() 註冊的 VFS 的名稱，則開啟嘗試會失敗。

4. 另請參閱

此頁面最後修改於 2023-01-02 14:22:42 UTC