SQLite

Añadido en: v22.5.0

[Estable: 1 - Experimental]

Estable: 1 Estabilidad: 1.1 - Desarrollo activo.

Código fuente: lib/sqlite.js

El módulo node:sqlite facilita el trabajo con bases de datos SQLite. Para acceder a él:

ESM

import sqlite from 'node:sqlite'

CJS

const sqlite = require('node:sqlite')

Este módulo solo está disponible bajo el esquema node:.

El siguiente ejemplo muestra el uso básico del módulo node:sqlite para abrir una base de datos en memoria, escribir datos en la base de datos y luego leer los datos de nuevo.

ESM

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

// Ejecuta sentencias SQL a partir de cadenas.
database.exec(`
  CREATE TABLE data(
    key INTEGER PRIMARY KEY,
    value TEXT
  ) STRICT
`)
// Crea una sentencia preparada para insertar datos en la base de datos.
const insert = database.prepare('INSERT INTO data (key, value) VALUES (?, ?)')
// Ejecuta la sentencia preparada con valores enlazados.
insert.run(1, 'hello')
insert.run(2, 'world')
// Crea una sentencia preparada para leer datos de la base de datos.
const query = database.prepare('SELECT * FROM data ORDER BY key')
// Ejecuta la sentencia preparada y registra el conjunto de resultados.
console.log(query.all())
// Imprime: [ { key: 1, value: 'hello' }, { key: 2, value: 'world' } ]

CJS

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

// Ejecuta sentencias SQL a partir de cadenas.
database.exec(`
  CREATE TABLE data(
    key INTEGER PRIMARY KEY,
    value TEXT
  ) STRICT
`)
// Crea una sentencia preparada para insertar datos en la base de datos.
const insert = database.prepare('INSERT INTO data (key, value) VALUES (?, ?)')
// Ejecuta la sentencia preparada con valores enlazados.
insert.run(1, 'hello')
insert.run(2, 'world')
// Crea una sentencia preparada para leer datos de la base de datos.
const query = database.prepare('SELECT * FROM data ORDER BY key')
// Ejecuta la sentencia preparada y registra el conjunto de resultados.
console.log(query.all())
// Imprime: [ { key: 1, value: 'hello' }, { key: 2, value: 'world' } ]

Clase: DatabaseSync

Añadido en: v22.5.0

Esta clase representa una sola conexión a una base de datos SQLite. Todas las API expuestas por esta clase se ejecutan de forma síncrona.

new DatabaseSync(location[, options])

Añadido en: v22.5.0

• location <string> La ubicación de la base de datos. Una base de datos SQLite se puede almacenar en un archivo o completamente en memoria. Para usar una base de datos respaldada por un archivo, la ubicación debe ser una ruta de archivo. Para usar una base de datos en memoria, la ubicación debe ser el nombre especial ':memory:'.
• options <Object> Opciones de configuración para la conexión a la base de datos. Se admiten las siguientes opciones:
  • open <boolean> Si es true, la base de datos se abre mediante el constructor. Cuando este valor es false, la base de datos debe abrirse mediante el método open(). Predeterminado: true.
  • readOnly <boolean> Si es true, la base de datos se abre en modo de solo lectura. Si la base de datos no existe, la apertura fallará. Predeterminado: false.
  • enableForeignKeyConstraints <boolean> Si es true, las restricciones de clave externa están habilitadas. Esto es recomendable, pero se puede deshabilitar para la compatibilidad con esquemas de bases de datos heredados. La aplicación de las restricciones de clave externa se puede habilitar y deshabilitar después de abrir la base de datos utilizando PRAGMA foreign_keys. Predeterminado: true.
  • enableDoubleQuotedStringLiterals <boolean> Si es true, SQLite aceptará literales de cadena entre comillas dobles. Esto no es recomendable, pero se puede habilitar para la compatibilidad con esquemas de bases de datos heredados. Predeterminado: false.
  • allowExtension <boolean> Si es true, la función SQL loadExtension y el método loadExtension() están habilitados. Puede llamar a enableLoadExtension(false) más adelante para deshabilitar esta función. Predeterminado: false.

Construye una nueva instancia de DatabaseSync.

database.close()

Añadido en: v22.5.0

Cierra la conexión a la base de datos. Se lanza una excepción si la base de datos no está abierta. Este método es un envoltorio alrededor de sqlite3_close_v2().

database.loadExtension(path)

Añadido en: v23.5.0

