開啟新的資料庫連線

小巧、快速、可靠。
選擇其中三項。

SQLite C 介面

int sqlite3_open(
  const char *filename,   /* Database filename (UTF-8) */
  sqlite3 **ppDb          /* OUT: SQLite db handle */
);
int sqlite3_open16(
  const void *filename,   /* Database filename (UTF-16) */
  sqlite3 **ppDb          /* OUT: SQLite db handle */
);
int sqlite3_open_v2(
  const char *filename,   /* Database filename (UTF-8) */
  sqlite3 **ppDb,         /* OUT: SQLite db handle */
  int flags,              /* Flags */
  const char *zVfs        /* Name of VFS module to use */
);

這些函式會開啟以 filename 參數指定的 SQLite 資料庫檔案。 sqlite3_open() 和 sqlite3_open_v2() 將 filename 參數解譯為 UTF-8，而 sqlite3_open16() 則將其解譯為原生位元組順序的 UTF-16。即使發生錯誤，通常也會在 *ppDb 中返回資料庫連線控制代碼。唯一的例外是，如果 SQLite 無法配置記憶體來存放 sqlite3 物件，則會在 *ppDb 中寫入 NULL，而不是指向 sqlite3 物件的指標。如果資料庫成功開啟（和/或建立），則返回 SQLITE_OK。否則返回錯誤碼。在任何 sqlite3_open() 函式失敗後，可以使用 sqlite3_errmsg() 或 sqlite3_errmsg16() 函式來取得錯誤的英文描述。

使用 sqlite3_open() 或 sqlite3_open_v2() 建立的資料庫，預設編碼為 UTF-8。使用 sqlite3_open16() 建立的資料庫，預設編碼為原生位元組順序的 UTF-16。

無論開啟時是否發生錯誤，當不再需要資料庫連線控制代碼時，都應將其傳遞給 sqlite3_close() 來釋放相關資源。

sqlite3_open_v2() 介面的工作方式與 sqlite3_open() 類似，但它接受兩個額外的參數，以對新的資料庫連線進行額外的控制。 sqlite3_open_v2() 的 flags 參數至少必須包含以下三種旗標組合之一：

SQLITE_OPEN_READONLY: 以唯讀模式開啟資料庫。如果資料庫不存在，則返回錯誤。
SQLITE_OPEN_READWRITE: 如果可能，以讀寫模式開啟資料庫；如果檔案受到作業系統的寫入保護，則以唯讀模式開啟。無論哪種情況，資料庫都必須已存在，否則會返回錯誤。基於歷史原因，如果以讀寫模式開啟失敗是由於作業系統層級的權限問題，則會嘗試以唯讀模式開啟。可以使用 sqlite3_db_readonly() 來確定資料庫實際上是否為唯讀。
SQLITE_OPEN_READWRITE | SQLITE_OPEN_CREATE: 以讀寫模式開啟資料庫，如果資料庫不存在則建立它。這是 sqlite3_open() 和 sqlite3_open16() 一直使用的行為。

除了必要的旗標之外，還支援以下選用旗標：

SQLITE_OPEN_URI

如果設定此旗標，則 filename 可以被解譯為 URI。

SQLITE_OPEN_MEMORY

資料庫將作為記憶體資料庫開啟。為了快取共享的目的（如果啟用了共享快取模式），資料庫由「filename」參數命名，但除此之外，「filename」會被忽略。

SQLITE_OPEN_NOMUTEX

新的資料庫連線將使用「多執行緒」執行緒模式。這表示允許不同的執行緒同時使用 SQLite，只要每個執行緒使用不同的資料庫連線。

SQLITE_OPEN_FULLMUTEX

新的資料庫連線將使用「序列化」執行緒模式。這表示多個執行緒可以安全地嘗試同時使用同一個資料庫連線。（互斥鎖會阻止任何實際的並行，但在這種模式下，嘗試並行操作沒有壞處。）

SQLITE_OPEN_SHAREDCACHE

資料庫以啟用共享快取的方式開啟，這將覆蓋sqlite3_enable_shared_cache()提供的預設共享快取設定。不建議使用共享快取模式，因此許多 SQLite 版本可能省略了共享快取功能。在這種情況下，此選項無效。

SQLITE_OPEN_PRIVATECACHE

資料庫以停用共享快取的方式開啟，這將覆蓋sqlite3_enable_shared_cache()提供的預設共享快取設定。

SQLITE_OPEN_EXRESCODE

