SQLite

追加バージョン: v22.5.0

[安定版: 1 - 試験版]

ソースコード: 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())
// 出力: [ { 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())
// 出力: [ { key: 1, value: 'hello' }, { key: 2, value: 'world' } ]

クラス: `DatabaseSync`

追加バージョン: v22.5.0

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

`new DatabaseSync(location[, options])`

追加バージョン: 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()`

追加日時: v22.5.0

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

`database.loadExtension(path)`

追加日時: v23.5.0

path <string> 読み込む共有ライブラリのパス。

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

`database.enableLoadExtension(allow)`

追加日時: v23.5.0

allow <boolean> 拡張機能の読み込みを許可するかどうか。

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

`database.exec(sql)`

追加日時: v22.5.0

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

このメソッドは、結果を返さずに 1 つ以上の SQL 文を実行できます。ファイルから読み取った SQL 文を実行する場合に便利です。このメソッドはsqlite3_exec()のラッパーです。

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

追加日時: 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.

Class: `Session`

追加: v23.3.0

`session.changeset()`

追加: v23.3.0

戻り値: <Uint8Array> 他のデータベースに適用できるバイナリ変更セット。

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

`session.patchset()`

追加: v23.3.0

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

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

`session.close()`.

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

Class: `StatementSync`

追加: v22.5.0

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

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

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

追加日時: v22.5.0

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

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

`statement.expandedSQL`

追加日時: v22.5.0

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

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

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

追加バージョン: v22.5.0

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

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

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

追加バージョン: v23.4.0

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

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

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

追加バージョン: v22.5.0

namedParameters <Object> 名前付きパラメータをバインドするために使用するオプションのオブジェクト。このオブジェクトのキーはマッピングの設定に使用されます。
...anonymousParameters <null> | <number> | <bigint> | <string> | <Buffer> | <Uint8Array> 匿名パラメータにバインドする 0 個以上の値。
戻り値: <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 コードでプレフィックス文字を必要としない、ベアナムドパラメータも許可できます。ベアナムドパラメータを有効にする際には、いくつかの注意点があります。

プレフィックス文字は SQL でも必要です。
プレフィックス文字は JavaScript でも許可されます。実際、プレフィックス付きの名前の方がバインディングのパフォーマンスがわずかに向上します。
$kと@kなど、あいまいな名前付きパラメータを同じプリペアドステートメントで使用すると、ベアナムをどのようにバインドするかを判断できないため、例外が発生します。

`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 定数

衝突解決定数