SQLite

Hinzugefügt in: v22.5.0

[Stabil: 1 - Experimentell]

Stabil: 1 Stabilität: 1.1 - Aktive Entwicklung.

Quellcode: lib/sqlite.js

Das Modul node:sqlite erleichtert die Arbeit mit SQLite-Datenbanken. Um darauf zuzugreifen:

ESM

import sqlite from 'node:sqlite'

CJS

const sqlite = require('node:sqlite')

Dieses Modul ist nur unter dem Schema node: verfügbar.

Das folgende Beispiel zeigt die grundlegende Verwendung des Moduls node:sqlite, um eine In-Memory-Datenbank zu öffnen, Daten in die Datenbank zu schreiben und die Daten dann wieder auszulesen.

ESM

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

// Ausführung von SQL-Anweisungen aus Strings.
database.exec(`
  CREATE TABLE data(
    key INTEGER PRIMARY KEY,
    value TEXT
  ) STRICT
`)
// Erstellung einer vorbereiteten Anweisung zum Einfügen von Daten in die Datenbank.
const insert = database.prepare('INSERT INTO data (key, value) VALUES (?, ?)')
// Ausführung der vorbereiteten Anweisung mit gebundenen Werten.
insert.run(1, 'hello')
insert.run(2, 'world')
// Erstellung einer vorbereiteten Anweisung zum Auslesen von Daten aus der Datenbank.
const query = database.prepare('SELECT * FROM data ORDER BY key')
// Ausführung der vorbereiteten Anweisung und Ausgabe des Ergebnissatzes.
console.log(query.all())
// Gibt aus: [ { key: 1, value: 'hello' }, { key: 2, value: 'world' } ]

CJS

'use strict'
const { DatabaseSync } = require('node:sqlite')
const database = new DatabaseSync(':memory:')

// Ausführung von SQL-Anweisungen aus Strings.
database.exec(`
  CREATE TABLE data(
    key INTEGER PRIMARY KEY,
    value TEXT
  ) STRICT
`)
// Erstellung einer vorbereiteten Anweisung zum Einfügen von Daten in die Datenbank.
const insert = database.prepare('INSERT INTO data (key, value) VALUES (?, ?)')
// Ausführung der vorbereiteten Anweisung mit gebundenen Werten.
insert.run(1, 'hello')
insert.run(2, 'world')
// Erstellung einer vorbereiteten Anweisung zum Auslesen von Daten aus der Datenbank.
const query = database.prepare('SELECT * FROM data ORDER BY key')
// Ausführung der vorbereiteten Anweisung und Ausgabe des Ergebnissatzes.
console.log(query.all())
// Gibt aus: [ { key: 1, value: 'hello' }, { key: 2, value: 'world' } ]

Klasse: DatabaseSync

Hinzugefügt in: v22.5.0

Diese Klasse repräsentiert eine einzelne Verbindung zu einer SQLite-Datenbank. Alle von dieser Klasse bereitgestellten APIs werden synchron ausgeführt.

new DatabaseSync(location[, options])

Hinzugefügt in: v22.5.0

• location <string> Der Speicherort der Datenbank. Eine SQLite-Datenbank kann in einer Datei oder vollständig im Speicher gespeichert werden. Um eine dateibasierte Datenbank zu verwenden, sollte der Speicherort ein Dateipfad sein. Um eine In-Memory-Datenbank zu verwenden, sollte der Speicherort der spezielle Name ':memory:' sein.
• options <Object> Konfigurationsoptionen für die Datenbankverbindung. Die folgenden Optionen werden unterstützt:
  • open <boolean> Wenn true, wird die Datenbank durch den Konstruktor geöffnet. Wenn dieser Wert false ist, muss die Datenbank über die Methode open() geöffnet werden. Standard: true.
  • readOnly <boolean> Wenn true, wird die Datenbank im schreibgeschützten Modus geöffnet. Wenn die Datenbank nicht existiert, schlägt das Öffnen fehl. Standard: false.
  • enableForeignKeyConstraints <boolean> Wenn true, werden Fremdschlüsselbeschränkungen aktiviert. Dies wird empfohlen, kann aber aus Gründen der Kompatibilität mit älteren Datenbankschemata deaktiviert werden. Die Durchsetzung von Fremdschlüsselbeschränkungen kann nach dem Öffnen der Datenbank mit PRAGMA foreign_keys aktiviert und deaktiviert werden. Standard: true.
  • enableDoubleQuotedStringLiterals <boolean> Wenn true, akzeptiert SQLite doppelt-geklammerte Stringliterale. Dies wird nicht empfohlen, kann aber aus Gründen der Kompatibilität mit älteren Datenbankschemata aktiviert werden. Standard: false.
  • allowExtension <boolean> Wenn true, sind die SQL-Funktion loadExtension und die Methode loadExtension() aktiviert. Sie können enableLoadExtension(false) später aufrufen, um diese Funktion zu deaktivieren. Standard: false.

