SQLite#

穩定性:1.1 - 積極開發中。

原始碼: lib/sqlite.js

node:sqlite 模組便於使用 SQLite 資料庫。要訪問它:

import sqlite from 'node:sqlite';const sqlite = require('node:sqlite');

此模組僅在 node: 協議下可用。

以下示例展示了 node:sqlite 模組的基本用法,用於開啟一個記憶體資料庫,向資料庫寫入資料,然後將資料讀回。

import { DatabaseSync } from 'node:sqlite';
const database = new DatabaseSync(':memory:');

// Execute SQL statements from strings.
database.exec(`
  CREATE TABLE data(
    key INTEGER PRIMARY KEY,
    value TEXT
  ) STRICT
`);
// Create a prepared statement to insert data into the database.
const insert = database.prepare('INSERT INTO data (key, value) VALUES (?, ?)');
// Execute the prepared statement with bound values.
insert.run(1, 'hello');
insert.run(2, 'world');
// Create a prepared statement to read data from the database.
const query = database.prepare('SELECT * FROM data ORDER BY key');
// Execute the prepared statement and log the result set.
console.log(query.all());
// Prints: [ { key: 1, value: 'hello' }, { key: 2, value: 'world' } ]'use strict';
const { DatabaseSync } = require('node:sqlite');
const database = new DatabaseSync(':memory:');

// Execute SQL statements from strings.
database.exec(`
  CREATE TABLE data(
    key INTEGER PRIMARY KEY,
    value TEXT
  ) STRICT
`);
// Create a prepared statement to insert data into the database.
const insert = database.prepare('INSERT INTO data (key, value) VALUES (?, ?)');
// Execute the prepared statement with bound values.
insert.run(1, 'hello');
insert.run(2, 'world');
// Create a prepared statement to read data from the database.
const query = database.prepare('SELECT * FROM data ORDER BY key');
// Execute the prepared statement and log the result set.
console.log(query.all());
// Prints: [ { key: 1, value: 'hello' }, { key: 2, value: 'world' } ]

類:DatabaseSync#

此類表示到 SQLite 資料庫的單個連線。此類公開的所有 API 均同步執行。

new DatabaseSync(path[, options])#

  • path <string> | <Buffer> | <URL> 資料庫的路徑。SQLite 資料庫可以儲存在檔案中或完全儲存在記憶體中。要使用檔案支援的資料庫,路徑應為檔案路徑。要使用記憶體資料庫,路徑應為特殊名稱 ':memory:'
  • options <Object> 資料庫連線的配置選項。支援以下選項:
    • open <boolean> 如果為 true,資料庫將由建構函式開啟。當此值為 false 時,必須透過 open() 方法開啟資料庫。預設值:true
    • readOnly <boolean> 如果為 true,資料庫將以只讀模式開啟。如果資料庫不存在,開啟將失敗。預設值:false
    • enableForeignKeyConstraints <boolean> 如果為 true,則啟用外部索引鍵約束。推薦使用此選項,但為了與舊資料庫模式相容可以停用。外部索引鍵約束的強制執行可以在開啟資料庫後使用 PRAGMA foreign_keys 啟用和停用。預設值:true
    • enableDoubleQuotedStringLiterals <boolean> 如果為 true,SQLite 將接受雙引號字串字面量。不推薦使用此選項,但為了與舊資料庫模式相容可以啟用。預設值:false
    • allowExtension <boolean> 如果為 true,則啟用 loadExtension SQL 函式和 loadExtension() 方法。您可以稍後呼叫 enableLoadExtension(false) 來停用此功能。預設值:false
    • timeout <number> 繁忙超時時間(以毫秒為單位)。這是 SQLite 在返回錯誤前等待資料庫鎖釋放的最長時間。預設值:0
    • readBigInts <boolean> 如果為 true,整數字段將作為 JavaScript BigInt 值讀取。如果為 false,整數字段將作為 JavaScript 數字讀取。預設值:false
    • returnArrays <boolean> 如果為 true,查詢結果將作為陣列而不是物件返回。預設值:false
    • allowBareNamedParameters <boolean> 如果為 true,則允許繫結沒有字首字元的命名引數(例如,foo 而不是 :foo)。預設值:true
    • allowUnknownNamedParameters <boolean> 如果為 true,繫結時將忽略未知的命名引數。如果為 false,則會對未知的命名引數丟擲異常。預設值:false