資料庫連線以「擴展結果代碼模式」啟動。換句話說，資料庫的行為就像在建立連線後立即對資料庫連線呼叫sqlite3_extended_result_codes(db,1)一樣。除了設定擴展結果代碼模式外，此旗標還會使sqlite3_open_v2()返回擴展結果代碼。

SQLITE_OPEN_NOFOLLOW

資料庫檔名不允許包含符號連結。

如果 sqlite3_open_v2() 的第三個參數不是上面顯示的必要組合（可選擇與其他 SQLITE_OPEN_* 位元組合），則行為未定義。過去版本的 SQLite 會忽略 sqlite3_open_v2() 的 flags 參數中的多餘位元，但未來的 SQLite 版本可能不會延續此行為，因此應用程式不應依賴它。尤其要注意的是，SQLITE_OPEN_EXCLUSIVE 旗標對於 sqlite3_open_v2() 來說無效。如果資料庫已存在，SQLITE_OPEN_EXCLUSIVE *不會* 導致開啟失敗。SQLITE_OPEN_EXCLUSIVE 旗標僅供 VFS 介面使用，而不是供 sqlite3_open_v2() 使用。

sqlite3_open_v2() 的第四個參數是定義新資料庫連線應使用的作業系統介面的 sqlite3_vfs 物件的名稱。如果第四個參數是 NULL 指標，則使用預設的 sqlite3_vfs 物件。

如果檔名是 ":memory:"，則會為該連線建立一個私有的、暫時的記憶體資料庫。當資料庫連線關閉時，此記憶體資料庫將消失。未來版本的 SQLite 可能會使用其他以 ":" 字元開頭的特殊檔名。建議當資料庫檔名實際上以 ":" 字元開頭時，您應該在檔名前加上路徑名稱，例如 "./"，以避免歧義。

如果檔名是空字串，則會建立一個私有的、暫時的磁碟資料庫。此私有資料庫將在資料庫連線關閉後自動刪除。

URI 檔名

如果啟用了URI 檔名的解析，並且檔名參數以 "file:" 開頭，則檔名會被解釋為 URI。如果在 sqlite3_open_v2() 的第三個參數中設定了 SQLITE_OPEN_URI 旗標，或者使用 SQLITE_CONFIG_URI 選項和 sqlite3_config() 方法或通過 SQLITE_USE_URI 編譯時選項全域啟用了它，則會啟用 URI 檔名解析。URI 檔名解析預設為關閉，但未來版本的 SQLite 可能會預設啟用 URI 檔名解析。有關更多資訊，請參閱「URI 檔名」。

URI 檔名會根據 RFC 3986 進行解析。如果 URI 包含授權機構，則它必須是空字串或字串 "localhost"。如果授權機構不是空字串或 "localhost"，則會向呼叫者返回錯誤。URI 的片段組件（如果存在）將被忽略。

SQLite 使用 URI 的路徑組件作為包含資料庫的磁碟檔案的名稱。如果路徑以 '/' 字元開頭，則它會被解釋為絕對路徑。如果路徑不是以 '/' 開頭（表示 URI 中省略了授權機構部分），則該路徑會被解釋為相對路徑。在 Windows 上，絕對路徑的第一個組件是磁碟機規格（例如 "C:"）。

URI 的查詢組件可能包含由 SQLite 本身或自定義 VFS 實作解讀的參數。SQLite 及其內建的VFS會解讀下列查詢參數：