Konstruiert eine neue DatabaseSync-Instanz.

database.close()

Hinzugefügt in: v22.5.0

Schließt die Datenbankverbindung. Eine Ausnahme wird ausgelöst, wenn die Datenbank nicht geöffnet ist. Diese Methode ist ein Wrapper um sqlite3_close_v2().

database.loadExtension(path)

Hinzugefügt in: v23.5.0

• path <string> Der Pfad zur zu ladenden Shared Library.

Lädt eine Shared Library in die Datenbankverbindung. Diese Methode ist ein Wrapper um sqlite3_load_extension(). Es ist erforderlich, die Option allowExtension beim Erstellen der DatabaseSync-Instanz zu aktivieren.

database.enableLoadExtension(allow)

Hinzugefügt in: v23.5.0

• allow <boolean> Gibt an, ob das Laden von Erweiterungen zulässig ist.

Aktiviert oder deaktiviert die SQL-Funktion loadExtension und die Methode loadExtension(). Wenn allowExtension beim Erstellen false ist, können Sie das Laden von Erweiterungen aus Sicherheitsgründen nicht aktivieren.

database.exec(sql)

Hinzugefügt in: v22.5.0

• sql <string> Eine auszuführende SQL-Zeichenfolge.

Diese Methode ermöglicht die Ausführung einer oder mehrerer SQL-Anweisungen, ohne Ergebnisse zurückzugeben. Diese Methode ist nützlich, wenn SQL-Anweisungen aus einer Datei gelesen werden. Diese Methode ist ein Wrapper um sqlite3_exec().

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

Hinzugefügt in: v23.5.0

• name <string> Der Name der zu erstellenden SQLite-Funktion.

• options <Object> Optionale Konfigurationseinstellungen für die Funktion. Die folgenden Eigenschaften werden unterstützt:

  • deterministic <boolean> Wenn true, wird das Flag SQLITE_DETERMINISTIC für die erstellte Funktion gesetzt. Standard: false.
  • directOnly <boolean> Wenn true, wird das Flag SQLITE_DIRECTONLY für die erstellte Funktion gesetzt. Standard: false.
  • useBigIntArguments <boolean> Wenn true, werden ganzzahlige Argumente für function in BigInts konvertiert. Wenn false, werden ganzzahlige Argumente als JavaScript-Zahlen übergeben. Standard: false.
  • varargs <boolean> Wenn true, kann function eine variable Anzahl von Argumenten akzeptieren. Wenn false, muss function mit genau function.length Argumenten aufgerufen werden. Standard: false.

• function <Function> Die JavaScript-Funktion, die aufgerufen wird, wenn die SQLite-Funktion aufgerufen wird.

Diese Methode wird verwendet, um benutzerdefinierte SQLite-Funktionen zu erstellen. Diese Methode ist ein Wrapper um sqlite3_create_function_v2().

database.open()

Hinzugefügt in: v22.5.0

Öffnet die Datenbank, die im Argument location des Konstruktors DatabaseSync angegeben ist. Diese Methode sollte nur verwendet werden, wenn die Datenbank nicht über den Konstruktor geöffnet wird. Es wird eine Ausnahme ausgelöst, wenn die Datenbank bereits geöffnet ist.

database.prepare(sql)

Hinzugefügt in: v22.5.0

• sql <string> Eine SQL-Zeichenkette, die zu einer vorbereiteten Anweisung kompiliert werden soll.
• Gibt zurück: <StatementSync> Die vorbereitete Anweisung.

Kompiliert eine SQL-Anweisung in eine vorbereitete Anweisung. Diese Methode ist ein Wrapper um sqlite3_prepare_v2().

database.createSession([options])

Hinzugefügt in: v23.3.0

• options <Object> Die Konfigurationsoptionen für die Sitzung.

  • table <string> Eine bestimmte Tabelle, für die Änderungen verfolgt werden sollen. Standardmäßig werden Änderungen an allen Tabellen verfolgt.
  • db <string> Name der zu verfolgenden Datenbank. Dies ist nützlich, wenn mehrere Datenbanken mit ATTACH DATABASE hinzugefügt wurden. Standard: 'main'.

