SQLite

Adicionado em: v22.5.0

[Estável: 1 - Experimental]

Estável: 1 Estabilidade: 1.1 - Desenvolvimento ativo.

Código-fonte: lib/sqlite.js

O módulo node:sqlite facilita o trabalho com bancos de dados SQLite. Para acessá-lo:

ESM

import sqlite from 'node:sqlite'

CJS

const sqlite = require('node:sqlite')

Este módulo só está disponível sob o esquema node:.

O exemplo a seguir mostra o uso básico do módulo node:sqlite para abrir um banco de dados na memória, escrever dados no banco de dados e, em seguida, ler os dados novamente.

ESM

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

// Executar instruções SQL a partir de strings.
database.exec(`
  CREATE TABLE data(
    key INTEGER PRIMARY KEY,
    value TEXT
  ) STRICT
`)
// Criar uma instrução preparada para inserir dados no banco de dados.
const insert = database.prepare('INSERT INTO data (key, value) VALUES (?, ?)')
// Executar a instrução preparada com valores vinculados.
insert.run(1, 'hello')
insert.run(2, 'world')
// Criar uma instrução preparada para ler dados do banco de dados.
const query = database.prepare('SELECT * FROM data ORDER BY key')
// Executar a instrução preparada e registrar o 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:')

// Executar instruções SQL a partir de strings.
database.exec(`
  CREATE TABLE data(
    key INTEGER PRIMARY KEY,
    value TEXT
  ) STRICT
`)
// Criar uma instrução preparada para inserir dados no banco de dados.
const insert = database.prepare('INSERT INTO data (key, value) VALUES (?, ?)')
// Executar a instrução preparada com valores vinculados.
insert.run(1, 'hello')
insert.run(2, 'world')
// Criar uma instrução preparada para ler dados do banco de dados.
const query = database.prepare('SELECT * FROM data ORDER BY key')
// Executar a instrução preparada e registrar o conjunto de resultados.
console.log(query.all())
// Imprime: [ { key: 1, value: 'hello' }, { key: 2, value: 'world' } ]

Classe: DatabaseSync

Adicionado em: v22.5.0

Esta classe representa uma única conexão a um banco de dados SQLite. Todas as APIs expostas por esta classe são executadas sincronicamente.

new DatabaseSync(location[, options])

Adicionado em: v22.5.0

• location <string> O local do banco de dados. Um banco de dados SQLite pode ser armazenado em um arquivo ou completamente na memória. Para usar um banco de dados baseado em arquivo, o local deve ser um caminho de arquivo. Para usar um banco de dados em memória, o local deve ser o nome especial ':memory:'.
• options <Object> Opções de configuração para a conexão do banco de dados. As seguintes opções são suportadas:
  • open <boolean> Se true, o banco de dados é aberto pelo construtor. Quando este valor é false, o banco de dados deve ser aberto por meio do método open(). Padrão: true.
  • readOnly <boolean> Se true, o banco de dados é aberto no modo somente leitura. Se o banco de dados não existir, abri-lo falhará. Padrão: false.
  • enableForeignKeyConstraints <boolean> Se true, as restrições de chave estrangeira são habilitadas. Isso é recomendado, mas pode ser desabilitado para compatibilidade com esquemas de banco de dados legados. A aplicação das restrições de chave estrangeira pode ser habilitada e desabilitada após a abertura do banco de dados usando PRAGMA foreign_keys. Padrão: true.
  • enableDoubleQuotedStringLiterals <boolean> Se true, o SQLite aceitará literais de string entre aspas duplas. Isso não é recomendado, mas pode ser habilitado para compatibilidade com esquemas de banco de dados legados. Padrão: false.
  • allowExtension <boolean> Se true, a função SQL loadExtension e o método loadExtension() são habilitados. Você pode chamar enableLoadExtension(false) posteriormente para desabilitar este recurso. Padrão: false.

Constrói uma nova instância DatabaseSync.

database.close()

Adicionado em: v22.5.0

Fecha a conexão do banco de dados. Uma exceção é lançada se o banco de dados não estiver aberto. Este método é um wrapper em torno de sqlite3_close_v2().

database.loadExtension(path)

Adicionado em: v23.5.0

• path <string> O caminho para a biblioteca compartilhada a ser carregada.