構造一個新的 DatabaseSync 例項。

database.aggregate(name, options)#

向 SQLite 資料庫註冊一個新的聚合函式。此方法是 sqlite3_create_window_function() 的包裝器。

  • name <string> 要建立的 SQLite 函式的名稱。
  • options <Object> 函式配置設定。
    • deterministic <boolean> 如果為 true,則在建立的函式上設定 SQLITE_DETERMINISTIC 標誌。預設值:false
    • directOnly <boolean> 如果為 true,則在建立的函式上設定 SQLITE_DIRECTONLY 標誌。預設值:false
    • useBigIntArguments <boolean> 如果為 true,則傳遞給 options.stepoptions.inverse 的整數引數將轉換為 BigInt。如果為 false,整數引數將作為 JavaScript 數字傳遞。預設值:false
    • varargs <boolean> 如果為 trueoptions.stepoptions.inverse 可以使用任意數量的引數呼叫(介於零和 SQLITE_MAX_FUNCTION_ARG 之間)。如果為 false,則 inversestep 必須使用確切的 length 個引數呼叫。預設值:false
    • start <number> | <string> | <null> | <Array> | <Object> | <Function> 聚合函式的初始值。該值在聚合函式初始化時使用。當傳入 <Function> 時,初始值將是其返回值。
    • step <Function> 對聚合中的每一行呼叫的函式。該函式接收當前狀態和行值。此函式的返回值應為新的狀態。
    • result <Function> 用於獲取聚合結果的函式。該函式接收最終狀態,並應返回聚合的結果。
    • inverse <Function> 提供此函式後,aggregate 方法將作為視窗函式工作。該函式接收當前狀態和被移除的行值。此函式的返回值應為新的狀態。

當用作視窗函式時,result 函式將被多次呼叫。

const { DatabaseSync } = require('node:sqlite');

const db = new DatabaseSync(':memory:');
db.exec(`
  CREATE TABLE t3(x, y);
  INSERT INTO t3 VALUES ('a', 4),
                        ('b', 5),
                        ('c', 3),
                        ('d', 8),
                        ('e', 1);
`);

db.aggregate('sumint', {
  start: 0,
  step: (acc, value) => acc + value,
});

db.prepare('SELECT sumint(y) as total FROM t3').get(); // { total: 21 }import { DatabaseSync } from 'node:sqlite';

const db = new DatabaseSync(':memory:');
db.exec(`
  CREATE TABLE t3(x, y);
  INSERT INTO t3 VALUES ('a', 4),
                        ('b', 5),
                        ('c', 3),
                        ('d', 8),
                        ('e', 1);
`);

db.aggregate('sumint', {
  start: 0,
  step: (acc, value) => acc + value,
});

db.prepare('SELECT sumint(y) as total FROM t3').get(); // { total: 21 }

database.close()#

關閉資料庫連線。如果資料庫未開啟,則會丟擲異常。此方法是 sqlite3_close_v2() 的包裝器。

database.loadExtension(path)#

  • path <string> 要載入的共享庫的路徑。

將共享庫載入到資料庫連線中。此方法是 sqlite3_load_extension() 的包裝器。在構造 DatabaseSync 例項時,必須啟用 allowExtension 選項。

database.enableLoadExtension(allow)#

  • allow <boolean> 是否允許載入擴充套件。

啟用或停用 loadExtension SQL 函式和 loadExtension() 方法。如果在構造時 allowExtensionfalse,出於安全原因,您無法啟用載入擴充套件。

database.location([dbName])#

  • dbName <string> 資料庫的名稱。可以是 'main'(預設主資料庫)或使用 ATTACH DATABASE 新增的任何其他資料庫。預設值:'main'
  • 返回:<string> | <null> 資料庫檔案的位置。當使用記憶體資料庫時,此方法返回 null。

此方法是 sqlite3_db_filename() 的包裝器。

database.exec(sql)#

  • sql <string> 要執行的 SQL 字串。

此方法允許執行一個或多個 SQL 語句而不返回任何結果。在執行從檔案中讀取的 SQL 語句時,此方法很有用。此方法是 sqlite3_exec() 的包裝器。