• Gibt zurück: <Session> Ein Sitzungshandle.

Erstellt und hängt eine Sitzung an die Datenbank an. Diese Methode ist ein Wrapper um sqlite3session_create() und sqlite3session_attach().

database.applyChangeset(changeset[, options])

Hinzugefügt in: v23.3.0

• changeset <Uint8Array> Ein binäres Changeset oder Patchset.

• options <Object> Die Konfigurationsoptionen für die Art und Weise, wie die Änderungen angewendet werden.

  • filter <Function> Überspringt Änderungen, die, wenn der Name der Zieltabelle an diese Funktion übergeben wird, einen Wahrheitwert zurückgeben. Standardmäßig werden alle Änderungen versucht.
  • onConflict <number> Bestimmt, wie Konflikte behandelt werden. Standard: SQLITE_CHANGESET_ABORT.
  • SQLITE_CHANGESET_OMIT: Konfliktierende Änderungen werden weggelassen.
  • SQLITE_CHANGESET_REPLACE: Konfliktierende Änderungen ersetzen vorhandene Werte.
  • SQLITE_CHANGESET_ABORT: Abbruch bei Konflikt und Zurückrollen der Datenbank.

• Gibt zurück: <boolean> Ob das Changeset erfolgreich angewendet wurde, ohne abgebrochen zu werden.

Es wird eine Ausnahme ausgelöst, wenn die Datenbank nicht geöffnet ist. Diese Methode ist ein Wrapper um 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)
// Nachdem das Changeset angewendet wurde, enthält targetDb die gleichen Daten wie sourceDb.

Klasse: Session

Hinzugefügt in: v23.3.0

session.changeset()

Hinzugefügt in: v23.3.0

• Gibt zurück: <Uint8Array> Binäres Changeset, das auf andere Datenbanken angewendet werden kann.

Ruft ein Changeset ab, das alle Änderungen seit Erstellung des Changesets enthält. Kann mehrmals aufgerufen werden. Eine Ausnahme wird ausgelöst, wenn die Datenbank oder die Sitzung nicht geöffnet ist. Diese Methode ist ein Wrapper um sqlite3session_changeset().

session.patchset()

Hinzugefügt in: v23.3.0

• Gibt zurück: <Uint8Array> Binäres Patchset, das auf andere Datenbanken angewendet werden kann.

Ähnlich wie die obige Methode, erzeugt aber ein kompakteres Patchset. Siehe Changesets und Patchsets in der Dokumentation von SQLite. Eine Ausnahme wird ausgelöst, wenn die Datenbank oder die Sitzung nicht geöffnet ist. Diese Methode ist ein Wrapper um sqlite3session_patchset().

session.close().

Schließt die Sitzung. Eine Ausnahme wird ausgelöst, wenn die Datenbank oder die Sitzung nicht geöffnet ist. Diese Methode ist ein Wrapper um sqlite3session_delete().

Klasse: StatementSync

Hinzugefügt in: v22.5.0

Diese Klasse repräsentiert eine einzelne vorbereitete Anweisung. Diese Klasse kann nicht über ihren Konstruktor instanziiert werden. Stattdessen werden Instanzen über die Methode database.prepare() erstellt. Alle von dieser Klasse bereitgestellten APIs werden synchron ausgeführt.

Eine vorbereitete Anweisung ist eine effiziente binäre Darstellung des SQL, das zu ihrer Erstellung verwendet wurde. Vorbereitete Anweisungen sind parametrisierbar und können mehrfach mit verschiedenen gebundenen Werten aufgerufen werden. Parameter bieten auch Schutz vor SQL-Injection-Angriffen. Aus diesen Gründen werden vorbereitete Anweisungen gegenüber handgefertigten SQL-Strings bevorzugt, wenn Benutzereingaben verarbeitet werden.

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

Hinzugefügt in: v22.5.0

• namedParameters <Object> Ein optionales Objekt, das zum Binden von benannten Parametern verwendet wird. Die Schlüssel dieses Objekts werden verwendet, um die Zuordnung zu konfigurieren.
• ...anonymousParameters <null> | <number> | <bigint> | <string> | <Buffer> | <Uint8Array> Null oder mehr Werte, die an anonyme Parameter gebunden werden sollen.
• Gibt zurück: <Array> Ein Array von Objekten. Jedes Objekt entspricht einer Zeile, die durch die Ausführung der vorbereiteten Anweisung zurückgegeben wird. Die Schlüssel und Werte jedes Objekts entsprechen den Spaltennamen und -werten der Zeile.