Carrega uma biblioteca compartilhada na conexão do banco de dados. Este método é um wrapper em torno de sqlite3_load_extension(). É necessário habilitar a opção allowExtension ao construir a instância DatabaseSync.

database.enableLoadExtension(allow)

Adicionado em: v23.5.0

• allow <boolean> Se deve permitir o carregamento de extensões.

Habilita ou desabilita a função SQL loadExtension e o método loadExtension(). Quando allowExtension é false durante a construção, você não pode habilitar o carregamento de extensões por motivos de segurança.

database.exec(sql)

Adicionado em: v22.5.0

• sql <string> Uma string SQL a ser executada.

Este método permite que uma ou mais instruções SQL sejam executadas sem retornar nenhum resultado. Este método é útil ao executar instruções SQL lidas de um arquivo. Este método é um wrapper em torno de sqlite3_exec().

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

Adicionado em: v23.5.0

• name <string> O nome da função SQLite a ser criada.

• options <Object> Configurações opcionais para a função. As seguintes propriedades são suportadas:

  • deterministic <boolean> Se true, a flag SQLITE_DETERMINISTIC é definida na função criada. Padrão: false.
  • directOnly <boolean> Se true, a flag SQLITE_DIRECTONLY é definida na função criada. Padrão: false.
  • useBigIntArguments <boolean> Se true, os argumentos inteiros para function são convertidos para BigInts. Se false, os argumentos inteiros são passados como números JavaScript. Padrão: false.
  • varargs <boolean> Se true, function pode aceitar um número variável de argumentos. Se false, function deve ser invocado com exatamente function.length argumentos. Padrão: false.

• function <Function> A função JavaScript a ser chamada quando a função SQLite for invocada.

Este método é usado para criar funções definidas pelo usuário do SQLite. Este método é um wrapper em torno de sqlite3_create_function_v2().

database.open()

Adicionado em: v22.5.0

Abre o banco de dados especificado no argumento location do construtor DatabaseSync. Este método só deve ser usado quando o banco de dados não for aberto via construtor. Uma exceção é lançada se o banco de dados já estiver aberto.

database.prepare(sql)

Adicionado em: v22.5.0

• sql <string> Uma string SQL para compilar em uma instrução preparada.
• Retorna: <StatementSync> A instrução preparada.

Compila uma instrução SQL em uma instrução preparada. Este método é um wrapper em torno de sqlite3_prepare_v2().

database.createSession([options])

Adicionado em: v23.3.0

• options <Object> As opções de configuração para a sessão.

  • table <string> Uma tabela específica para rastrear alterações. Por padrão, as alterações em todas as tabelas são rastreadas.
  • db <string> Nome do banco de dados a ser rastreado. Isso é útil quando vários bancos de dados foram adicionados usando ATTACH DATABASE. Padrão: 'main'.

• Retorna: <Session> Um identificador de sessão.

Cria e anexa uma sessão ao banco de dados. Este método é um wrapper em torno de sqlite3session_create() e sqlite3session_attach().

database.applyChangeset(changeset[, options])

Adicionado em: v23.3.0

• changeset <Uint8Array> Um changeset ou patchset binário.

• options <Object> As opções de configuração de como as alterações serão aplicadas.

  • filter <Function> Ignora alterações que, quando o nome da tabela de destino é fornecido a esta função, retornam um valor truthy. Por padrão, todas as alterações são tentadas.
  • onConflict <number> Determina como os conflitos são tratados. Padrão: SQLITE_CHANGESET_ABORT.
  • SQLITE_CHANGESET_OMIT: alterações conflitantes são omitidas.
  • SQLITE_CHANGESET_REPLACE: alterações conflitantes substituem os valores existentes.
  • SQLITE_CHANGESET_ABORT: interrompe em caso de conflito e retorna o banco de dados.

• Retorna: <boolean> Se o changeset foi aplicado com sucesso sem ser interrompido.

Uma exceção é lançada se o banco de dados não estiver aberto. Este método é um wrapper em torno 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)
// Agora que o changeset foi aplicado, targetDb contém os mesmos dados que sourceDb.

Classe: Session

Adicionado em: v23.3.0

session.changeset()

Adicionado em: v23.3.0

• Retorna: <Uint8Array> Changeset binário que pode ser aplicado a outros bancos de dados.