• path <string> La ruta a la biblioteca compartida que se va a cargar.

Carga una biblioteca compartida en la conexión a la base de datos. Este método es un envoltorio alrededor de sqlite3_load_extension(). Es necesario habilitar la opción allowExtension al construir la instancia DatabaseSync.

database.enableLoadExtension(allow)

Añadido en: v23.5.0

• allow <boolean> Indica si se permite cargar extensiones.

Habilita o deshabilita la función SQL loadExtension y el método loadExtension(). Cuando allowExtension es false al construir, no se pueden habilitar la carga de extensiones por razones de seguridad.

database.exec(sql)

Agregado en: v22.5.0

• sql <string> Una cadena SQL para ejecutar.

Este método permite ejecutar una o más sentencias SQL sin devolver ningún resultado. Este método es útil cuando se ejecutan sentencias SQL leídas desde un archivo. Este método es un envoltorio alrededor de sqlite3_exec().

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

Agregado en: v23.5.0

• name <string> El nombre de la función SQLite a crear.

• options <Object> Configuración opcional para la función. Se admiten las siguientes propiedades:

  • deterministic <boolean> Si es true, se establece el flag SQLITE_DETERMINISTIC en la función creada. Predeterminado: false.
  • directOnly <boolean> Si es true, se establece el flag SQLITE_DIRECTONLY en la función creada. Predeterminado: false.
  • useBigIntArguments <boolean> Si es true, los argumentos enteros para function se convierten a BigInts. Si es false, los argumentos enteros se pasan como números de JavaScript. Predeterminado: false.
  • varargs <boolean> Si es true, function puede aceptar un número variable de argumentos. Si es false, function debe ser invocada exactamente con function.length argumentos. Predeterminado: false.

• function <Function> La función JavaScript a llamar cuando se invoca la función SQLite.

Este método se utiliza para crear funciones definidas por el usuario de SQLite. Este método es un envoltorio alrededor de sqlite3_create_function_v2().

database.open()

Agregado en: v22.5.0

Abre la base de datos especificada en el argumento location del constructor DatabaseSync. Este método solo debe usarse cuando la base de datos no se abre a través del constructor. Se lanza una excepción si la base de datos ya está abierta.

database.prepare(sql)

Agregado en: v22.5.0

• sql <string> Una cadena SQL para compilar en una declaración preparada.
• Devuelve: <StatementSync> La declaración preparada.

Compila una declaración SQL en una declaración preparada. Este método es un envoltorio alrededor de sqlite3_prepare_v2().

database.createSession([options])

Agregado en: v23.3.0

• options <Object> Las opciones de configuración para la sesión.

  • table <string> Una tabla específica para rastrear los cambios. De forma predeterminada, se rastrean los cambios en todas las tablas.
  • db <string> Nombre de la base de datos a rastrear. Esto es útil cuando se han agregado varias bases de datos usando ATTACH DATABASE. Predeterminado: 'main'.

• Devuelve: <Session> Un identificador de sesión.

Crea y adjunta una sesión a la base de datos. Este método es un envoltorio alrededor de sqlite3session_create() y sqlite3session_attach().

database.applyChangeset(changeset[, options])

Agregado en: v23.3.0

• changeset <Uint8Array> Un conjunto de cambios binario o un conjunto de parches.
• options <Object> Las opciones de configuración para cómo se aplicarán los cambios.
  • filter <Function> Omite los cambios que, cuando se proporciona el nombre de la tabla de destino a esta función, devuelven un valor verdadero. De forma predeterminada, se intentan todos los cambios.
  • onConflict <number> Determina cómo se manejan los conflictos. Predeterminado: SQLITE_CHANGESET_ABORT.
  • SQLITE_CHANGESET_OMIT: los cambios conflictivos se omiten.
  • SQLITE_CHANGESET_REPLACE: los cambios conflictivos reemplazan los valores existentes.
  • SQLITE_CHANGESET_ABORT: aborta en caso de conflicto y revierte la base de datos.
• Devuelve: <boolean> Indica si el conjunto de cambios se aplicó correctamente sin ser abortado.

Se lanza una excepción si la base de datos no está abierta. Este método es un envoltorio alrededor 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)
// Ahora que se ha aplicado el conjunto de cambios, targetDb contiene los mismos datos que sourceDb.

Clase: Session

Agregado en: v23.3.0

session.changeset()

Agregado en: v23.3.0

• Devuelve: <Uint8Array> Conjunto de cambios binario que se puede aplicar a otras bases de datos.