Diese Methode führt eine vorbereitete Anweisung aus und gibt alle Ergebnisse als Array von Objekten zurück. Wenn die vorbereitete Anweisung keine Ergebnisse zurückgibt, gibt diese Methode ein leeres Array zurück. Die Parameter der vorbereiteten Anweisung werden mit den Werten in namedParameters und anonymousParameters gebunden.

statement.expandedSQL

Hinzugefügt in: v22.5.0

• <string> Der Quell-SQL-Code, der erweitert wurde, um Parameterwerte einzuschließen.

Der Quell-SQL-Text der vorbereiteten Anweisung, wobei die Parameterplatzhalter durch die Werte ersetzt wurden, die bei der letzten Ausführung dieser vorbereiteten Anweisung verwendet wurden. Diese Eigenschaft ist ein Wrapper um sqlite3_expanded_sql().

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

Hinzugefügt in: v22.5.0

• namedParameters <Object> Ein optionales Objekt, das verwendet wird, um benannte Parameter zu binden. Die Schlüssel dieses Objekts werden verwendet, um die Zuordnung zu konfigurieren.
• ...anonymousParameters <null> | <number> | <bigint> | <string> | <Buffer> | <Uint8Array> Null oder mehr Werte, die an anonyme Parameter gebunden werden sollen.
• Gibt zurück: <Object> | <undefined> Ein Objekt, das der ersten Zeile entspricht, die durch Ausführen der vorbereiteten Anweisung zurückgegeben wird. Die Schlüssel und Werte des Objekts entsprechen den Spaltennamen und -werten der Zeile. Wenn keine Zeilen aus der Datenbank zurückgegeben wurden, gibt diese Methode undefined zurück.

Diese Methode führt eine vorbereitete Anweisung aus und gibt das erste Ergebnis als Objekt zurück. Wenn die vorbereitete Anweisung keine Ergebnisse zurückgibt, gibt diese Methode undefined zurück. Die vorbereiteten Anweisungs-Parameter werden gebunden, indem die Werte in namedParameters und anonymousParameters verwendet werden.

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

Hinzugefügt in: v23.4.0

• namedParameters <Object> Ein optionales Objekt, das verwendet wird, um benannte Parameter zu binden. Die Schlüssel dieses Objekts werden verwendet, um die Zuordnung zu konfigurieren.
• ...anonymousParameters <null> | <number> | <bigint> | <string> | <Buffer> | <Uint8Array> Null oder mehr Werte, die an anonyme Parameter gebunden werden sollen.
• Gibt zurück: <Iterator> Ein iterierbarer Iterator von Objekten. Jedes Objekt entspricht einer Zeile, die durch Ausführen der vorbereiteten Anweisung zurückgegeben wird. Die Schlüssel und Werte jedes Objekts entsprechen den Spaltennamen und -werten der Zeile.

Diese Methode führt eine vorbereitete Anweisung aus und gibt einen Iterator von Objekten zurück. Wenn die vorbereitete Anweisung keine Ergebnisse zurückgibt, gibt diese Methode einen leeren Iterator zurück. Die vorbereiteten Anweisungs-Parameter werden gebunden, indem die Werte in namedParameters und anonymousParameters verwendet werden.

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

Hinzugefügt in: v22.5.0

• namedParameters <Object> Ein optionales Objekt, das zum Binden benannter Parameter verwendet wird. Die Schlüssel dieses Objekts werden zur Konfiguration der Zuordnung verwendet.
• ...anonymousParameters <null> | <number> | <bigint> | <string> | <Buffer> | <Uint8Array> Null oder mehr Werte zum Binden an anonyme Parameter.
• Gibt zurück: <Object>
  • changes: <number> | <bigint> Die Anzahl der Zeilen, die durch die zuletzt abgeschlossene INSERT-, UPDATE- oder DELETE-Anweisung geändert, eingefügt oder gelöscht wurden. Dieses Feld ist entweder eine Zahl oder ein BigInt, abhängig von der Konfiguration der vorbereiteten Anweisung. Diese Eigenschaft ist das Ergebnis von sqlite3_changes64().
  • lastInsertRowid: <number> | <bigint> Die zuletzt eingefügte Zeilen-ID. Dieses Feld ist entweder eine Zahl oder ein BigInt, abhängig von der Konfiguration der vorbereiteten Anweisung. Diese Eigenschaft ist das Ergebnis von sqlite3_last_insert_rowid().