database.function(name[, options], function)#

  • name <string> 要建立的 SQLite 函式的名稱。
  • options <Object> 函式的可選配置設定。支援以下屬性:
    • deterministic <boolean> 如果為 true,則在建立的函式上設定 SQLITE_DETERMINISTIC 標誌。預設值:false
    • directOnly <boolean> 如果為 true,則在建立的函式上設定 SQLITE_DIRECTONLY 標誌。預設值:false
    • useBigIntArguments <boolean> 如果為 true,則傳遞給 function 的整數引數將轉換為 BigInt。如果為 false,整數引數將作為 JavaScript 數字傳遞。預設值:false
    • varargs <boolean> 如果為 truefunction 可以使用任意數量的引數呼叫(介於零和 SQLITE_MAX_FUNCTION_ARG 之間)。如果為 false,則 function 必須使用確切的 function.length 個引數呼叫。預設值:false
  • function <Function> 在呼叫 SQLite 函式時要呼叫的 JavaScript 函式。此函式的返回值應為有效的 SQLite 資料型別:請參閱JavaScript 和 SQLite 之間的型別轉換。如果返回值為 undefined,則結果預設為 NULL

此方法用於建立 SQLite 使用者定義函式。此方法是 sqlite3_create_function_v2() 的包裝器。

database.setAuthorizer(callback)#

  • callback <Function> | <null> 要設定的授權函式,或 null 以清除當前授權函式。

設定一個授權回撥函式,SQLite 將在每次嘗試透過預編譯語句訪問資料或修改資料庫模式時呼叫該函式。這可用於實施安全策略、審計訪問或限制某些操作。此方法是 sqlite3_set_authorizer() 的包裝器。

呼叫時,回撥函式接收五個引數:

  • actionCode <number> 正在執行的操作型別(例如,SQLITE_INSERT, SQLITE_UPDATE, SQLITE_SELECT)。
  • arg1 <string> | <null> 第一個引數(取決於上下文,通常是表名)。
  • arg2 <string> | <null> 第二個引數(取決於上下文,通常是列名)。
  • dbName <string> | <null> 資料庫的名稱。
  • triggerOrView <string> | <null> 導致訪問的觸發器或檢視的名稱。

回撥函式必須返回以下常量之一:

  • SQLITE_OK - 允許操作。
  • SQLITE_DENY - 拒絕操作(導致錯誤)。
  • SQLITE_IGNORE - 忽略操作(靜默跳過)。
const { DatabaseSync, constants } = require('node:sqlite');
const db = new DatabaseSync(':memory:');

// Set up an authorizer that denies all table creation
db.setAuthorizer((actionCode) => {
  if (actionCode === constants.SQLITE_CREATE_TABLE) {
    return constants.SQLITE_DENY;
  }
  return constants.SQLITE_OK;
});

// This will work
db.prepare('SELECT 1').get();

// This will throw an error due to authorization denial
try {
  db.exec('CREATE TABLE blocked (id INTEGER)');
} catch (err) {
  console.log('Operation blocked:', err.message);
}import { DatabaseSync, constants } from 'node:sqlite';
const db = new DatabaseSync(':memory:');

// Set up an authorizer that denies all table creation
db.setAuthorizer((actionCode) => {
  if (actionCode === constants.SQLITE_CREATE_TABLE) {
    return constants.SQLITE_DENY;
  }
  return constants.SQLITE_OK;
});

// This will work
db.prepare('SELECT 1').get();

// This will throw an error due to authorization denial
try {
  db.exec('CREATE TABLE blocked (id INTEGER)');
} catch (err) {
  console.log('Operation blocked:', err.message);
}

database.isOpen#

  • 型別:<boolean> 資料庫當前是否開啟。

database.isTransaction#

database.open()#

開啟在 DatabaseSync 建構函式的 path 引數中指定的資料庫。此方法僅應在資料庫未透過建構函式開啟時使用。如果資料庫已經開啟,則會丟擲異常。

database.prepare(sql)#

將 SQL 語句編譯為預編譯語句。此方法是 sqlite3_prepare_v2() 的包裝器。

database.createTagStore([maxSize])#

  • maxSize <integer> 要快取的預編譯語句的最大數量。預設值:1000
  • 返回:<SQLTagStore> 用於快取預編譯語句的新 SQL 標籤儲存。