Recupera un conjunto de cambios que contiene todos los cambios desde que se creó el conjunto de cambios. Se puede llamar varias veces. Se lanza una excepción si la base de datos o la sesión no están abiertas. Este método es un envoltorio alrededor de sqlite3session_changeset().

session.patchset()

Agregado en: v23.3.0

• Devuelve: <Uint8Array> Conjunto de parches binario que se puede aplicar a otras bases de datos.

Similar al método anterior, pero genera un conjunto de parches más compacto. Consulte Conjuntos de cambios y conjuntos de parches en la documentación de SQLite. Se lanza una excepción si la base de datos o la sesión no están abiertas. Este método es un envoltorio alrededor de sqlite3session_patchset().

session.close().

Cierra la sesión. Se lanza una excepción si la base de datos o la sesión no están abiertas. Este método es un envoltorio alrededor de sqlite3session_delete().

Clase: StatementSync

Agregado en: v22.5.0

Esta clase representa una única sentencia preparada. Esta clase no se puede instanciar a través de su constructor. En cambio, las instancias se crean a través del método database.prepare(). Todas las API expuestas por esta clase se ejecutan de forma síncrona.

Una sentencia preparada es una representación binaria eficiente del SQL utilizado para crearla. Las sentencias preparadas son parametrizables y se pueden invocar varias veces con diferentes valores vinculados. Los parámetros también ofrecen protección contra ataques de inyección SQL. Por estas razones, se prefieren las sentencias preparadas sobre las cadenas SQL hechas a mano cuando se maneja la entrada del usuario.

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

Agregado en: v22.5.0

• namedParameters <Object> Un objeto opcional utilizado para vincular parámetros con nombre. Las claves de este objeto se utilizan para configurar el mapeo.
• ...anonymousParameters <null> | <number> | <bigint> | <string> | <Buffer> | <Uint8Array> Cero o más valores para vincular a parámetros anónimos.
• Devuelve: <Array> Un arreglo de objetos. Cada objeto corresponde a una fila devuelta al ejecutar la sentencia preparada. Las claves y los valores de cada objeto corresponden a los nombres de las columnas y los valores de la fila.

Este método ejecuta una sentencia preparada y devuelve todos los resultados como un arreglo de objetos. Si la sentencia preparada no devuelve ningún resultado, este método devuelve un arreglo vacío. Los parámetros de la sentencia preparada se vinculan utilizando los valores en namedParameters y anonymousParameters.

statement.expandedSQL

Agregado en: v22.5.0

• <string> El SQL fuente expandido para incluir los valores de los parámetros.

El texto SQL fuente de la sentencia preparada con los marcadores de posición de los parámetros reemplazados por los valores que se utilizaron durante la ejecución más reciente de esta sentencia preparada. Esta propiedad es un envoltorio alrededor de sqlite3_expanded_sql().

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

Agregado en: v22.5.0

• namedParameters <Object> Un objeto opcional utilizado para vincular parámetros con nombre. Las claves de este objeto se utilizan para configurar la asignación.
• ...anonymousParameters <null> | <number> | <bigint> | <string> | <Buffer> | <Uint8Array> Cero o más valores para vincular a parámetros anónimos.
• Devuelve: <Object> | <undefined> Un objeto correspondiente a la primera fila devuelta al ejecutar la sentencia preparada. Las claves y los valores del objeto corresponden a los nombres de las columnas y los valores de la fila. Si no se devolvieron filas de la base de datos, este método devuelve undefined.

Este método ejecuta una sentencia preparada y devuelve el primer resultado como un objeto. Si la sentencia preparada no devuelve ningún resultado, este método devuelve undefined. Los parámetros de la sentencia preparada se vinculan utilizando los valores en namedParameters y anonymousParameters.

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

Agregado en: v23.4.0

• namedParameters <Objeto> Un objeto opcional utilizado para enlazar parámetros nombrados. Las claves de este objeto se utilizan para configurar la asignación.
• ...anonymousParameters <null> | <número> | <bigint> | <cadena> | <Buffer> | <Uint8Array> Cero o más valores para enlazar a parámetros anónimos.
• Devuelve: <Iterador> Un iterador iterable de objetos. Cada objeto corresponde a una fila devuelta al ejecutar la sentencia preparada. Las claves y los valores de cada objeto corresponden a los nombres de columna y valores de la fila.

