SQLite

Added in: v22.5.0

[Stable: 1 - Experimental]

ソースコード: lib/sqlite.js

node:sqlite モジュールは、SQLite データベースの操作を容易にします。アクセスするには:

ESMCJS

import sqlite from 'node:sqlite';

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

このモジュールは、node: スキームでのみ利用可能です。

次の例は、node:sqlite モジュールの基本的な使用方法を示しています。インメモリデータベースを開き、データベースにデータを書き込み、データを読み返します。

ESMCJS

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

// 文字列から SQL ステートメントを実行します。
database.exec(`
  CREATE TABLE data(
    key INTEGER PRIMARY KEY,
    value TEXT
  ) STRICT
`);
// データベースにデータを挿入するためのプリペアドステートメントを作成します。
const insert = database.prepare('INSERT INTO data (key, value) VALUES (?, ?)');
// バインドされた値でプリペアドステートメントを実行します。
insert.run(1, 'hello');
insert.run(2, 'world');
// データベースからデータを読み取るためのプリペアドステートメントを作成します。
const query = database.prepare('SELECT * FROM data ORDER BY key');
// プリペアドステートメントを実行し、結果セットをログに記録します。
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:');

// 文字列から SQL ステートメントを実行します。
database.exec(`
  CREATE TABLE data(
    key INTEGER PRIMARY KEY,
    value TEXT
  ) STRICT
`);
// データベースにデータを挿入するためのプリペアドステートメントを作成します。
const insert = database.prepare('INSERT INTO data (key, value) VALUES (?, ?)');
// バインドされた値でプリペアドステートメントを実行します。
insert.run(1, 'hello');
insert.run(2, 'world');
// データベースからデータを読み取るためのプリペアドステートメントを作成します。
const query = database.prepare('SELECT * FROM data ORDER BY key');
// プリペアドステートメントを実行し、結果セットをログに記録します。
console.log(query.all());
// Prints: [ { key: 1, value: 'hello' }, { key: 2, value: 'world' } ]

クラス: `DatabaseSync`

Added in: v22.5.0

このクラスは、SQLiteデータベースへの単一の接続を表します。このクラスによって公開されるすべてのAPIは、同期的に実行されます。

`new DatabaseSync(location[, options])`

Added in: v22.5.0

location <string> データベースの場所。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。

新しいDatabaseSyncインスタンスを構築します。

`database.close()`

Added in: v22.5.0

データベース接続を閉じます。データベースが開いていない場合、例外がスローされます。このメソッドは、sqlite3_close_v2() のラッパーです。

`database.loadExtension(path)`

Added in: v23.5.0

path <string> ロードする共有ライブラリへのパス。

共有ライブラリをデータベース接続にロードします。このメソッドは、sqlite3_load_extension() のラッパーです。DatabaseSync インスタンスを構築するときに、allowExtension オプションを有効にする必要があります。

`database.enableLoadExtension(allow)`

Added in: v23.5.0

allow <boolean> 拡張機能のロードを許可するかどうか。

loadExtension SQL 関数と loadExtension() メソッドを有効または無効にします。構築時に allowExtension が false の場合、セキュリティ上の理由から拡張機能のロードを有効にすることはできません。

`database.exec(sql)`

Added in: v22.5.0

sql <string> 実行する SQL 文字列。

このメソッドを使用すると、結果を返さずに 1 つ以上の SQL ステートメントを実行できます。このメソッドは、ファイルから読み取った SQL ステートメントを実行する場合に役立ちます。このメソッドは、sqlite3_exec() のラッパーです。

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

Added in: v23.5.0

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> true の場合、function は可変数の引数を受け入れることができます。 false の場合、function は正確に function.length 引数で呼び出す必要があります。デフォルト: false。
function <Function> SQLite 関数が呼び出されたときに呼び出す JavaScript 関数。

このメソッドは、SQLite ユーザー定義関数を作成するために使用されます。このメソッドは、sqlite3_create_function_v2() のラッパーです。

`database.open()`

追加: v22.5.0