建立一個新的 SQLTagStore,它是一個用於儲存預編譯語句的 LRU(最近最少使用)快取。這允許透過使用唯一識別符號標記預編譯語句來高效地重用它們。

當執行一個帶標籤的 SQL 字面量時,SQLTagStore 會檢查快取中是否已存在該特定 SQL 字串的預編譯語句。如果存在,則使用快取的語句。如果不存在,則建立一個新的預編譯語句,執行它,然後將其儲存在快取中以備將來使用。這種機制有助於避免重複解析和準備相同 SQL 語句的開銷。

import { DatabaseSync } from 'node:sqlite';

const db = new DatabaseSync(':memory:');
const sql = db.createTagStore();

db.exec('CREATE TABLE users (id INT, name TEXT)');

// Using the 'run' method to insert data.
// The tagged literal is used to identify the prepared statement.
sql.run`INSERT INTO users VALUES (1, 'Alice')`;
sql.run`INSERT INTO users VALUES (2, 'Bob')`;

// Using the 'get' method to retrieve a single row.
const id = 1;
const user = sql.get`SELECT * FROM users WHERE id = ${id}`;
console.log(user); // { id: 1, name: 'Alice' }

// Using the 'all' method to retrieve all rows.
const allUsers = sql.all`SELECT * FROM users ORDER BY id`;
console.log(allUsers);
// [
//   { id: 1, name: 'Alice' },
//   { id: 2, name: 'Bob' }
// ] 

database.createSession([options])#

  • options <Object> 會話的配置選項。
    • table <string> 要跟蹤更改的特定表。預設情況下,跟蹤所有表的更改。
    • db <string> 要跟蹤的資料庫名稱。當使用 ATTACH DATABASE 添加了多個數據庫時,此選項很有用。預設值'main'
  • 返回:<Session> 會話控制代碼。

建立會話並將其附加到資料庫。此方法是 sqlite3session_create()sqlite3session_attach() 的包裝器。

database.applyChangeset(changeset[, options])#

  • changeset <Uint8Array> 二進位制變更集或補丁集。
  • options <Object> 應用更改方式的配置選項。
    • filter <Function> 跳過那些當目標表名提供給此函式時返回真值的更改。預設情況下,嘗試所有更改。

    • onConflict <Function> 一個確定如何處理衝突的函式。該函式接收一個引數,該引數可以是以下值之一:

      • SQLITE_CHANGESET_DATADELETEUPDATE 更改不包含預期的“之前”值。
      • SQLITE_CHANGESET_NOTFOUND:不存在與 DELETEUPDATE 更改的主鍵匹配的行。
      • SQLITE_CHANGESET_CONFLICTINSERT 更改導致主鍵重複。
      • SQLITE_CHANGESET_FOREIGN_KEY:應用更改將導致外部索引鍵衝突。
      • SQLITE_CHANGESET_CONSTRAINT:應用更改導致 UNIQUECHECKNOT NULL 約束衝突。

      該函式應返回以下值之一:

      • SQLITE_CHANGESET_OMIT:忽略衝突的更改。
      • SQLITE_CHANGESET_REPLACE:用衝突的更改替換現有值(僅在 SQLITE_CHANGESET_DATASQLITE_CHANGESET_CONFLICT 衝突時有效)。
      • SQLITE_CHANGESET_ABORT:在衝突時中止並回滾資料庫。

      當在衝突處理程式中丟擲錯誤或從處理程式返回任何其他值時,應用變更集將中止,資料庫將回滾。

      預設值:返回 SQLITE_CHANGESET_ABORT 的函式。

  • 返回:<boolean> 變更集是否成功應用而未被中止。

如果資料庫未開啟,則會丟擲異常。此方法是 sqlite3changeset_apply() 的包裝器。

const sourceDb = new DatabaseSync(':memory:');
const targetDb = new DatabaseSync(':memory:');

sourceDb.exec('CREATE TABLE data(key INTEGER PRIMARY KEY, value TEXT)');
targetDb.exec('CREATE TABLE data(key INTEGER PRIMARY KEY, value TEXT)');

const session = sourceDb.createSession();

const insert = sourceDb.prepare('INSERT INTO data (key, value) VALUES (?, ?)');
insert.run(1, 'hello');
insert.run(2, 'world');

