SQLite

Aggiunto in: v22.5.0

[Stabile: 1 - Sperimentale]

Stabile: 1 Stabilità: 1.1 - Sviluppo attivo.

Codice sorgente: lib/sqlite.js

Il modulo node:sqlite facilita il lavoro con i database SQLite. Per accedervi:

ESM

import sqlite from 'node:sqlite'

CJS

const sqlite = require('node:sqlite')

Questo modulo è disponibile solo con lo schema node:.

Il seguente esempio mostra l'utilizzo di base del modulo node:sqlite per aprire un database in memoria, scrivere dati nel database e poi rileggere i dati.

ESM

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

// Esegue istruzioni SQL da stringhe.
database.exec(`
  CREATE TABLE data(
    key INTEGER PRIMARY KEY,
    value TEXT
  ) STRICT
`)
// Crea un'istruzione preparata per inserire dati nel database.
const insert = database.prepare('INSERT INTO data (key, value) VALUES (?, ?)')
// Esegue l'istruzione preparata con valori legati.
insert.run(1, 'hello')
insert.run(2, 'world')
// Crea un'istruzione preparata per leggere dati dal database.
const query = database.prepare('SELECT * FROM data ORDER BY key')
// Esegue l'istruzione preparata e registra il set di risultati.
console.log(query.all())
// Stampa: [ { key: 1, value: 'hello' }, { key: 2, value: 'world' } ]

CJS

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

// Esegue istruzioni SQL da stringhe.
database.exec(`
  CREATE TABLE data(
    key INTEGER PRIMARY KEY,
    value TEXT
  ) STRICT
`)
// Crea un'istruzione preparata per inserire dati nel database.
const insert = database.prepare('INSERT INTO data (key, value) VALUES (?, ?)')
// Esegue l'istruzione preparata con valori legati.
insert.run(1, 'hello')
insert.run(2, 'world')
// Crea un'istruzione preparata per leggere dati dal database.
const query = database.prepare('SELECT * FROM data ORDER BY key')
// Esegue l'istruzione preparata e registra il set di risultati.
console.log(query.all())
// Stampa: [ { key: 1, value: 'hello' }, { key: 2, value: 'world' } ]

Classe: DatabaseSync

Aggiunto in: v22.5.0

Questa classe rappresenta una singola connessione a un database SQLite. Tutte le API esposte da questa classe vengono eseguite in modo sincrono.

new DatabaseSync(location[, options])

Aggiunto in: v22.5.0

• location <string> La posizione del database. Un database SQLite può essere memorizzato in un file o completamente in memoria. Per utilizzare un database su file, la posizione deve essere un percorso file. Per utilizzare un database in memoria, la posizione deve essere il nome speciale ':memory:'.
• options <Object> Opzioni di configurazione per la connessione al database. Sono supportate le seguenti opzioni:
  • open <boolean> Se true, il database viene aperto dal costruttore. Quando questo valore è false, il database deve essere aperto tramite il metodo open(). Default: true.
  • readOnly <boolean> Se true, il database viene aperto in modalità di sola lettura. Se il database non esiste, l'apertura avrà esito negativo. Default: false.
  • enableForeignKeyConstraints <boolean> Se true, i vincoli di chiave esterna sono abilitati. Questo è consigliato ma può essere disabilitato per la compatibilità con schemi di database legacy. L'applicazione dei vincoli di chiave esterna può essere abilitata e disabilitata dopo aver aperto il database usando PRAGMA foreign_keys. Default: true.
  • enableDoubleQuotedStringLiterals <boolean> Se true, SQLite accetterà letterali di stringa tra virgolette doppie. Questo non è consigliato ma può essere abilitato per la compatibilità con schemi di database legacy. Default: false.
  • allowExtension <boolean> Se true, la funzione SQL loadExtension e il metodo loadExtension() sono abilitati. È possibile chiamare enableLoadExtension(false) in seguito per disabilitare questa funzionalità. Default: false.

Costruisce una nuova istanza DatabaseSync.

database.close()

Aggiunto in: v22.5.0

Chiude la connessione al database. Viene sollevata un'eccezione se il database non è aperto. Questo metodo è un wrapper attorno a sqlite3_close_v2().

database.loadExtension(path)

Aggiunto in: v23.5.0

• path <string> Il percorso alla libreria condivisa da caricare.

Carica una libreria condivisa nella connessione al database. Questo metodo è un wrapper attorno a sqlite3_load_extension(). È richiesto abilitare l'opzione allowExtension durante la costruzione dell'istanza DatabaseSync.

database.enableLoadExtension(allow)