DatabaseSyncコンストラクターのlocation引数で指定されたデータベースを開きます。このメソッドは、データベースがコンストラクター経由で開かれていない場合にのみ使用する必要があります。データベースがすでに開いている場合、例外がスローされます。

`database.prepare(sql)`

追加: v22.5.0

sql <string> プリペアドステートメントにコンパイルするSQL文字列。
戻り値: <StatementSync> プリペアドステートメント。

SQLステートメントをプリペアドステートメントにコンパイルします。このメソッドは、sqlite3_prepare_v2()のラッパーです。

`database.createSession([options])`

追加: v23.3.0

options <Object> セッションの構成オプション。
- table <string> 変更を追跡する特定のテーブル。デフォルトでは、すべてのテーブルへの変更が追跡されます。
- db <string> 追跡するデータベースの名前。これは、ATTACH DATABASEを使用して複数のデータベースが追加された場合に役立ちます。デフォルト: 'main'。
戻り値: <Session> セッションハンドル。

データベースにセッションを作成してアタッチします。このメソッドは、sqlite3session_create()とsqlite3session_attach()のラッパーです。

`database.applyChangeset(changeset[, options])`

追加: v23.3.0

changeset <Uint8Array> バイナリのチェンジセットまたはパッチセット。
options <Object> 変更の適用方法に関する構成オプション。
- filter <Function> 対象のテーブル名がこの関数に提供されたときに、真の値を返す変更をスキップします。デフォルトでは、すべての変更が試行されます。
- onConflict <number> 競合の処理方法を決定します。デフォルト: SQLITE_CHANGESET_ABORT。
- SQLITE_CHANGESET_OMIT: 競合する変更は省略されます。
- SQLITE_CHANGESET_REPLACE: 競合する変更は既存の値を置き換えます。
- 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.
// これでチェンジセットが適用されたので、targetDbにはsourceDbと同じデータが含まれています。

Class: `Session`

Added in: v23.3.0

`session.changeset()`

Added in: v23.3.0

Returns: <Uint8Array> 他のデータベースに適用できるバイナリチェンジセット。

チェンジセットが作成されてからのすべての変更を含むチェンジセットを取得します。複数回呼び出すことができます。データベースまたはセッションが開かれていない場合、例外がスローされます。このメソッドは、sqlite3session_changeset() のラッパーです。

`session.patchset()`

Added in: v23.3.0

Returns: <Uint8Array> 他のデータベースに適用できるバイナリパッチセット。

上記のメソッドと同様ですが、よりコンパクトなパッチセットを生成します。SQLite のドキュメントのチェンジセットとパッチセットを参照してください。データベースまたはセッションが開かれていない場合、例外がスローされます。このメソッドは、sqlite3session_patchset() のラッパーです。

`session.close()`

セッションを閉じます。データベースまたはセッションが開かれていない場合、例外がスローされます。このメソッドは、sqlite3session_delete() のラッパーです。

Class: `StatementSync`

Added in: v22.5.0

このクラスは、単一のプリペアドステートメントを表します。このクラスは、コンストラクタを介してインスタンス化することはできません。代わりに、インスタンスは database.prepare() メソッドを介して作成されます。このクラスによって公開されるすべての API は、同期的に実行されます。

プリペアドステートメントは、それを作成するために使用される SQL の効率的なバイナリ表現です。プリペアドステートメントはパラメータ化可能であり、異なるバインド値で複数回呼び出すことができます。パラメータは、SQLインジェクション攻撃に対する保護も提供します。これらの理由から、ユーザー入力を処理する際には、手作りの SQL 文字列よりもプリペアドステートメントが推奨されます。

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

Added in: v22.5.0

namedParameters <Object> 名前付きパラメーターをバインドするために使用されるオプションのオブジェクト。このオブジェクトのキーは、マッピングの構成に使用されます。
...anonymousParameters <null> | <number> | <bigint> | <string> | <Buffer> | <Uint8Array> 匿名パラメーターにバインドするゼロ個以上の値。
戻り値: <Array> オブジェクトの配列。各オブジェクトは、プリペアドステートメントを実行して返された行に対応します。各オブジェクトのキーと値は、行の列名と値に対応します。