const changeset = session.changeset();
targetDb.applyChangeset(changeset);
// Now that the changeset has been applied, targetDb contains the same data as sourceDb. 

database[Symbol.dispose]()#

關閉資料庫連線。如果資料庫連線已經關閉,則此操作無效。

類:Session#

session.changeset()#

  • 返回:<Uint8Array> 可應用於其他資料庫的二進位制變更集。

檢索包含自變更集建立以來所有更改的變更集。可以多次呼叫。如果資料庫或會話未開啟,則會丟擲異常。此方法是 sqlite3session_changeset() 的包裝器。

session.patchset()#

  • 返回:<Uint8Array> 可應用於其他資料庫的二進位制補丁集。

與上述方法類似,但生成更緊湊的補丁集。請參閱 SQLite 文件中的變更集和補丁集。如果資料庫或會話未開啟,則會丟擲異常。此方法是 sqlite3session_patchset() 的包裝器。

session.close().#

關閉會話。如果資料庫或會話未開啟,則會丟擲異常。此方法是 sqlite3session_delete() 的包裝器。

類:StatementSync#

此類表示單個預編譯語句。此類不能透過其建構函式例項化。相反,例項是透過 database.prepare() 方法建立的。此類公開的所有 API 均同步執行。

預編譯語句是用於建立它的 SQL 的高效二進位制表示。預編譯語句是可引數化的,並且可以使用不同的繫結值多次呼叫。引數還提供了防止SQL 注入攻擊的保護。因此,在處理使用者輸入時,預編譯語句優於手動拼接的 SQL 字串。

類:SQLTagStore#

此類表示一個用於儲存預編譯語句的 LRU(最近最少使用)快取。

此類的例項透過 database.createTagStore() 方法建立,而不是使用建構函式。該儲存根據提供的 SQL 查詢字串快取預編譯語句。當再次看到相同的查詢時,儲存會檢索快取的語句並透過引數繫結安全地應用新值,從而防止 SQL 注入等攻擊。

快取的 maxSize 預設為 1000 個語句,但可以提供自定義大小(例如,database.createTagStore(100))。此類公開的所有 API 均同步執行。

sqlTagStore.all(sqlTemplate[, ...values])#

  • sqlTemplate <Template Literal> 包含 SQL 查詢的模板字面量。
  • ...values <any> 要插入到模板字面量中的值。
  • 返回:<Array> 一個表示查詢返回的行的物件陣列。

執行給定的 SQL 查詢並以物件陣列的形式返回所有結果行。

sqlTagStore.get(sqlTemplate[, ...values])#

  • sqlTemplate <Template Literal> 包含 SQL 查詢的模板字面量。
  • ...values <any> 要插入到模板字面量中的值。
  • 返回:<Object> | <undefined> 一個表示查詢返回的第一行的物件,如果沒有返回行,則為 undefined

執行給定的 SQL 查詢並以物件形式返回第一個結果行。

sqlTagStore.iterate(sqlTemplate[, ...values])#

  • sqlTemplate <Template Literal> 包含 SQL 查詢的模板字面量。
  • ...values <any> 要插入到模板字面量中的值。
  • 返回:<Iterator> 一個迭代器,該迭代器生成表示查詢返回的行的物件。

執行給定的 SQL 查詢並返回結果行的迭代器。

sqlTagStore.run(sqlTemplate[, ...values])#

  • sqlTemplate <Template Literal> 包含 SQL 查詢的模板字面量。
  • ...values <any> 要插入到模板字面量中的值。
  • 返回:<Object> 一個包含執行資訊的物件,包括 changeslastInsertRowid

執行給定的 SQL 查詢,該查詢預計不返回任何行(例如,INSERT、UPDATE、DELETE)。

sqlTagStore.size()#

  • 返回:<integer> 快取中當前預編譯語句的數量。

一個只讀屬性,返回快取中當前預編譯語句的數量。

sqlTagStore.capacity#

  • 返回:<integer> 快取可以容納的預編譯語句的最大數量。

一個只讀屬性,返回快取可以容納的預編譯語句的最大數量。

sqlTagStore.db#

一個只讀屬性,返回與此 SQLTagStore 關聯的 DatabaseSync 物件。

sqlTagStore.reset()#

重置 LRU 快取,清除所有儲存的預編譯語句。