Recupera um changeset contendo todas as alterações desde a criação do changeset. Pode ser chamado múltiplas vezes. Uma exceção é lançada se o banco de dados ou a sessão não estiverem abertos. Este método é um wrapper em torno de sqlite3session_changeset().

session.patchset()

Adicionado em: v23.3.0

• Retorna: <Uint8Array> Patchset binário que pode ser aplicado a outros bancos de dados.

Similar ao método acima, mas gera um patchset mais compacto. Veja Changesets e Patchsets na documentação do SQLite. Uma exceção é lançada se o banco de dados ou a sessão não estiverem abertos. Este método é um wrapper em torno de sqlite3session_patchset().

session.close().

Fecha a sessão. Uma exceção é lançada se o banco de dados ou a sessão não estiverem abertos. Este método é um wrapper em torno de sqlite3session_delete().

Classe: StatementSync

Adicionado em: v22.5.0

Esta classe representa uma única declaração preparada. Esta classe não pode ser instanciada via seu construtor. Em vez disso, instâncias são criadas via o método database.prepare(). Todas as APIs expostas por esta classe executam sincronicamente.

Uma declaração preparada é uma representação binária eficiente do SQL usado para criá-la. Declarações preparadas são parametrizáveis e podem ser invocadas múltiplas vezes com diferentes valores vinculados. Parâmetros também oferecem proteção contra ataques de injeção SQL. Por essas razões, declarações preparadas são preferíveis a strings SQL feitas manualmente ao lidar com entrada do usuário.

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

Adicionado em: v22.5.0

• namedParameters <Object> Um objeto opcional usado para vincular parâmetros nomeados. As chaves deste objeto são usadas para configurar o mapeamento.
• ...anonymousParameters <null> | <number> | <bigint> | <string> | <Buffer> | <Uint8Array> Zero ou mais valores para vincular a parâmetros anônimos.
• Retorna: <Array> Um array de objetos. Cada objeto corresponde a uma linha retornada pela execução da declaração preparada. As chaves e os valores de cada objeto correspondem aos nomes e valores das colunas da linha.

Este método executa uma declaração preparada e retorna todos os resultados como um array de objetos. Se a declaração preparada não retornar nenhum resultado, este método retorna um array vazio. Os parâmetros da declaração preparada são vinculados usando os valores em namedParameters e anonymousParameters.

statement.expandedSQL

Adicionado em: v22.5.0

• <string> O SQL de origem expandido para incluir valores de parâmetros.

O texto SQL de origem da declaração preparada com placeholders de parâmetros substituídos pelos valores que foram usados durante a execução mais recente desta declaração preparada. Esta propriedade é um wrapper em torno de sqlite3_expanded_sql().

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

Adicionado em: v22.5.0

• namedParameters <Object> Um objeto opcional usado para vincular parâmetros nomeados. As chaves deste objeto são usadas para configurar o mapeamento.
• ...anonymousParameters <null> | <number> | <bigint> | <string> | <Buffer> | <Uint8Array> Zero ou mais valores para vincular a parâmetros anônimos.
• Retorna: <Object> | <undefined> Um objeto correspondente à primeira linha retornada pela execução da instrução preparada. As chaves e os valores do objeto correspondem aos nomes e valores das colunas da linha. Se nenhuma linha for retornada do banco de dados, este método retorna undefined.

Este método executa uma instrução preparada e retorna o primeiro resultado como um objeto. Se a instrução preparada não retornar nenhum resultado, este método retorna undefined. Os parâmetros da instrução preparada são vinculados usando os valores em namedParameters e anonymousParameters.

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

Adicionado em: v23.4.0

• namedParameters <Object> Um objeto opcional usado para vincular parâmetros nomeados. As chaves deste objeto são usadas para configurar o mapeamento.
• ...anonymousParameters <null> | <number> | <bigint> | <string> | <Buffer> | <Uint8Array> Zero ou mais valores para vincular a parâmetros anônimos.
• Retorna: <Iterator> Um iterador iterável de objetos. Cada objeto corresponde a uma linha retornada pela execução da instrução preparada. As chaves e os valores de cada objeto correspondem aos nomes e valores das colunas da linha.

Este método executa uma instrução preparada e retorna um iterador de objetos. Se a instrução preparada não retornar nenhum resultado, este método retorna um iterador vazio. Os parâmetros da instrução preparada são vinculados usando os valores em namedParameters e anonymousParameters.

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