vfs：「vfs」參數可用於指定 VFS 物件的名稱，該物件提供應用於存取磁碟上資料庫檔案的作業系統介面。如果此選項設定為空字串，則使用預設的 VFS 物件。指定未知的 VFS 是一個錯誤。如果使用 sqlite3_open_v2() 且存在 vfs 選項，則選項指定的 VFS 優先於傳給 sqlite3_open_v2() 作為第四個參數的值。
mode：mode 參數可以設定為「ro」、「rw」、「rwc」或「memory」。嘗試將其設定為任何其他值是一個錯誤。如果指定「ro」，則資料庫以唯讀方式開啟，就像在 sqlite3_open_v2() 的第三個參數中設定了 SQLITE_OPEN_READONLY 旗標一樣。如果 mode 選項設定為「rw」，則資料庫以讀寫（但不建立）存取方式開啟，就像設定了 SQLITE_OPEN_READWRITE（但未設定 SQLITE_OPEN_CREATE）一樣。值「rwc」相當於同時設定 SQLITE_OPEN_READWRITE 和 SQLITE_OPEN_CREATE。如果 mode 選項設定為「memory」，則使用純記憶體資料庫，它從不讀取或寫入磁碟。指定一個限制性低於傳給 sqlite3_open_v2() 的第三個參數中旗標所指定限制的 mode 參數值是一個錯誤。
cache：cache 參數可以設定為「shared」或「private」。將其設定為「shared」相當於在傳給 sqlite3_open_v2() 的 flags 參數中設定 SQLITE_OPEN_SHAREDCACHE 位元。將 cache 參數設定為「private」相當於設定 SQLITE_OPEN_PRIVATECACHE 位元。如果使用 sqlite3_open_v2() 且 URI 檔名中存在「cache」參數，則其值會覆蓋透過設定 SQLITE_OPEN_PRIVATECACHE 或 SQLITE_OPEN_SHAREDCACHE 旗標所要求的任何行為。
psow：psow 參數指示電源安全覆寫屬性是否適用於資料庫檔案所在的儲存媒體。
nolock：nolock 參數是一個布林值查詢參數，如果設定，則會在回滾日誌模式中停用檔案鎖定。這對於存取不支援鎖定的檔案系統上的資料庫很有用。注意：如果兩個或多個處理程序寫入同一個資料庫，且其中任何一個處理程序使用 nolock=1，則可能會導致資料庫損毀。
immutable：immutable 參數是一個布林值查詢參數，指示資料庫檔案儲存在唯讀媒體上。當設定 immutable 時，SQLite 假設資料庫檔案無法更改，即使是具有較高權限的處理程序也無法更改，因此資料庫以唯讀方式開啟，並且所有鎖定和變更偵測都被停用。注意：在實際會變更的資料庫檔案上設定 immutable 屬性可能會導致錯誤的查詢結果和/或 SQLITE_CORRUPT 錯誤。另請參閱：SQLITE_IOCAP_IMMUTABLE。

在 URI 的查詢組件中指定未知參數不是錯誤。未來版本的 SQLite 可能會理解其他查詢參數。有關其他資訊，請參閱「對 SQLite 具有特殊含義的查詢參數」。

URI 檔名範例

URI 檔名	結果
file:data.db	開啟目前目錄中的檔案「data.db」。
file:/home/fred/data.db file:///home/fred/data.db file://127.0.0.1/home/fred/data.db	開啟資料庫檔案「/home/fred/data.db」。
file://darkstar/home/fred/data.db	錯誤。「darkstar」不是已辨識的授權單位。
file:///C:/Documents%20and%20Settings/fred/Desktop/data.db	僅限 Windows：開啟 C 槽上 fred 桌面上的檔案「data.db」。請注意，此範例中的 %20 跳脫字元並非絕對必要 — 空格字元可以在 URI 檔名中直接使用。
file:data.db?mode=ro&cache=private	以唯讀模式開啟目前目錄下的 "data.db" 檔案。無論預設是否啟用共享快取模式，皆使用私有快取。
file:/home/fred/data.db?vfs=unix-dotfile	開啟檔案 "/home/fred/data.db"。使用特殊的 VFS "unix-dotfile"，它使用點文件 (dot-files) 來取代 POSIX 諮詢式鎖定 (advisory locking)。
file:data.db?mode=readonly	錯誤。"readonly" 不是 "mode" 參數的有效選項。請改用 "ro"："file:data.db?mode=ro"。

URI 十六進位逸出序列 (%HH) 在 URI 的路徑和查詢組成部分中受到支援。十六進位逸出序列由一個百分比符號 - "%" - 後面接兩個十六進位數字組成，用於指定一個八位元組值。在解譯 URI 檔案名的路徑或查詢組成部分之前，會先使用 UTF-8 編碼，並將所有十六進位逸出序列替換為包含對應八位元組值的單個位元組。如果此過程產生無效的 UTF-8 編碼，結果未定義。

Windows 使用者注意事項：sqlite3_open() 和 sqlite3_open_v2() 的檔案名稱參數使用的編碼必須是 UTF-8，而不是目前定義的任何字碼頁。包含國際字元的檔案名稱必須在傳遞給 sqlite3_open() 或 sqlite3_open_v2() 之前轉換為 UTF-8。

Windows 執行階段使用者注意事項：必須在呼叫 sqlite3_open() 或 sqlite3_open_v2() 之前設定暫存目錄。否則，需要使用暫存檔案的各種功能可能會失敗。

另請參閱：sqlite3_temp_directory

另請參閱物件、常數和函式列表。