SQLite

Ajouté dans : v22.5.0

[Stable : 1 - Expérimental]

Stable : 1 Stabilité : 1.1 - Développement actif.

Code source : lib/sqlite.js

Le module node:sqlite facilite l’utilisation des bases de données SQLite. Pour y accéder :

ESM

import sqlite from 'node:sqlite'

CJS

const sqlite = require('node:sqlite')

Ce module est uniquement disponible sous le schéma node:.

L’exemple suivant illustre l’utilisation de base du module node:sqlite pour ouvrir une base de données en mémoire, écrire des données dans la base de données, puis relire les données.

ESM

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

// Exécuter des instructions SQL à partir de chaînes de caractères.
database.exec(`
  CREATE TABLE data(
    key INTEGER PRIMARY KEY,
    value TEXT
  ) STRICT
`)
// Créer une instruction préparée pour insérer des données dans la base de données.
const insert = database.prepare('INSERT INTO data (key, value) VALUES (?, ?)')
// Exécuter l’instruction préparée avec des valeurs liées.
insert.run(1, 'hello')
insert.run(2, 'world')
// Créer une instruction préparée pour lire les données de la base de données.
const query = database.prepare('SELECT * FROM data ORDER BY key')
// Exécuter l’instruction préparée et journaliser le jeu de résultats.
console.log(query.all())
// Affiche : [ { key: 1, value: 'hello' }, { key: 2, value: 'world' } ]

CJS

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

// Exécuter des instructions SQL à partir de chaînes de caractères.
database.exec(`
  CREATE TABLE data(
    key INTEGER PRIMARY KEY,
    value TEXT
  ) STRICT
`)
// Créer une instruction préparée pour insérer des données dans la base de données.
const insert = database.prepare('INSERT INTO data (key, value) VALUES (?, ?)')
// Exécuter l’instruction préparée avec des valeurs liées.
insert.run(1, 'hello')
insert.run(2, 'world')
// Créer une instruction préparée pour lire les données de la base de données.
const query = database.prepare('SELECT * FROM data ORDER BY key')
// Exécuter l’instruction préparée et journaliser le jeu de résultats.
console.log(query.all())
// Affiche : [ { key: 1, value: 'hello' }, { key: 2, value: 'world' } ]

Classe : DatabaseSync

Ajouté dans : v22.5.0

Cette classe représente une seule connexion à une base de données SQLite. Toutes les API exposées par cette classe s’exécutent de manière synchrone.

new DatabaseSync(location[, options])

Ajouté dans : v22.5.0

• location <string> L’emplacement de la base de données. Une base de données SQLite peut être stockée dans un fichier ou complètement en mémoire. Pour utiliser une base de données adossée à un fichier, l’emplacement doit être un chemin d’accès au fichier. Pour utiliser une base de données en mémoire, l’emplacement doit être le nom spécial ':memory:'.
• options <Object> Options de configuration pour la connexion à la base de données. Les options suivantes sont prises en charge :
  • open <boolean> Si true, la base de données est ouverte par le constructeur. Lorsque cette valeur est false, la base de données doit être ouverte via la méthode open(). Par défaut : true.
  • readOnly <boolean> Si true, la base de données est ouverte en mode lecture seule. Si la base de données n’existe pas, son ouverture échouera. Par défaut : false.
  • enableForeignKeyConstraints <boolean> Si true, les contraintes de clé étrangère sont activées. Ceci est recommandé, mais peut être désactivé pour assurer la compatibilité avec les schémas de base de données hérités. L’application des contraintes de clé étrangère peut être activée et désactivée après l’ouverture de la base de données à l’aide de PRAGMA foreign_keys. Par défaut : true.
  • enableDoubleQuotedStringLiterals <boolean> Si true, SQLite acceptera les littéraux de chaîne entre guillemets doubles. Ceci n’est pas recommandé, mais peut être activé pour assurer la compatibilité avec les schémas de base de données hérités. Par défaut : false.
  • allowExtension <boolean> Si true, la fonction SQL loadExtension et la méthode loadExtension() sont activées. Vous pouvez appeler enableLoadExtension(false) ultérieurement pour désactiver cette fonctionnalité. Par défaut : false.

Construit une nouvelle instance de DatabaseSync.

database.close()

Ajouté dans : v22.5.0

Ferme la connexion à la base de données. Une exception est levée si la base de données n'est pas ouverte. Cette méthode est un wrapper autour de sqlite3_close_v2().

database.loadExtension(path)

Ajouté dans : v23.5.0

• path <string> Le chemin vers la bibliothèque partagée à charger.