Adicionado em: v22.5.0

• namedParameters <Object> Um objeto opcional usado para vincular parâmetros nomeados. As chaves deste objeto são usadas para configurar o mapeamento.
• ...anonymousParameters <null> | <number> | <bigint> | <string> | <Buffer> | <Uint8Array> Zero ou mais valores para vincular a parâmetros anônimos.
• Retorna: <Object>
  • changes: <number> | <bigint> O número de linhas modificadas, inseridas ou excluídas pela instrução INSERT, UPDATE ou DELETE mais recentemente concluída. Este campo é um número ou um BigInt, dependendo da configuração da instrução preparada. Esta propriedade é o resultado de sqlite3_changes64().
  • lastInsertRowid: <number> | <bigint> O rowid mais recentemente inserido. Este campo é um número ou um BigInt, dependendo da configuração da instrução preparada. Esta propriedade é o resultado de sqlite3_last_insert_rowid().

Este método executa uma instrução preparada e retorna um objeto resumindo as alterações resultantes. Os parâmetros da instrução preparada são vinculados usando os valores em namedParameters e anonymousParameters.

statement.setAllowBareNamedParameters(enabled)

Adicionado em: v22.5.0

• enabled <boolean> Habilita ou desabilita o suporte para vinculação de parâmetros nomeados sem o caractere de prefixo.

Os nomes dos parâmetros do SQLite começam com um caractere de prefixo. Por padrão, node:sqlite exige que este caractere de prefixo esteja presente ao vincular parâmetros. No entanto, com exceção do caractere de cifrão, esses caracteres de prefixo também exigem aspas extras quando usados em chaves de objeto.

Para melhorar a ergonomia, este método pode ser usado para permitir também parâmetros nomeados puros, que não exigem o caractere de prefixo no código JavaScript. Existem várias ressalvas a serem consideradas ao habilitar parâmetros nomeados puros:

• O caractere de prefixo ainda é necessário no SQL.
• O caractere de prefixo ainda é permitido em JavaScript. Na verdade, nomes prefixados terão um desempenho de vinculação ligeiramente melhor.
• O uso de parâmetros nomeados ambíguos, como $k e @k, na mesma instrução preparada resultará em uma exceção, pois não é possível determinar como vincular um nome puro.

statement.setReadBigInts(enabled)

Adicionado em: v22.5.0

• enabled <boolean> Habilita ou desabilita o uso de BigInts ao ler campos INTEGER do banco de dados.

Ao ler do banco de dados, os INTEGERs do SQLite são mapeados para números JavaScript por padrão. No entanto, os INTEGERs do SQLite podem armazenar valores maiores do que os números JavaScript são capazes de representar. Nesses casos, este método pode ser usado para ler dados INTEGER usando BigInts do JavaScript. Este método não tem impacto nas operações de gravação do banco de dados, onde números e BigInts são ambos suportados o tempo todo.

statement.sourceSQL

Adicionado em: v22.5.0

• <string> O SQL de origem usado para criar esta instrução preparada.

O texto SQL de origem da instrução preparada. Esta propriedade é um wrapper em torno de sqlite3_sql().

Conversão de tipo entre JavaScript e SQLite

Quando o Node.js escreve ou lê do SQLite, é necessário converter entre os tipos de dados do JavaScript e os tipos de dados do SQLite tipos de dados. Como o JavaScript suporta mais tipos de dados do que o SQLite, apenas um subconjunto dos tipos do JavaScript é suportado. Tentar escrever um tipo de dado não suportado para o SQLite resultará em uma exceção.

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

sqlite.constants

Adicionado em: v23.5.0

• <Object>

Um objeto contendo constantes comumente usadas para operações SQLite.

Constantes SQLite

As seguintes constantes são exportadas pelo objeto sqlite.constants.

Constantes de resolução de conflito

As seguintes constantes destinam-se a serem usadas com database.applyChangeset().

Constante	Descrição
SQLITE_CHANGESET_OMIT	Alterações conflitantes são omitidas.
SQLITE_CHANGESET_REPLACE	Alterações conflitantes substituem os valores existentes.
SQLITE_CHANGESET_ABORT	Abortar quando uma alteração encontrar um conflito e reverter o banco de dados.