better-sqlite3-typescript para TypeScript: guia completo com exemplos

No desenvolvimento com TypeScript, é comum surgir a necessidade de armazenar dados localmente sem configurar um banco de dados completo. O SQLite é a solução ideal para esses casos: um banco de dados relacional embutido que funciona sem servidor separado. No entanto, a biblioteca padrão better-sqlite3 é escrita em JavaScript e não oferece tipagem nativa. É aí que entra o better-sqlite3-typescript — um wrapper que adiciona tipagem estrita do TypeScript sobre a API síncrona do better-sqlite3.

Essa biblioteca permite escrever código type-safe para trabalhar com SQLite, obtendo autocompletar na IDE, verificação de tipos em tempo de compilação e reduzindo erros em tempo de execução. Você aproveita todos os benefícios do acesso síncrono ao banco de dados (simplicidade, previsibilidade, alta performance) com o poder do sistema de tipos do TypeScript.

Neste artigo, vamos detalhar a instalação, os principais métodos, apresentar exemplos reais e dar dicas de performance. O conteúdo é útil tanto para iniciantes quanto para desenvolvedores experientes que desejam usar SQLite de forma eficiente em seus projetos TypeScript.

Instalação

Para instalar a biblioteca, execute o seguinte comando no terminal do seu projeto:

npm install better-sqlite3-typescript better-sqlite3

Você também precisará instalar os tipos para TypeScript:

npm install -D @types/better-sqlite3

Após a instalação, você pode importar a biblioteca no seu projeto:

import Database from 'better-sqlite3-typescript';

Início rápido

Um exemplo mínimo funcional de criação de banco de dados, criação de tabela e inserção de dados:

import Database from 'better-sqlite3-typescript';

// Cria ou abre o banco de dados
const db = new Database('meu_banco.db');

// Cria a tabela
db.exec(`
  CREATE TABLE IF NOT EXISTS usuarios (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    nome TEXT NOT NULL,
    email TEXT UNIQUE NOT NULL,
    idade INTEGER
  )
`);

// Insere dados
const inserir = db.prepare('INSERT INTO usuarios (nome, email, idade) VALUES (?, ?, ?)');
inserir.run('Alice', 'alice@exemplo.com', 30);
inserir.run('Bob', 'bob@exemplo.com', 25);

// Lê dados
const selecionar = db.prepare('SELECT * FROM usuarios');
const usuarios = selecionar.all();
console.log(usuarios);

// Fecha a conexão
db.close();

Esse código criará o arquivo meu_banco.db no diretório atual, criará a tabela usuarios, adicionará dois usuários e exibirá os resultados no console.

Principais métodos e funções

Vamos explorar os métodos essenciais da biblioteca. Todos os exemplos assumem que você já tem uma instância do banco de dados db.

1. new Database(filename, options?)

Assinatura: new Database(filename: string, options?: DatabaseOptions): Database

Descrição: Cria ou abre um banco de dados SQLite. Se o arquivo não existir, ele será criado. As opções permitem configurar o modo de abertura (readonly, memory, etc.).

Exemplo:

// Abre banco em memória (não salva em disco)
const memDb = new Database(':memory:');

// Abre banco no modo somente leitura
const readOnlyDb = new Database('dados.db', { readonly: true });

2. db.prepare(sql)

Assinatura: prepare(sql: string): Statement

Descrição: Compila uma consulta SQL em um statement preparado. Retorna um objeto Statement que pode ser executado várias vezes com parâmetros diferentes.

Exemplo:

const stmt = db.prepare('SELECT * FROM usuarios WHERE idade > ?');
const adultos = stmt.all(18);
console.log(adultos);