Charge une bibliothèque partagée dans la connexion à la base de données. Cette méthode est un wrapper autour de sqlite3_load_extension(). Il est nécessaire d'activer l'option allowExtension lors de la construction de l'instance DatabaseSync.

database.enableLoadExtension(allow)

Ajouté dans : v23.5.0

• allow <boolean> Indique s'il faut autoriser le chargement d'extensions.

Active ou désactive la fonction SQL loadExtension, et la méthode loadExtension(). Lorsque allowExtension est false lors de la construction, vous ne pouvez pas activer le chargement d'extensions pour des raisons de sécurité.

database.exec(sql)

Ajouté dans : v22.5.0

• sql <string> Une chaîne SQL à exécuter.

Cette méthode permet d'exécuter une ou plusieurs instructions SQL sans renvoyer de résultats. Cette méthode est utile lors de l'exécution d'instructions SQL lues à partir d'un fichier. Cette méthode est un wrapper autour de sqlite3_exec().

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

Ajouté dans : v23.5.0

• name <string> Le nom de la fonction SQLite à créer.

• options <Object> Paramètres de configuration facultatifs pour la fonction. Les propriétés suivantes sont prises en charge :

  • deterministic <boolean> Si true, l'indicateur SQLITE_DETERMINISTIC est défini sur la fonction créée. Par défaut : false.
  • directOnly <boolean> Si true, l'indicateur SQLITE_DIRECTONLY est défini sur la fonction créée. Par défaut : false.
  • useBigIntArguments <boolean> Si true, les arguments entiers de function sont convertis en BigInt. Si false, les arguments entiers sont transmis en tant que nombres JavaScript. Par défaut : false.
  • varargs <boolean> Si true, function peut accepter un nombre variable d'arguments. Si false, function doit être invoquée avec exactement function.length arguments. Par défaut : false.

• function <Function> La fonction JavaScript à appeler lorsque la fonction SQLite est invoquée.

Cette méthode est utilisée pour créer des fonctions définies par l'utilisateur SQLite. Cette méthode est un wrapper autour de sqlite3_create_function_v2().

database.open()

Ajouté dans : v22.5.0

Ouvre la base de données spécifiée dans l’argument location du constructeur DatabaseSync. Cette méthode ne doit être utilisée que lorsque la base de données n’est pas ouverte via le constructeur. Une exception est levée si la base de données est déjà ouverte.

database.prepare(sql)

Ajouté dans : v22.5.0

• sql <string> Une chaîne SQL à compiler dans une instruction préparée.
• Retourne : <StatementSync> L’instruction préparée.

Compile une instruction SQL en une instruction préparée. Cette méthode est un wrapper autour de sqlite3_prepare_v2().

database.createSession([options])

Ajouté dans : v23.3.0

• options <Object> Les options de configuration pour la session.

  • table <string> Une table spécifique pour le suivi des modifications. Par défaut, les modifications apportées à toutes les tables sont suivies.
  • db <string> Nom de la base de données à suivre. Ceci est utile lorsque plusieurs bases de données ont été ajoutées à l’aide de ATTACH DATABASE. Par défaut : 'main'.

• Retourne : <Session> Un handle de session.

Crée et attache une session à la base de données. Cette méthode est un wrapper autour de sqlite3session_create() et sqlite3session_attach().

database.applyChangeset(changeset[, options])

Ajouté dans : v23.3.0

• changeset <Uint8Array> Un ensemble de modifications binaires ou un ensemble de correctifs.

• options <Object> Les options de configuration pour la manière dont les modifications seront appliquées.

  • filter <Function> Ignore les modifications qui, lorsque le nom de la table cible est fourni à cette fonction, renvoient une valeur vraie. Par défaut, toutes les modifications sont tentées.
  • onConflict <number> Détermine comment les conflits sont gérés. Par défaut : SQLITE_CHANGESET_ABORT.
  • SQLITE_CHANGESET_OMIT : les modifications conflictuelles sont omises.
  • SQLITE_CHANGESET_REPLACE : les modifications conflictuelles remplacent les valeurs existantes.
  • SQLITE_CHANGESET_ABORT : annule en cas de conflit et restaure la base de données.

• Retourne : <boolean> Indique si l’ensemble de modifications a été appliqué avec succès sans être annulé.

Une exception est levée si la base de données n’est pas ouverte. Cette méthode est un wrapper autour de 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)
// Maintenant que l’ensemble de modifications a été appliqué, targetDb contient les mêmes données que sourceDb.

Classe : Session

Ajouté dans : v23.3.0

session.changeset()

Ajouté dans : v23.3.0

• Renvoie : <Uint8Array> Ensemble de modifications binaires qui peut être appliqué à d’autres bases de données.