このメソッドは、プリペアドステートメントを実行し、すべての結果をオブジェクトの配列として返します。プリペアドステートメントが結果を返さない場合、このメソッドは空の配列を返します。プリペアドステートメントのパラメーターは、namedParametersとanonymousParametersの値を使用してバインドされます。

`statement.expandedSQL`

Added in: v22.5.0

<string> パラメーター値を含むように拡張されたソースSQL。

プリペアドステートメントのソースSQLテキスト。パラメータープレースホルダーは、このプリペアドステートメントの最新の実行時に使用された値に置き換えられます。このプロパティは、sqlite3_expanded_sql()のラッパーです。

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

Added in: v22.5.0

namedParameters <Object> 名前付きパラメータをバインドするために使用されるオプションのオブジェクト。このオブジェクトのキーは、マッピングの構成に使用されます。
...anonymousParameters <null> | <number> | <bigint> | <string> | <Buffer> | <Uint8Array> 匿名パラメータにバインドするゼロ個以上の値。
戻り値: <Object> | <undefined> プリペアドステートメントを実行して返された最初の行に対応するオブジェクト。オブジェクトのキーと値は、行の列名と値に対応します。データベースから行が返されなかった場合、このメソッドは undefined を返します。

このメソッドは、プリペアドステートメントを実行し、最初の結果をオブジェクトとして返します。プリペアドステートメントが結果を返さない場合、このメソッドは undefined を返します。プリペアドステートメントのパラメータは、namedParameters と anonymousParameters の値を使用してバインドされます。

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

Added in: v23.4.0

namedParameters <Object> 名前付きパラメータをバインドするために使用されるオプションのオブジェクト。このオブジェクトのキーは、マッピングの構成に使用されます。
...anonymousParameters <null> | <number> | <bigint> | <string> | <Buffer> | <Uint8Array> 匿名パラメータにバインドするゼロ個以上の値。
戻り値: <Iterator> オブジェクトの反復可能イテレータ。各オブジェクトは、プリペアドステートメントを実行して返された行に対応します。各オブジェクトのキーと値は、行の列名と値に対応します。

このメソッドは、プリペアドステートメントを実行し、オブジェクトのイテレータを返します。プリペアドステートメントが結果を返さない場合、このメソッドは空のイテレータを返します。プリペアドステートメントのパラメータは、namedParameters と anonymousParameters の値を使用してバインドされます。

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

Added in: v22.5.0

namedParameters <Object> 名前付きパラメータをバインドするために使用されるオプションのオブジェクト。このオブジェクトのキーは、マッピングを構成するために使用されます。
...anonymousParameters <null> | <number> | <bigint> | <string> | <Buffer> | <Uint8Array> 匿名パラメータにバインドするゼロ個以上の値。
戻り値: <Object>
- changes: <number> | <bigint> 最近完了したINSERT、UPDATE、またはDELETEステートメントによって変更、挿入、または削除された行の数。このフィールドは、準備されたステートメントの構成に応じて、数値またはBigIntのいずれかです。このプロパティは、sqlite3_changes64()の結果です。
- lastInsertRowid: <number> | <bigint> 最近挿入された rowid。このフィールドは、準備されたステートメントの構成に応じて、数値またはBigIntのいずれかです。このプロパティは、sqlite3_last_insert_rowid()の結果です。

このメソッドは、準備されたステートメントを実行し、結果として生じた変更をまとめたオブジェクトを返します。準備されたステートメントパラメータは、namedParametersとanonymousParametersの値を使用してバインドされます。

`statement.setAllowBareNamedParameters(enabled)`

追加: v22.5.0

enabled <boolean> 接頭辞文字なしで名前付きパラメータのバインドのサポートを有効または無効にします。

SQLiteパラメータの名前は接頭辞文字で始まります。デフォルトでは、node:sqliteはパラメータをバインドするときにこの接頭辞文字が存在することを要求します。ただし、ドル記号を除いて、これらの接頭辞文字はオブジェクトキーで使用する場合にも追加の引用符が必要です。

人間工学を向上させるために、このメソッドを使用して、JavaScriptコードで接頭辞文字を必要としない、生の（bare）名前付きパラメータも許可できます。生の（bare）名前付きパラメータを有効にする場合は、注意すべき点がいくつかあります。