Aggiunto in: v23.5.0

• allow <boolean> Se consentire il caricamento di estensioni.

Abilita o disabilita la funzione SQL loadExtension e il metodo loadExtension(). Quando allowExtension è false durante la costruzione, non è possibile abilitare il caricamento di estensioni per motivi di sicurezza.

database.exec(sql)

Aggiunto in: v22.5.0

• sql <string> Una stringa SQL da eseguire.

Questo metodo permette l'esecuzione di una o più istruzioni SQL senza restituire alcun risultato. Questo metodo è utile quando si eseguono istruzioni SQL lette da un file. Questo metodo è un wrapper attorno a sqlite3_exec().

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

Aggiunto in: v23.5.0

• name <string> Il nome della funzione SQLite da creare.

• options <Object> Impostazioni di configurazione facoltative per la funzione. Sono supportate le seguenti proprietà:

  • deterministic <boolean> Se true, il flag SQLITE_DETERMINISTIC viene impostato sulla funzione creata. Default: false.
  • directOnly <boolean> Se true, il flag SQLITE_DIRECTONLY viene impostato sulla funzione creata. Default: false.
  • useBigIntArguments <boolean> Se true, gli argomenti interi a function vengono convertiti in BigInt. Se false, gli argomenti interi vengono passati come numeri JavaScript. Default: false.
  • varargs <boolean> Se true, function può accettare un numero variabile di argomenti. Se false, function deve essere invocato con esattamente function.length argomenti. Default: false.

• function <Function> La funzione JavaScript da chiamare quando viene invocata la funzione SQLite.

Questo metodo viene utilizzato per creare funzioni definite dall'utente SQLite. Questo metodo è un wrapper attorno a sqlite3_create_function_v2().

database.open()

Aggiunto in: v22.5.0

Apre il database specificato nell'argomento location del costruttore DatabaseSync. Questo metodo dovrebbe essere utilizzato solo quando il database non è aperto tramite il costruttore. Viene lanciata un'eccezione se il database è già aperto.

database.prepare(sql)

Aggiunto in: v22.5.0

• sql <string> Una stringa SQL da compilare in un'istruzione preparata.
• Restituisce: <StatementSync> L'istruzione preparata.

Compila un'istruzione SQL in un' istruzione preparata. Questo metodo è un wrapper attorno a sqlite3_prepare_v2().

database.createSession([options])

Aggiunto in: v23.3.0

• options <Object> Le opzioni di configurazione per la sessione.

  • table <string> Una tabella specifica per tracciare le modifiche. Per impostazione predefinita, vengono tracciate le modifiche a tutte le tabelle.
  • db <string> Nome del database da tracciare. Questo è utile quando sono stati aggiunti più database usando ATTACH DATABASE. Predefinito: 'main'.

• Restituisce: <Session> Un handle di sessione.

Crea e associa una sessione al database. Questo metodo è un wrapper attorno a sqlite3session_create() e sqlite3session_attach().

database.applyChangeset(changeset[, options])

Aggiunto in: v23.3.0

• changeset <Uint8Array> Un changeset o patchset binario.

• options <Object> Le opzioni di configurazione su come verranno applicate le modifiche.

  • filter <Function> Salta le modifiche che, quando il nome della tabella di destinazione viene fornito a questa funzione, restituiscono un valore truthy. Per impostazione predefinita, vengono tentate tutte le modifiche.
  • onConflict <number> Determina come vengono gestiti i conflitti. Predefinito: SQLITE_CHANGESET_ABORT.
  • SQLITE_CHANGESET_OMIT: le modifiche in conflitto vengono omesse.
  • SQLITE_CHANGESET_REPLACE: le modifiche in conflitto sostituiscono i valori esistenti.
  • SQLITE_CHANGESET_ABORT: interruzione in caso di conflitto e rollback del database.

• Restituisce: <boolean> Se il changeset è stato applicato correttamente senza essere interrotto.

Viene lanciata un'eccezione se il database non è aperto. Questo metodo è un wrapper attorno a 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)
// Ora che il changeset è stato applicato, targetDb contiene gli stessi dati di sourceDb.

Classe: Session

Aggiunto in: v23.3.0

session.changeset()

Aggiunto in: v23.3.0

• Restituisce: <Uint8Array> Changeset binario che può essere applicato ad altri database.

Recupera un changeset contenente tutte le modifiche da quando è stato creato il changeset. Può essere chiamato più volte. Viene sollevata un'eccezione se il database o la sessione non sono aperti. Questo metodo è un wrapper attorno a sqlite3session_changeset().