Diese Methode führt eine vorbereitete Anweisung aus und gibt ein Objekt zurück, das die resultierenden Änderungen zusammenfasst. Die Parameter der vorbereiteten Anweisung werden mit den Werten in namedParameters und anonymousParameters gebunden.

statement.setAllowBareNamedParameters(enabled)

Hinzugefügt in: v22.5.0

• enabled <boolean> Aktiviert oder deaktiviert die Unterstützung für das Binden von benannten Parametern ohne das Präfixzeichen.

Die Namen von SQLite-Parametern beginnen mit einem Präfixzeichen. Standardmäßig erfordert node:sqlite, dass dieses Präfixzeichen beim Binden von Parametern vorhanden ist. Mit Ausnahme des Dollarzeichens erfordern diese Präfixzeichen jedoch auch zusätzliche Anführungszeichen, wenn sie in Objektschlüsseln verwendet werden.

Um die Ergonomie zu verbessern, kann diese Methode verwendet werden, um auch ungeschmückte benannte Parameter zu erlauben, die das Präfixzeichen im JavaScript-Code nicht erfordern. Es gibt mehrere Einschränkungen, die beim Aktivieren von ungeschmückten benannten Parametern zu beachten sind:

• Das Präfixzeichen ist weiterhin in SQL erforderlich.
• Das Präfixzeichen ist in JavaScript weiterhin erlaubt. Tatsächlich haben Präfixnamen eine etwas bessere Bindungsleistung.
• Die Verwendung von mehrdeutigen benannten Parametern, wie z. B. $k und @k, in derselben vorbereiteten Anweisung führt zu einer Ausnahme, da nicht ermittelt werden kann, wie ein ungeschmückter Name gebunden werden soll.

statement.setReadBigInts(enabled)

Hinzugefügt in: v22.5.0

• enabled <boolean> Aktiviert oder deaktiviert die Verwendung von BigInts beim Lesen von INTEGER-Feldern aus der Datenbank.

Beim Lesen aus der Datenbank werden SQLite INTEGERs standardmäßig auf JavaScript-Zahlen abgebildet. SQLite INTEGERs können jedoch Werte speichern, die größer sind, als JavaScript-Zahlen darstellen können. In solchen Fällen kann diese Methode verwendet werden, um INTEGER-Daten mit JavaScript BigInts zu lesen. Diese Methode hat keine Auswirkungen auf Datenbank-Schreiboperationen, bei denen Zahlen und BigInts jederzeit unterstützt werden.

statement.sourceSQL

Hinzugefügt in: v22.5.0

• <string> Das Quell-SQL, das zum Erstellen dieser vorbereiteten Anweisung verwendet wurde.

Der Quell-SQL-Text der vorbereiteten Anweisung. Diese Eigenschaft ist ein Wrapper um sqlite3_sql().

Typkonvertierung zwischen JavaScript und SQLite

Wenn Node.js in SQLite schreibt oder aus SQLite liest, ist es notwendig, zwischen JavaScript-Datentypen und den Datentypen von SQLite zu konvertieren. Da JavaScript mehr Datentypen unterstützt als SQLite, wird nur eine Teilmenge der JavaScript-Typen unterstützt. Der Versuch, einen nicht unterstützten Datentyp in SQLite zu schreiben, führt zu einer Ausnahme.

SQLite	JavaScript
NULL	<null>
INTEGER	<number> oder <bigint>
REAL	<number>
TEXT	<string>
BLOB	<Uint8Array>

sqlite.constants

Hinzugefügt in: v23.5.0

• <Object>

Ein Objekt, das häufig verwendete Konstanten für SQLite-Operationen enthält.

SQLite-Konstanten

Die folgenden Konstanten werden vom sqlite.constants-Objekt exportiert.

Konstanten zur Konfliktlösung

Die folgenden Konstanten sind für die Verwendung mit database.applyChangeset() gedacht.

Konstante	Beschreibung
SQLITE_CHANGESET_OMIT	Konfliktierende Änderungen werden ausgelassen.
SQLITE_CHANGESET_REPLACE	Konfliktierende Änderungen ersetzen bestehende Werte.
SQLITE_CHANGESET_ABORT	Abbruch, wenn eine Änderung auf einen Konflikt stößt und die Datenbank zurückgesetzt wird.