sqlTagStore.clear()#

sqlTagStore.reset() 的別名。

statement.all([namedParameters][, ...anonymousParameters])#

  • namedParameters <Object> 一個可選物件,用於繫結命名引數。此物件的鍵用於配置對映。
  • ...anonymousParameters <null> | <number> | <bigint> | <string> | <Buffer> | <TypedArray> | <DataView> 零個或多個要繫結到匿名引數的值。
  • 返回:<Array> 物件陣列。每個物件對應於執行預編譯語句返回的一行。每個物件的鍵和值對應於該行的列名和值。

此方法執行一個預編譯語句並以物件陣列的形式返回所有結果。如果預編譯語句不返回任何結果,此方法返回一個空陣列。預編譯語句的引數會使用 namedParametersanonymousParameters 中的值進行繫結。

statement.columns()#

此方法用於檢索有關預編譯語句返回的列的資訊。

statement.expandedSQL#

  • 型別:<string> 展開以包含引數值的源 SQL。

預編譯語句的源 SQL 文字,其中引數佔位符被最近一次執行此預編譯語句時使用的值所替換。此屬性是 sqlite3_expanded_sql() 的包裝器。

statement.get([namedParameters][, ...anonymousParameters])#

  • namedParameters <Object> 一個可選物件,用於繫結命名引數。此物件的鍵用於配置對映。
  • ...anonymousParameters <null> | <number> | <bigint> | <string> | <Buffer> | <TypedArray> | <DataView> 零個或多個要繫結到匿名引數的值。
  • 返回:<Object> | <undefined> 一個對應於執行預編譯語句返回的第一行的物件。物件的鍵和值對應於該行的列名和值。如果資料庫沒有返回任何行,則此方法返回 undefined

此方法執行一個預編譯語句並以物件形式返回第一個結果。如果預編譯語句不返回任何結果,此方法返回 undefined。預編譯語句的引數會使用 namedParametersanonymousParameters 中的值進行繫結。

statement.iterate([namedParameters][, ...anonymousParameters])#

  • namedParameters <Object> 一個可選物件,用於繫結命名引數。此物件的鍵用於配置對映。
  • ...anonymousParameters <null> | <number> | <bigint> | <string> | <Buffer> | <TypedArray> | <DataView> 零個或多個要繫結到匿名引數的值。
  • 返回:<Iterator> 一個可迭代的物件迭代器。每個物件對應於執行預編譯語句返回的一行。每個物件的鍵和值對應於該行的列名和值。

此方法執行一個預編譯語句並返回一個物件迭代器。如果預編譯語句不返回任何結果,此方法返回一個空迭代器。預編譯語句的引數會使用 namedParametersanonymousParameters 中的值進行繫結。

statement.run([namedParameters][, ...anonymousParameters])#

此方法執行一個預編譯語句並返回一個總結結果更改的物件。預編譯語句的引數會使用 namedParametersanonymousParameters 中的值進行繫結。

statement.setAllowBareNamedParameters(enabled)#

  • enabled <boolean> 啟用或停用對不帶字首字元的命名引數繫結的支援。

SQLite 引數的名稱以一個字首字元開頭。預設情況下,node:sqlite 要求在繫結引數時必須存在此字首字元。然而,除了美元符號外,這些字首字元在物件鍵中使用時也需要額外的引號。

為提高易用性,此方法可用於也允許裸命名引數,這在 JavaScript 程式碼中不需要字首字元。啟用裸命名引數時需要注意幾個問題:

  • 在 SQL 中仍然需要字首字元。
  • 在 JavaScript 中仍然允許使用字首字元。實際上,帶字首的名稱會有稍好的繫結效能。
  • 在同一個預編譯語句中使用模糊的命名引數,如 $k@k,將導致異常,因為它無法確定如何繫結裸名稱。

statement.setAllowUnknownNamedParameters(enabled)#

  • enabled <boolean> 啟用或停用對未知命名引數的支援。

預設情況下,如果在繫結引數時遇到未知名稱,將丟擲異常。此方法允許忽略未知的命名引數。

statement.setReturnArrays(enabled)#

  • enabled <boolean> 啟用或停用以陣列形式返回查詢結果。

啟用後,all()get()iterate() 方法返回的查詢結果將以陣列形式返回,而不是物件。