Este método ejecuta una sentencia preparada y devuelve un iterador de objetos. Si la sentencia preparada no devuelve ningún resultado, este método devuelve un iterador vacío. Los parámetros de la sentencia preparada se enlazan utilizando los valores en namedParameters y anonymousParameters.

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

Añadido en: v22.5.0

• namedParameters <Object> Un objeto opcional usado para vincular parámetros nombrados. Las claves de este objeto se utilizan para configurar la asignación.
• ...anonymousParameters <null> | <number> | <bigint> | <string> | <Buffer> | <Uint8Array> Cero o más valores para vincular a parámetros anónimos.
• Devuelve: <Object>
  • changes: <number> | <bigint> El número de filas modificadas, insertadas o eliminadas por la declaración INSERT, UPDATE o DELETE completada más recientemente. Este campo es un número o un BigInt dependiendo de la configuración de la declaración preparada. Esta propiedad es el resultado de sqlite3_changes64().
  • lastInsertRowid: <number> | <bigint> El rowid insertado más recientemente. Este campo es un número o un BigInt dependiendo de la configuración de la declaración preparada. Esta propiedad es el resultado de sqlite3_last_insert_rowid().

Este método ejecuta una declaración preparada y devuelve un objeto que resume los cambios resultantes. Los parámetros de la declaración preparada se vinculan utilizando los valores en namedParameters y anonymousParameters.

statement.setAllowBareNamedParameters(enabled)

Agregado en: v22.5.0

• enabled <boolean> Habilita o deshabilita el soporte para enlazar parámetros nombrados sin el carácter de prefijo.

Los nombres de los parámetros de SQLite comienzan con un carácter de prefijo. Por defecto, node:sqlite requiere que este carácter de prefijo esté presente al enlazar parámetros. Sin embargo, con la excepción del carácter de signo de dólar, estos caracteres de prefijo también requieren comillas adicionales cuando se usan en claves de objeto.

Para mejorar la ergonomía, este método se puede usar para permitir también parámetros nombrados sin formato, que no requieren el carácter de prefijo en el código JavaScript. Hay varias advertencias que se deben tener en cuenta al habilitar los parámetros nombrados sin formato:

• El carácter de prefijo todavía es necesario en SQL.
• El carácter de prefijo todavía está permitido en JavaScript. De hecho, los nombres con prefijo tendrán un rendimiento de enlace ligeramente mejor.
• Usar parámetros nombrados ambiguos, como $k y @k, en la misma sentencia preparada resultará en una excepción, ya que no se puede determinar cómo enlazar un nombre sin formato.

statement.setReadBigInts(enabled)

Añadido en: v22.5.0

• enabled <booleano> Habilita o deshabilita el uso de BigInts al leer campos INTEGER de la base de datos.

Al leer de la base de datos, los INTEGER de SQLite se asignan a números de JavaScript de forma predeterminada. Sin embargo, los INTEGER de SQLite pueden almacenar valores más grandes de los que los números de JavaScript son capaces de representar. En tales casos, este método se puede usar para leer datos INTEGER usando BigInts de JavaScript. Este método no tiene impacto en las operaciones de escritura de la base de datos, donde los números y los BigInts son compatibles en todo momento.

statement.sourceSQL

Añadido en: v22.5.0

• <string> El SQL fuente utilizado para crear esta sentencia preparada.

El texto SQL fuente de la sentencia preparada. Esta propiedad es un envoltorio alrededor de sqlite3_sql().

Conversión de tipos entre JavaScript y SQLite

Cuando Node.js escribe o lee desde SQLite, es necesario convertir entre los tipos de datos de JavaScript y los tipos de datos de SQLite. Dado que JavaScript admite más tipos de datos que SQLite, solo se admite un subconjunto de tipos de JavaScript. Intentar escribir un tipo de datos no admitido en SQLite resultará en una excepción.

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

sqlite.constants

Añadido en: v23.5.0

• <Object>

Un objeto que contiene constantes de uso común para operaciones de SQLite.

Constantes de SQLite

Las siguientes constantes son exportadas por el objeto sqlite.constants.

Constantes de resolución de conflictos

Las siguientes constantes están pensadas para ser usadas con database.applyChangeset().

Constante	Descripción
SQLITE_CHANGESET_OMIT	Los cambios en conflicto son omitidos.
SQLITE_CHANGESET_REPLACE	Los cambios en conflicto reemplazan los valores existentes.
SQLITE_CHANGESET_ABORT	Abortar cuando un cambio encuentra un conflicto y revertir la base de datos.