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 montre 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:');

// 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' } ]

CJS

'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' } ]

Classe : DatabaseSync

Ajoutée 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(emplacement[, options])

Ajoutée dans : v22.5.0

• emplacement <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 basée sur un fichier, l’emplacement doit être un chemin de 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 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 d’accès à 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 SQLite définies par l’utilisateur. 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 en 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 de la session.

  • table <string> Une table spécifique pour suivre les 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 façon dont les modifications seront appliquées.

  • filter <Function> Ignore les modifications qui, lorsque le nom de la table cible est fourni à cette fonction, retournent une valeur truthy. 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 : abandon en cas de conflit et restauration de la base de données.

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

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);
// Now that the changeset has been applied, targetDb contains the same data as sourceDb.
// 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

• Retourne : <Uint8Array> Changement binaire qui peut être appliqué à d’autres bases de données.

Récupère un ensemble de modifications contenant toutes les modifications depuis la création de l’ensemble de modifications. 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

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

Similaire à la méthode ci-dessus, mais génère un ensemble de correctifs plus compact. Voir Changesets and Patchsets 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 artisanales lors du traitement de la saisie utilisateur.

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

Ajoutée 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 : <Array> Un tableau d’objets. Chaque objet correspond à une ligne renvoyé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 renvoie tous les résultats sous forme de tableau d’objets. Si l’instruction préparée ne renvoie aucun résultat, cette méthode renvoie un tableau vide. Les paramètres de l’instruction préparée sont liés à l’aide des valeurs dans namedParameters et anonymousParameters.

statement.expandedSQL

Ajoutée dans : v22.5.0

• <string> Le code SQL source étendu 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 l’exécution la plus récente de cette instruction préparée. Cette propriété est un enveloppeur 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 à des paramètres anonymes.
• Retourne : <Object> | <undefined> Un objet correspondant à la première ligne renvoyée par l’exécution de l’instruction préparée. Les clés et les valeurs de l’objet correspondent aux noms et aux valeurs des colonnes de la ligne. Si aucune ligne n’est renvoyée par la base de données, cette méthode renvoie undefined.

Cette méthode exécute une instruction préparée et renvoie le premier résultat sous forme d’objet. Si l’instruction préparée ne renvoie aucun résultat, cette méthode renvoie undefined. Les paramètres de l’instruction préparée sont liés à l’aide des 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 à des paramètres anonymes.
• Retourne : <Iterator> Un itérateur itérable d’objets. Chaque objet correspond à une ligne renvoyée par l’exécution de l’instruction préparée. Les clés et les valeurs de chaque objet correspondent aux noms et aux valeurs des colonnes de la ligne.

Cette méthode exécute une instruction préparée et renvoie un itérateur d’objets. Si l’instruction préparée ne renvoie aucun résultat, cette méthode renvoie un itérateur vide. Les paramètres de l’instruction préparée sont liés à l’aide des valeurs dans namedParameters et anonymousParameters.

statement.run([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 ou plusieurs valeurs à lier à des paramètres anonymes.
• Renvoie : <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écemment terminée. Ce champ est soit un nombre, soit un BigInt en fonction de la configuration de l'instruction préparée. Cette propriété est le résultat de sqlite3_changes64().
  • lastInsertRowid: <number> | <bigint> Le rowid inséré le plus récemment. Ce champ est soit un nombre, soit un BigInt en fonction de 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 de namedParameters et anonymousParameters.

statement.setAllowBareNamedParameters(enabled)

Ajouté dans : v22.5.0

• enabled <boolean> Active ou désactive la prise en charge de la liaison de 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 existe plusieurs mises en garde à connaître lors de l’activation des paramètres nommés nus :

• Le caractère de préfixe est toujours requis dans 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 sera pas possible de déterminer comment lier un nom nu.

statement.setReadBigInts(enabled)

Ajouté dans : v22.5.0

• enabled <boolean> Active ou désactive l’utilisation de BigInts lors de la lecture des champs INTEGER à partir de la base de données.

Lors de la lecture à partir de la base de données, les INTEGERs SQLite sont mappés aux nombres JavaScript par défaut. Cependant, les INTEGERs SQLite peuvent stocker des valeurs plus grandes que celles 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 en utilisant les BigInts JavaScript. Cette méthode n’a aucun impact sur les opérations d’écriture de la base de données où les nombres et les BigInts 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 dans ou lit à partir de 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 des conflits

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.