statement.setReadBigInts(enabled)#

  • enabled <boolean> 啟用或停用在從資料庫讀取 INTEGER 欄位時使用 BigInt

從資料庫讀取時,SQLite 的 INTEGER 預設對映為 JavaScript 數字。然而,SQLite 的 INTEGER 可以儲存比 JavaScript 數字所能表示的更大的值。在這種情況下,此方法可用於使用 JavaScript 的 BigInt 讀取 INTEGER 資料。此方法對資料庫寫入操作沒有影響,因為數字和 BigInt 在任何時候都受支援。

statement.sourceSQL#

  • 型別:<string> 用於建立此預編譯語句的源 SQL。

預編譯語句的源 SQL 文字。此屬性是 sqlite3_sql() 的包裝器。

JavaScript 和 SQLite 之間的型別轉換#

當 Node.js 向 SQLite 寫入或從中讀取時,需要在 JavaScript 資料型別和 SQLite 的資料型別之間進行轉換。因為 JavaScript 支援的資料型別比 SQLite 多,所以只支援 JavaScript 型別的一個子集。嘗試將不支援的資料型別寫入 SQLite 將導致異常。

SQLiteJavaScript
NULL<null>
INTEGER<number><bigint>
REAL<number>
TEXT<string>
BLOB<TypedArray><DataView>

sqlite.backup(sourceDb, path[, options])#

  • sourceDb <DatabaseSync> 要備份的資料庫。源資料庫必須是開啟的。
  • path <string> | <Buffer> | <URL> 將建立備份的路徑。如果檔案已存在,內容將被覆蓋。
  • options <Object> 備份的可選配置。支援以下屬性:
    • source <string> 源資料庫的名稱。可以是 'main'(預設主資料庫)或使用 ATTACH DATABASE 新增的任何其他資料庫。預設值:'main'
    • target <string> 目標資料庫的名稱。可以是 'main'(預設主資料庫)或使用 ATTACH DATABASE 新增的任何其他資料庫。預設值:'main'
    • rate <number> 備份的每個批次中要傳輸的頁數。預設值:100
    • progress <Function> 一個可選的回撥函式,將在每個備份步驟後呼叫。傳遞給此回撥的引數是一個帶有 remainingPagestotalPages 屬性的 <Object>,描述了備份操作的當前進度。
  • 返回:<Promise> 一個 Promise,在完成時解析為備份的總頁數,或在發生錯誤時拒絕。

此方法進行資料庫備份。此方法抽象了 sqlite3_backup_init()sqlite3_backup_step()sqlite3_backup_finish() 函式。

備份的資料庫可以在備份過程中正常使用。來自同一連線——即同一個 <DatabaseSync> 物件——的修改將立即反映在備份中。然而,來自其他連線的修改將導致備份過程重新啟動。

const { backup, DatabaseSync } = require('node:sqlite');

(async () => {
  const sourceDb = new DatabaseSync('source.db');
  const totalPagesTransferred = await backup(sourceDb, 'backup.db', {
    rate: 1, // Copy one page at a time.
    progress: ({ totalPages, remainingPages }) => {
      console.log('Backup in progress', { totalPages, remainingPages });
    },
  });

  console.log('Backup completed', totalPagesTransferred);
})();import { backup, DatabaseSync } from 'node:sqlite';

const sourceDb = new DatabaseSync('source.db');
const totalPagesTransferred = await backup(sourceDb, 'backup.db', {
  rate: 1, // Copy one page at a time.
  progress: ({ totalPages, remainingPages }) => {
    console.log('Backup in progress', { totalPages, remainingPages });
  },
});

console.log('Backup completed', totalPagesTransferred);

sqlite.constants#

一個包含 SQLite 操作常用常量的物件。

SQLite 常量#

以下常量由 sqlite.constants 物件匯出。

衝突解決常量#

以下常量之一可作為傳遞給 database.applyChangeset()onConflict 衝突解決處理程式的引數。另請參閱 SQLite 文件中的傳遞給衝突處理程式的常量

