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:
import sqlite from 'node:sqlite';
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 vuelta.
import { DatabaseSync } from 'node:sqlite';
const database = new DatabaseSync(':memory:');
// Ejecutar sentencias SQL desde cadenas.
database.exec(`
CREATE TABLE data(
key INTEGER PRIMARY KEY,
value TEXT
) STRICT
`);
// Crear una sentencia preparada para insertar datos en la base de datos.
const insert = database.prepare('INSERT INTO data (key, value) VALUES (?, ?)');
// Ejecutar la sentencia preparada con valores enlazados.
insert.run(1, 'hello');
insert.run(2, 'world');
// Crear una sentencia preparada para leer datos de la base de datos.
const query = database.prepare('SELECT * FROM data ORDER BY key');
// Ejecutar la sentencia preparada y registrar el conjunto de resultados.
console.log(query.all());
// Imprime: [ { key: 1, value: 'hello' }, { key: 2, value: 'world' } ]
'use strict';
const { DatabaseSync } = require('node:sqlite');
const database = new DatabaseSync(':memory:');
// Ejecutar sentencias SQL desde cadenas.
database.exec(`
CREATE TABLE data(
key INTEGER PRIMARY KEY,
value TEXT
) STRICT
`);
// Crear una sentencia preparada para insertar datos en la base de datos.
const insert = database.prepare('INSERT INTO data (key, value) VALUES (?, ?)');
// Ejecutar la sentencia preparada con valores enlazados.
insert.run(1, 'hello');
insert.run(2, 'world');
// Crear una sentencia preparada para leer datos de la base de datos.
const query = database.prepare('SELECT * FROM data ORDER BY key');
// Ejecutar la sentencia preparada y registrar 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 APIs 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 puede almacenarse en un archivo o completamente en memoria. Para utilizar una base de datos basada en archivos, la ubicación debe ser una ruta de archivo. Para utilizar 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 de la base de datos. Se admiten las siguientes opciones:open
<boolean> Si estrue
, la base de datos se abre mediante el constructor. Cuando este valor esfalse
, la base de datos debe abrirse mediante el métodoopen()
. Predeterminado:true
.readOnly
<boolean> Si estrue
, la base de datos se abre en modo de solo lectura. Si la base de datos no existe, al intentar abrirla fallará. Predeterminado:false
.enableForeignKeyConstraints
<boolean> Si estrue
, 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 utilizandoPRAGMA foreign_keys
. Predeterminado:true
.enableDoubleQuotedStringLiterals
<boolean> Si estrue
, 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 estrue
, la función SQLloadExtension
y el métodoloadExtension()
están habilitados. Puede llamar aenableLoadExtension(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 para sqlite3_close_v2()
.
database.loadExtension(path)
Añadido en: v23.5.0
path
<string> La ruta a la biblioteca compartida para cargar.
Carga una biblioteca compartida en la conexión a la base de datos. Este método es un envoltorio para 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 la carga de 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)
Añadido 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 de un archivo. Este método es un envoltorio para sqlite3_exec()
.
database.function(name[, options], function)
Añadido en: v23.5.0
name
<string> El nombre de la función SQLite para crear.options
<Object> Ajustes de configuración opcionales para la función. Se admiten las siguientes propiedades:deterministic
<boolean> Si estrue
, el flagSQLITE_DETERMINISTIC
se establece en la función creada. Predeterminado:false
.directOnly
<boolean> Si estrue
, el flagSQLITE_DIRECTONLY
se establece en la función creada. Predeterminado:false
.useBigIntArguments
<boolean> Si estrue
, los argumentos enteros afunction
se convierten enBigInt
s. Si esfalse
, los argumentos enteros se pasan como números de JavaScript. Predeterminado:false
.varargs
<boolean> Si estrue
,function
puede aceptar un número variable de argumentos. Si esfalse
,function
debe ser invocada con exactamentefunction.length
argumentos. Predeterminado:false
.
function
<Function> La función JavaScript para 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 para sqlite3_create_function_v2()
.
database.open()
Añadido 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)
Añadido 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])
Añadido 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 añadido varias bases de datos utilizandoATTACH 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])
Añadido 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 gestionan 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ó con éxito 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);
// Now that the changeset has been applied, targetDb contains the same data as sourceDb.
// Ahora que se ha aplicado el conjunto de cambios, targetDb contiene los mismos datos que sourceDb.
Clase: Session
Añadido en: v23.3.0
session.changeset()
Añadido en: v23.3.0
- Retorna: <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()
Añadido en: v23.3.0
- Retorna: <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
Añadido en: v22.5.0
Esta clase representa una única sentencia preparada. Esta clase no se puede instanciar a través de su constructor. En su lugar, las instancias se crean a través del método database.prepare()
. Todas las API expuestas por esta clase se ejecutan sincrónicamente.
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 enlazados. Los parámetros también ofrecen protección contra ataques de inyección SQL. Por estas razones, las sentencias preparadas son preferibles a las cadenas SQL hechas a mano cuando se maneja la entrada del usuario.
statement.all([namedParameters][, ...anonymousParameters])
Añadido en: v22.5.0
namedParameters
<Object> Un objeto opcional utilizado 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: <Array> Un array 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 y valores de las columnas de la fila.
Este método ejecuta una sentencia preparada y devuelve todos los resultados como un array de objetos. Si la sentencia preparada no devuelve ningún resultado, este método devuelve un array vacío. Los parámetros de la sentencia preparada se vinculan utilizando los valores en namedParameters
y anonymousParameters
.
statement.expandedSQL
Añadido 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])
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> | <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 y valores de las columnas 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 están vinculados usando los valores en namedParameters
y anonymousParameters
.
statement.iterate([namedParameters][, ...anonymousParameters])
Añadido en: v23.4.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: <Iterator> 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 y valores de las columnas 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 están vinculados usando los valores en namedParameters
y anonymousParameters
.
statement.run([namedParameters][, ...anonymousParameters])
Añadido 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>
changes
: <number> | <bigint> El número de filas modificadas, insertadas o eliminadas por la instrucciónINSERT
,UPDATE
oDELETE
completada más recientemente. Este campo es un número o unBigInt
dependiendo de la configuración de la declaración preparada. Esta propiedad es el resultado desqlite3_changes64()
.lastInsertRowid
: <number> | <bigint> El rowid insertado más recientemente. Este campo es un número o unBigInt
dependiendo de la configuración de la declaración preparada. Esta propiedad es el resultado desqlite3_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)
Añadido en: v22.5.0
enabled
<boolean> Activa o desactiva la compatibilidad para vincular 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 vincular parámetros. Sin embargo, con la excepción del signo de dólar, estos caracteres de prefijo también requieren comillas adicionales cuando se utilizan en claves de objetos.
Para mejorar la ergonomía, este método se puede utilizar también para permitir parámetros nombrados "bare", 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 "bare":
- 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.
- El uso de 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 vincular un nombre "bare".
statement.setReadBigInts(enabled)
Añadido en: v22.5.0
enabled
<boolean> Activa o desactiva el uso deBigInt
s al leer camposINTEGER
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 lo que los números de JavaScript son capaces de representar. En tales casos, este método se puede utilizar para leer datos INTEGER
utilizando BigInt
s de JavaScript. Este método no tiene impacto en las operaciones de escritura de la base de datos, donde los números y los BigInt
s son compatibles en todo momento.
statement.sourceSQL
Añadido en: v22.5.0
- <string> El código 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 tipo 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. Debido a 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
Un objeto que contiene constantes de uso común para las 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 destinadas a ser utilizadas con database.applyChangeset()
.
Constante | Descripción |
---|---|
SQLITE_CHANGESET_OMIT | Los cambios en conflicto se omiten. |
SQLITE_CHANGESET_REPLACE | Los cambios en conflicto reemplazan los valores existentes. |
SQLITE_CHANGESET_ABORT | Abortar cuando un cambio encuentra un conflicto y deshacer la base de datos. |