Récupère un ensemble de modifications contenant toutes les modifications depuis que l’ensemble de modifications a été créé. Peut être appelé plusieurs fois. Une exception est levée si la base de données ou la session n’est pas ouverte. Cette méthode est un wrapper autour de sqlite3session_changeset().

session.patchset()

Ajouté dans : v23.3.0

• Renvoie : <Uint8Array> Ensemble de correctifs binaires qui peut être appliqué à d’autres bases de données.

Semblable à la méthode ci-dessus, mais génère un ensemble de correctifs plus compact. Voir Ensembles de modifications et ensembles de correctifs dans la documentation de SQLite. Une exception est levée si la base de données ou la session n’est pas ouverte. Cette méthode est un wrapper autour de sqlite3session_patchset().

session.close().

Ferme la session. Une exception est levée si la base de données ou la session n’est pas ouverte. Cette méthode est un wrapper autour de sqlite3session_delete().

Classe : StatementSync

Ajouté dans : v22.5.0

Cette classe représente une seule instruction préparée. Cette classe ne peut pas être instanciée via son constructeur. Au lieu de cela, les instances sont créées via la méthode database.prepare(). Toutes les API exposées par cette classe s’exécutent de manière synchrone.

Une instruction préparée est une représentation binaire efficace du SQL utilisé pour la créer. Les instructions préparées sont paramétrables et peuvent être invoquées plusieurs fois avec différentes valeurs liées. Les paramètres offrent également une protection contre les attaques par injection SQL. Pour ces raisons, les instructions préparées sont préférées aux chaînes SQL créées manuellement lors du traitement des entrées utilisateur.

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

Ajouté dans : v22.5.0

• namedParameters <Object> Un objet optionnel utilisé pour lier les paramètres nommés. Les clés de cet objet sont utilisées pour configurer le mappage.
• ...anonymousParameters <null> | <number> | <bigint> | <string> | <Buffer> | <Uint8Array> Zéro valeur ou plus à lier à des paramètres anonymes.
• Retourne : <Array> Un tableau d’objets. Chaque objet correspond à une ligne retournée par l’exécution de l’instruction préparée. Les clés et les valeurs de chaque objet correspondent aux noms de colonnes et aux valeurs de la ligne.

Cette méthode exécute une instruction préparée et retourne tous les résultats sous forme de tableau d’objets. Si l’instruction préparée ne retourne aucun résultat, cette méthode retourne un tableau vide. Les paramètres sont liés à l’instruction préparée en utilisant les valeurs dans namedParameters et anonymousParameters.

statement.expandedSQL

Ajouté dans : v22.5.0

• <string> La source SQL étendue pour inclure les valeurs des paramètres.

Le texte SQL source de l’instruction préparée avec les espaces réservés des paramètres remplacés par les valeurs qui ont été utilisées lors de la plus récente exécution de cette instruction préparée. Cette propriété est un wrapper autour de sqlite3_expanded_sql().

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

Ajouté dans : v22.5.0

• namedParameters <Object> Un objet optionnel utilisé pour lier des paramètres nommés. Les clés de cet objet sont utilisées pour configurer le mappage.
• ...anonymousParameters <null> | <number> | <bigint> | <string> | <Buffer> | <Uint8Array> Zéro ou plusieurs valeurs à lier aux paramètres anonymes.
• Retourne : <Object> | <undefined> Un objet correspondant à la première ligne retournée par l'exécution de l'instruction préparée. Les clés et les valeurs de l'objet correspondent aux noms de colonnes et aux valeurs de la ligne. Si aucune ligne n'a été retournée par la base de données, cette méthode retourne undefined.

Cette méthode exécute une instruction préparée et retourne le premier résultat sous forme d'objet. Si l'instruction préparée ne retourne aucun résultat, cette méthode retourne undefined. Les paramètres de l'instruction préparée sont liés en utilisant les valeurs dans namedParameters et anonymousParameters.

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

Ajouté dans : v23.4.0

• namedParameters <Object> Un objet optionnel utilisé pour lier des paramètres nommés. Les clés de cet objet sont utilisées pour configurer le mappage.
• ...anonymousParameters <null> | <number> | <bigint> | <string> | <Buffer> | <Uint8Array> Zéro ou plusieurs valeurs à lier aux paramètres anonymes.
• Retourne : <Iterator> Un itérateur itérable d'objets. Chaque objet correspond à une ligne retournée par l'exécution de l'instruction préparée. Les clés et les valeurs de chaque objet correspondent aux noms de colonnes et aux valeurs de la ligne.