常量 描述
SQLITE_CHANGESET_DATA 在處理 DELETE 或 UPDATE 更改時,如果資料庫中存在具有所需 PRIMARY KEY 欄位的行,但更新修改的一個或多個其他(非主鍵)欄位不包含預期的“之前”值,則會使用此常量呼叫衝突處理程式。
SQLITE_CHANGESET_NOTFOUND 在處理 DELETE 或 UPDATE 更改時,如果資料庫中不存在具有所需 PRIMARY KEY 欄位的行,則會使用此常量呼叫衝突處理程式。
SQLITE_CHANGESET_CONFLICT 在處理 INSERT 更改時,如果操作會導致主鍵值重複,則會使用此常量呼叫衝突處理程式。
SQLITE_CHANGESET_CONSTRAINT 如果啟用了外部索引鍵處理,並且應用變更集導致資料庫處於包含外部索引鍵衝突的狀態,則在提交變更集之前,會使用此常量精確地呼叫一次衝突處理程式。如果衝突處理程式返回 SQLITE_CHANGESET_OMIT,則會提交更改,包括那些導致外部索引鍵約束衝突的更改。或者,如果它返回 SQLITE_CHANGESET_ABORT,則會回滾變更集。
SQLITE_CHANGESET_FOREIGN_KEY 如果在應用更改時發生任何其他約束衝突(即 UNIQUE、CHECK 或 NOT NULL 約束),則會使用此常量呼叫衝突處理程式。

必須從傳遞給 database.applyChangeset()onConflict 衝突解決處理程式返回以下常量之一。另請參閱 SQLite 文件中的從衝突處理程式返回的常量

常量 描述
SQLITE_CHANGESET_OMIT 忽略衝突的更改。
SQLITE_CHANGESET_REPLACE 衝突的更改替換現有值。請注意,此值只能在衝突型別為 SQLITE_CHANGESET_DATASQLITE_CHANGESET_CONFLICT 時返回。
SQLITE_CHANGESET_ABORT 當更改遇到衝突時中止並回滾資料庫。
授權常量#

以下常量與 database.setAuthorizer() 方法一起使用。

授權結果程式碼#

必須從傳遞給 database.setAuthorizer() 的授權回撥函式返回以下常量之一。

常量 描述
SQLITE_OK 允許操作正常進行。
SQLITE_DENY 拒絕操作並導致返回錯誤。
SQLITE_IGNORE 忽略操作並繼續,就像從未請求過一樣。
授權操作程式碼#

以下常量作為第一個引數傳遞給授權回撥函式,以指示正在授權的操作型別。

常量 描述
SQLITE_CREATE_INDEX 建立索引
SQLITE_CREATE_TABLE 建立表
SQLITE_CREATE_TEMP_INDEX 建立臨時索引
SQLITE_CREATE_TEMP_TABLE 建立臨時表
SQLITE_CREATE_TEMP_TRIGGER 建立臨時觸發器
SQLITE_CREATE_TEMP_VIEW 建立臨時檢視
SQLITE_CREATE_TRIGGER 建立觸發器
SQLITE_CREATE_VIEW 建立檢視
SQLITE_DELETE 從表中刪除
SQLITE_DROP_INDEX 刪除索引
SQLITE_DROP_TABLE 刪除表
SQLITE_DROP_TEMP_INDEX 刪除臨時索引
SQLITE_DROP_TEMP_TABLE 刪除臨時表
SQLITE_DROP_TEMP_TRIGGER 刪除臨時觸發器
SQLITE_DROP_TEMP_VIEW 刪除臨時檢視
SQLITE_DROP_TRIGGER 刪除觸發器
SQLITE_DROP_VIEW 刪除檢視
SQLITE_INSERT 插入到表中
SQLITE_PRAGMA 執行 PRAGMA 語句
SQLITE_READ 從表中讀取
SQLITE_SELECT 執行 SELECT 語句
SQLITE_TRANSACTION 開始、提交或回滾事務
SQLITE_UPDATE 更新表
SQLITE_ATTACH 附加資料庫
SQLITE_DETACH 分離資料庫
SQLITE_ALTER_TABLE 修改表
SQLITE_REINDEX 重建索引
SQLITE_ANALYZE 分析資料庫
SQLITE_CREATE_VTABLE 建立虛擬表
SQLITE_DROP_VTABLE 刪除虛擬表
SQLITE_FUNCTION 使用函式
SQLITE_SAVEPOINT 建立、釋放或回滾儲存點
SQLITE_COPY 複製資料(舊版)
SQLITE_RECURSIVE 遞迴查詢