Guia Rápido: Configuração Bun + SQLite

Precisa de um banco de dados rápido e sem dependências para seu projeto Bun? Configurar o Bun SQLite leva apenas alguns minutos e oferece um banco de dados local poderoso sem dependências externas ou configurações complexas. Aqui está tudo o que você precisa para começar com bun:sqlite e integrá-lo aos seus projetos.

Primeiros Passos com Bun SQLite

O módulo integrado bun:sqlite fornece um driver SQLite síncrono e de alto desempenho, perfeito para desenvolvimento local, protótipos e pequenas aplicações em produção. Nenhum pacote npm necessário—já faz parte do Bun.

Conexão Básica com o Banco de Dados

import { Database } from "bun:sqlite"

// Create or open a database file
const db = new Database("app.db")

// Or use an in-memory database for testing
const memDb = new Database(":memory:")

É isso—você agora tem uma conexão funcional com o banco de dados Bun SQLite. O arquivo do banco de dados é criado automaticamente se não existir.

Executando Suas Primeiras Consultas com bun:sqlite

Criando Tabelas e Operações Básicas

// Create a table
db.run(`
  CREATE TABLE IF NOT EXISTS users (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    name TEXT NOT NULL,
    email TEXT UNIQUE
  )
`)

// Insert data using parameters (prevents SQL injection)
const insertUser = db.prepare("INSERT INTO users (name, email) VALUES (?, ?)")
insertUser.run("Alice", "alice@example.com")

// Query data
const getUser = db.prepare("SELECT * FROM users WHERE name = ?")
const user = getUser.get("Alice")
console.log(user) // { id: 1, name: "Alice", email: "alice@example.com" }

// Get all results
const allUsers = db.prepare("SELECT * FROM users").all()

A API do Bun SQLite usa prepared statements por padrão, tornando suas consultas seguras e rápidas. O método .get() retorna uma única linha, enquanto .all() retorna um array com todas as linhas correspondentes.

Trabalhando com Transações

Para operações que precisam ter sucesso ou falhar em conjunto, use transações:

const insertMany = db.transaction((users) => {
  const stmt = db.prepare("INSERT INTO users (name, email) VALUES (?, ?)")
  for (const user of users) {
    stmt.run(user.name, user.email)
  }
})

// This either inserts all users or none
insertMany([
  { name: "Bob", email: "bob@example.com" },
  { name: "Charlie", email: "charlie@example.com" }
])

Recursos Avançados do Bun SQLite

Usando Parâmetros Nomeados

Parâmetros nomeados tornam consultas complexas mais legíveis:

const query = db.prepare(`
  SELECT * FROM users 
  WHERE name = $name AND email = $email
`)

const result = query.get({
  $name: "Alice",
  $email: "alice@example.com"
})

Manipulando Diferentes Tipos de Retorno

O Bun SQLite oferece múltiplos métodos para recuperar dados:

const stmt = db.prepare("SELECT * FROM users")

// Get first row as object
const firstUser = stmt.get()

// Get all rows as objects
const allUsers = stmt.all()

// Get values as arrays (useful for data processing)
const values = stmt.values()
// Returns: [[1, "Alice", "alice@example.com"], [2, "Bob", "bob@example.com"]]

// Execute without returning results (for INSERT/UPDATE/DELETE)
stmt.run()

Integrando com Drizzle ORM

Para projetos maiores, combinar bun:sqlite com Drizzle ORM proporciona segurança de tipos e melhor experiência do desenvolvedor:

// Install Drizzle
// bun add drizzle-orm drizzle-kit

import { drizzle } from 'drizzle-orm/bun-sqlite'
import { Database } from 'bun:sqlite'

const sqlite = new Database('app.db')
const db = drizzle(sqlite)

// Now use Drizzle's type-safe query builder
const users = await db.select().from(usersTable)

Melhores Práticas e Dicas de Desempenho

Sempre Feche as Conexões

Embora o Bun SQLite feche automaticamente os bancos de dados durante a coleta de lixo, fechá-los explicitamente é uma boa prática:

// When done with the database
db.close()

Use Prepared Statements

Prepared statements no Bun SQLite são armazenados em cache e reutilizados, oferecendo melhor desempenho para consultas repetidas:

// Good: Prepare once, use many times
const stmt = db.prepare("SELECT * FROM users WHERE id = ?")
for (const id of userIds) {
  const user = stmt.get(id)
  // Process user
}

// Less efficient: Creating new statement each time
for (const id of userIds) {
  const user = db.prepare("SELECT * FROM users WHERE id = ?").get(id)
}

Escolha o Modo de Armazenamento Correto

• Use bancos de dados baseados em arquivo (Database("app.db")) para dados persistentes
• Use bancos de dados em memória (Database(":memory:")) para testes ou dados temporários
• Use modo somente leitura (Database("data.db", { readonly: true })) para conjuntos de dados estáticos

Conclusão

O Bun SQLite fornece tudo o que você precisa para operações de banco de dados local sem dependências externas. Seja construindo uma ferramenta CLI, protótipo de API ou pequeno serviço em produção, o módulo integrado bun:sqlite oferece o equilíbrio perfeito entre simplicidade e desempenho. Comece com a API síncrona para scripts rápidos e depois adicione o Drizzle ORM quando precisar de segurança de tipos e migrações. Com apenas algumas linhas de código, você tem um banco de dados SQL totalmente funcional pronto para uso.

Perguntas Frequentes

Gain Debugging Superpowers

Unleash the power of session replay to reproduce bugs, track slowdowns and uncover frustrations in your app. Get complete visibility into your frontend with OpenReplay — the most advanced open-source session replay tool for developers. Check our GitHub repo and join the thousands of developers in our community.