Cette méthode exécute une instruction préparée et retourne un itérateur d'objets. Si l'instruction préparée ne retourne aucun résultat, cette méthode retourne un itérateur vide. Les paramètres de l'instruction préparée sont liés en utilisant les valeurs dans namedParameters et anonymousParameters.

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

Ajouté dans : v22.5.0

• namedParameters <Object> Un objet optionnel utilisé pour lier des paramètres nommés. Les clés de cet objet sont utilisées pour configurer le mappage.
• ...anonymousParameters <null> | <number> | <bigint> | <string> | <Buffer> | <Uint8Array> Zéro ou plusieurs valeurs à lier à des paramètres anonymes.
• Retourne : <Object>
  • changes : <number> | <bigint> Le nombre de lignes modifiées, insérées ou supprimées par l’instruction INSERT, UPDATE ou DELETE la plus récente. Ce champ est soit un nombre, soit un BigInt selon la configuration de l’instruction préparée. Cette propriété est le résultat de sqlite3_changes64().
  • lastInsertRowid : <number> | <bigint> Le rowid le plus récemment inséré. Ce champ est soit un nombre, soit un BigInt selon la configuration de l’instruction préparée. Cette propriété est le résultat de sqlite3_last_insert_rowid().

Cette méthode exécute une instruction préparée et renvoie un objet résumant les modifications résultantes. Les paramètres de l’instruction préparée sont liés en utilisant les valeurs dans namedParameters et anonymousParameters.

statement.setAllowBareNamedParameters(enabled)

Ajouté dans : v22.5.0

• enabled <boolean> Active ou désactive la prise en charge de la liaison des paramètres nommés sans le caractère de préfixe.

Les noms des paramètres SQLite commencent par un caractère de préfixe. Par défaut, node:sqlite exige que ce caractère de préfixe soit présent lors de la liaison des paramètres. Cependant, à l'exception du caractère dollar, ces caractères de préfixe nécessitent également des guillemets supplémentaires lorsqu'ils sont utilisés dans les clés d'objet.

Pour améliorer l'ergonomie, cette méthode peut être utilisée pour autoriser également les paramètres nommés nus, qui ne nécessitent pas le caractère de préfixe dans le code JavaScript. Il faut être conscient de plusieurs mises en garde lors de l'activation des paramètres nommés nus :

• Le caractère de préfixe est toujours requis en SQL.
• Le caractère de préfixe est toujours autorisé en JavaScript. En fait, les noms préfixés auront des performances de liaison légèrement meilleures.
• L'utilisation de paramètres nommés ambigus, tels que $k et @k, dans la même instruction préparée entraînera une exception car il ne peut pas être déterminé comment lier un nom nu.

statement.setReadBigInts(enabled)

Ajouté dans : v22.5.0

• enabled <boolean> Active ou désactive l'utilisation de BigInt lors de la lecture des champs INTEGER de la base de données.

Lors de la lecture à partir de la base de données, les INTEGER de SQLite sont mappés par défaut aux nombres JavaScript. Cependant, les INTEGER de SQLite peuvent stocker des valeurs supérieures à ce que les nombres JavaScript sont capables de représenter. Dans de tels cas, cette méthode peut être utilisée pour lire les données INTEGER à l'aide des BigInt de JavaScript. Cette méthode n'a aucun impact sur les opérations d'écriture dans la base de données où les nombres et les BigInt sont tous deux pris en charge à tout moment.

statement.sourceSQL

Ajouté dans : v22.5.0

• <string> Le code SQL source utilisé pour créer cette instruction préparée.

Le texte SQL source de l'instruction préparée. Cette propriété est un wrapper autour de sqlite3_sql().

Conversion de type entre JavaScript et SQLite

Lorsque Node.js écrit ou lit des données depuis SQLite, il est nécessaire de convertir entre les types de données JavaScript et les types de données de SQLite. Étant donné que JavaScript prend en charge plus de types de données que SQLite, seul un sous-ensemble de types JavaScript est pris en charge. Tenter d'écrire un type de données non pris en charge dans SQLite entraînera une exception.

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

sqlite.constants

Ajouté dans : v23.5.0

• <Object>

Un objet contenant des constantes couramment utilisées pour les opérations SQLite.

Constantes SQLite

Les constantes suivantes sont exportées par l'objet sqlite.constants.

Constantes de résolution de conflit

Les constantes suivantes sont destinées à être utilisées avec database.applyChangeset().

Constante	Description
SQLITE_CHANGESET_OMIT	Les changements conflictuels sont omis.
SQLITE_CHANGESET_REPLACE	Les changements conflictuels remplacent les valeurs existantes.
SQLITE_CHANGESET_ABORT	Abandonner lorsqu'un changement rencontre un conflit et annuler la base de données.