接頭辞文字はSQLで依然として必要です。
接頭辞文字はJavaScriptでも依然として許可されます。実際、接頭辞付きの名前の方がバインドのパフォーマンスがわずかに向上します。
同じプリペアドステートメントで$kや@kのようなあいまいな名前付きパラメータを使用すると、生の（bare）名前をどのようにバインドするかを判別できないため、例外が発生します。

`statement.setReadBigInts(enabled)`

追加: v22.5.0

enabled <boolean> データベースからINTEGERフィールドを読み取るときにBigIntの使用を有効または無効にします。

データベースからの読み取り時、SQLiteのINTEGERはデフォルトでJavaScriptの数値にマッピングされます。ただし、SQLiteのINTEGERはJavaScriptの数値が表現できるよりも大きな値を格納できます。このような場合、このメソッドを使用して、JavaScriptのBigIntを使用してINTEGERデータを読み取ることができます。このメソッドは、数値とBigIntの両方が常にサポートされているデータベースの書き込み操作には影響を与えません。

`statement.sourceSQL`

追加: v22.5.0

<string> このプリペアドステートメントの作成に使用されたソースSQL。

プリペアドステートメントのソースSQLテキスト。このプロパティは、sqlite3_sql()のラッパーです。

JavaScriptとSQLite間の型変換

Node.jsがSQLiteに書き込みまたは読み込みを行う場合、JavaScriptのデータ型とSQLiteのデータ型の間で変換を行う必要があります。JavaScriptはSQLiteよりも多くのデータ型をサポートしているため、JavaScript型のサブセットのみがサポートされています。サポートされていないデータ型をSQLiteに書き込もうとすると、例外が発生します。

SQLite	JavaScript
`NULL`	<null>
`INTEGER`	<number> または <bigint>
`REAL`	<number>
`TEXT`	<string>
`BLOB`	<Uint8Array>

`sqlite.constants`

追加: v23.5.0

<Object>

SQLite操作で一般的に使用される定数を含むオブジェクト。

SQLite定数

次の定数は、sqlite.constantsオブジェクトによってエクスポートされます。

競合解決定数

次の定数は、database.applyChangeset()で使用することを目的としています。

定数	説明
`SQLITE_CHANGESET_OMIT`	競合する変更は省略されます。
`SQLITE_CHANGESET_REPLACE`	競合する変更は既存の値を置き換えます。
`SQLITE_CHANGESET_ABORT`	変更が競合に遭遇し、データベースをロールバックしたときに中止します。

SQLite ​

クラス: DatabaseSync ​

new DatabaseSync(location[, options]) ​

database.close() ​

database.loadExtension(path) ​

database.enableLoadExtension(allow) ​

database.exec(sql) ​

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

database.open() ​

database.prepare(sql) ​

database.createSession([options]) ​

database.applyChangeset(changeset[, options]) ​

Class: Session ​

session.changeset() ​

session.patchset() ​

session.close() ​

Class: StatementSync ​

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

statement.expandedSQL ​

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

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

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

statement.setAllowBareNamedParameters(enabled) ​

statement.setReadBigInts(enabled) ​

statement.sourceSQL ​

JavaScriptとSQLite間の型変換 ​

sqlite.constants ​

SQLite定数 ​

競合解決定数 ​

SQLite

クラス: `DatabaseSync`

`new DatabaseSync(location[, options])`

`database.close()`

`database.loadExtension(path)`

`database.enableLoadExtension(allow)`

`database.exec(sql)`

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

`database.open()`

`database.prepare(sql)`

`database.createSession([options])`

`database.applyChangeset(changeset[, options])`

Class: `Session`

`session.changeset()`

`session.patchset()`

`session.close()`

Class: `StatementSync`

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

`statement.expandedSQL`

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

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

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

`statement.setAllowBareNamedParameters(enabled)`

`statement.setReadBigInts(enabled)`

`statement.sourceSQL`

JavaScriptとSQLite間の型変換

`sqlite.constants`

SQLite定数

競合解決定数