session.patchset()

Aggiunto in: v23.3.0

• Restituisce: <Uint8Array> Patchset binario che può essere applicato ad altri database.

Simile al metodo precedente, ma genera un patchset più compatto. Vedi Changesets e Patchsets nella documentazione di SQLite. Viene sollevata un'eccezione se il database o la sessione non sono aperti. Questo metodo è un wrapper attorno a sqlite3session_patchset().

session.close().

Chiude la sessione. Viene sollevata un'eccezione se il database o la sessione non sono aperti. Questo metodo è un wrapper attorno a sqlite3session_delete().

Classe: StatementSync

Aggiunto in: v22.5.0

Questa classe rappresenta una singola istruzione preparata. Questa classe non può essere istanziata tramite il suo costruttore. Invece, le istanze vengono create tramite il metodo database.prepare(). Tutte le API esposte da questa classe vengono eseguite in modo sincrono.

Un'istruzione preparata è una rappresentazione binaria efficiente del codice SQL utilizzato per crearla. Le istruzioni preparate sono parametrizzabili e possono essere invocate più volte con valori associati diversi. I parametri offrono anche protezione dagli attacchi di iniezione SQL. Per questi motivi, le istruzioni preparate sono preferite alle stringhe SQL create manualmente quando si gestisce l'input dell'utente.

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

Aggiunto in: v22.5.0

• namedParameters <Object> Un oggetto opzionale utilizzato per legare parametri nominativi. Le chiavi di questo oggetto vengono utilizzate per configurare il mapping.
• ...anonymousParameters <null> | <number> | <bigint> | <string> | <Buffer> | <Uint8Array> Zero o più valori da legare a parametri anonimi.
• Restituisce: <Array> Una matrice di oggetti. Ogni oggetto corrisponde a una riga restituita dall'esecuzione dell'istruzione preparata. Le chiavi e i valori di ogni oggetto corrispondono ai nomi e ai valori delle colonne della riga.

Questo metodo esegue un'istruzione preparata e restituisce tutti i risultati come una matrice di oggetti. Se l'istruzione preparata non restituisce alcun risultato, questo metodo restituisce una matrice vuota. I parametri dell'istruzione preparata sono legati utilizzando i valori in namedParameters e anonymousParameters.

statement.expandedSQL

Aggiunto in: v22.5.0

• <string> Il codice SQL sorgente espanso per includere i valori dei parametri.

Il testo SQL sorgente dell'istruzione preparata con i segnaposto dei parametri sostituiti dai valori utilizzati durante l'ultima esecuzione di questa istruzione preparata. Questa proprietà è un wrapper attorno a sqlite3_expanded_sql().

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

Aggiunto in: v22.5.0

• namedParameters <Object> Un oggetto opzionale utilizzato per legare i parametri nominati. Le chiavi di questo oggetto vengono utilizzate per configurare la mappatura.
• ...anonymousParameters <null> | <number> | <bigint> | <string> | <Buffer> | <Uint8Array> Zero o più valori da legare a parametri anonimi.
• Restituisce: <Object> | <undefined> Un oggetto corrispondente alla prima riga restituita dall'esecuzione dell'istruzione preparata. Le chiavi e i valori dell'oggetto corrispondono ai nomi e ai valori delle colonne della riga. Se non vengono restituite righe dal database, questo metodo restituisce undefined.

Questo metodo esegue un'istruzione preparata e restituisce il primo risultato come oggetto. Se l'istruzione preparata non restituisce alcun risultato, questo metodo restituisce undefined. I parametri dell'istruzione preparata vengono legati utilizzando i valori in namedParameters e anonymousParameters.

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

Aggiunto in: v23.4.0

• namedParameters <Object> Un oggetto opzionale utilizzato per legare i parametri nominati. Le chiavi di questo oggetto vengono utilizzate per configurare la mappatura.
• ...anonymousParameters <null> | <number> | <bigint> | <string> | <Buffer> | <Uint8Array> Zero o più valori da legare a parametri anonimi.
• Restituisce: <Iterator> Un iteratore iterabile di oggetti. Ogni oggetto corrisponde a una riga restituita dall'esecuzione dell'istruzione preparata. Le chiavi e i valori di ogni oggetto corrispondono ai nomi e ai valori delle colonne della riga.

Questo metodo esegue un'istruzione preparata e restituisce un iteratore di oggetti. Se l'istruzione preparata non restituisce alcun risultato, questo metodo restituisce un iteratore vuoto. I parametri dell'istruzione preparata vengono legati utilizzando i valori in namedParameters e anonymousParameters.

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

Aggiunto in: v22.5.0

• namedParameters <Object> Un oggetto opzionale usato per legare parametri nominativi. Le chiavi di questo oggetto sono usate per configurare il mapping.
• ...anonymousParameters <null> | <number> | <bigint> | <string> | <Buffer> | <Uint8Array> Zero o più valori da legare a parametri anonimi.
• Restituisce: <Object>
  • changes: <number> | <bigint> Il numero di righe modificate, inserite o eliminate dall'istruzione INSERT, UPDATE o DELETE più recentemente completata. Questo campo è un numero o un BigInt a seconda della configurazione dell'istruzione preparata. Questa proprietà è il risultato di sqlite3_changes64().
  • lastInsertRowid: <number> | <bigint> Il rowid più recentemente inserito. Questo campo è un numero o un BigInt a seconda della configurazione dell'istruzione preparata. Questa proprietà è il risultato di sqlite3_last_insert_rowid().

Questo metodo esegue un'istruzione preparata e restituisce un oggetto che riassume le modifiche risultanti. I parametri dell'istruzione preparata sono legati usando i valori in namedParameters e anonymousParameters.

statement.setAllowBareNamedParameters(enabled)

Aggiunto in: v22.5.0

• enabled <boolean> Abilita o disabilita il supporto per il binding di parametri nominati senza il carattere di prefisso.

I nomi dei parametri SQLite iniziano con un carattere di prefisso. Per impostazione predefinita, node:sqlite richiede che questo carattere di prefisso sia presente durante il binding dei parametri. Tuttavia, ad eccezione del carattere del dollaro, questi caratteri di prefisso richiedono anche una citazione aggiuntiva quando vengono utilizzati nelle chiavi dell'oggetto.

Per migliorare l'ergonomia, questo metodo può essere utilizzato per consentire anche parametri nominati semplici, che non richiedono il carattere di prefisso nel codice JavaScript. Ci sono diversi aspetti da tenere presenti quando si abilitano i parametri nominati semplici:

• Il carattere di prefisso è comunque richiesto in SQL.
• Il carattere di prefisso è comunque consentito in JavaScript. Infatti, i nomi prefissati avranno prestazioni di binding leggermente migliori.
• L'utilizzo di parametri nominati ambigui, come $k e @k, nella stessa istruzione preparata si tradurrà in un'eccezione in quanto non è possibile determinare come eseguire il binding di un nome semplice.

statement.setReadBigInts(enabled)

Aggiunto in: v22.5.0

• enabled <boolean> Abilita o disabilita l'utilizzo di BigInt durante la lettura dei campi INTEGER dal database.

Durante la lettura dal database, gli INTEGER di SQLite vengono mappati ai numeri JavaScript per impostazione predefinita. Tuttavia, gli INTEGER di SQLite possono memorizzare valori maggiori di quelli che i numeri JavaScript sono in grado di rappresentare. In questi casi, questo metodo può essere utilizzato per leggere i dati INTEGER utilizzando BigInt di JavaScript. Questo metodo non ha alcun impatto sulle operazioni di scrittura del database, dove numeri e BigInt sono entrambi supportati in ogni momento.

statement.sourceSQL

Aggiunto in: v22.5.0

• <string> L'istruzione SQL di origine utilizzata per creare questa istruzione preparata.

Il testo SQL di origine dell'istruzione preparata. Questa proprietà è un wrapper attorno a sqlite3_sql().

Conversione di tipo tra JavaScript e SQLite

Quando Node.js scrive o legge da SQLite, è necessario convertire tra i tipi di dati JavaScript e i tipi di dati di SQLite data types. Poiché JavaScript supporta più tipi di dati rispetto a SQLite, è supportato solo un sottoinsieme dei tipi JavaScript. Tentare di scrivere un tipo di dati non supportato in SQLite provocherà un'eccezione.

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

sqlite.constants

Aggiunto in: v23.5.0

• <Object>

Un oggetto contenente costanti comunemente utilizzate per le operazioni SQLite.

Costanti SQLite

Le seguenti costanti sono esportate dall'oggetto sqlite.constants.

Costanti di risoluzione dei conflitti

Le seguenti costanti sono destinate all'uso con database.applyChangeset().

Costante	Descrizione
SQLITE_CHANGESET_OMIT	Le modifiche in conflitto vengono omesse.
SQLITE_CHANGESET_REPLACE	Le modifiche in conflitto sostituiscono i valori esistenti.
SQLITE_CHANGESET_ABORT	Interrompe l'operazione quando una modifica incontra un conflitto e esegue il rollback del database.