SQLite on Dev TLDRLSS

Não se deixe enganar pela informalidade do SQLite! Quais são as armadilhas dos tipos dinâmicos? Por que o ALTER TABLE é capenga? Como construir uma arquitetura de programação defensiva no Node.js para atualizações de esquema sem dor?

Tue, 19 May 2026 18:10:00 +0800

Imagine uma lixeira de reciclagem onde você claramente colocou uma etiqueta dizendo "Apenas Garrafas Plásticas", mas quando alguém joga um pedaço de papel lá dentro, ela o aceita silenciosamente sem uma única palavra de protesto?

Esta é a experiência de arrepiar a espinha que os desenvolvedores vivem quando conhecem o sistema de tipos do SQLite pela primeira vez.

Se você está acostumado ao estilo rigoroso de agente de alfândega do PostgreSQL (onde os tipos incorretos são rejeitados diretamente), a informalidade do SQLite pode fazer você questionar sua vida.

Ainda mais assustador, quando você quer modificar a estrutura de uma tabela, ele lhe dirá:

"A tabela não pode ser modificada diretamente. Por favor, construa uma casa nova, mude os móveis e depois exploda a casa velha."

Sob o capô, o SQLite tem apenas 5 classes de armazenamento

Não importa quais nomes de tipo elegantes você declare em CREATE TABLE (VARCHAR(255), BIGINT, DECIMAL), o SQLite sob o capô reconhece apenas estas 5 classes de armazenamento:

Classe de armazenamento	Descrição
NULL	Valor nulo
INTEGER	Inteiro (ocupa automaticamente de 1 a 8 bytes de acordo com a magnitude)
REAL	Número de ponto flutuante (fixo de 8 bytes)
TEXT	String de texto (codificação UTF-8 padrão)
BLOB	Objeto binário grande (armazenado exatamente como inserido)

Os tipos que você define nas colunas são meramente "sugestões" para o SQLite, não "regras obrigatórias".

Isso se chama "Type Affinity" (Afinidade de tipos). O SQLite tentará converter seus dados para o tipo sugerido, mas se não puder, simplesmente colocará os dados originais de qualquer maneira sem lançar nenhum erro.

Você pode declarar uma coluna age INTEGER no SQLite e depois inserir a string 'para sempre dezoito'; ele o aceitará com prazer.

Três armadilhas de tipos mais fáceis de cair

Armadilha 1: Sem Boolean nativo

O SQLite não tem tipo booleano. True e False só podem ser representados pelos inteiros 1 e 0.

Quando você recupera dados do SQLite usando Node.js, obterá o número 1 ou 0, não true ou false.

Se você realizar diretamente uma verificação como if (user.is_admin === true), isso nunca será verdadeiro.

Armadilha 2: Sem tipo Date/Time

O SQLite não tem tipo de data/hora. Você só pode armazenar o tempo como:

Método de armazenamento	Exemplo	Prós e contras
TEXT (string ISO-8601)	`'2026-05-19T18:00:00Z'`	Mais recomendado, alta legibilidade, conversão perfeita ao passar para PostgreSQL no futuro
INTEGER (Unix Timestamp)	`1747656000`	Pegada pequena, mas não legível por humanos

Nunca armazene datas em formatos personalizados arbitrários como 19/05/2026 18:00, caso contrário, a migração de dados no futuro será un desastre.

Armadilha 3: Inserir uma string em uma coluna Integer não gerará erro

No PostgreSQL, inserir uma string em uma coluna INTEGER gera um erro imediatamente. Mas o SQLite apenas tentará convertê-la silenciosamente e, se falhar, a aceitará tal como está.

Isso significa que dados sujos podem entrar silenciosamente no seu banco de dados até que um dia seu programa falhe devido ao recebimento de um tipo inesperado, só então você descobrirá o problema.

Programação defensiva: Tratar um banco de dados informal com uma atitude rigorosa

Diante da informalidade do SQLite, você deve construir mecanismos de defesa rígidos no desenvolvimento com Node.js:

Nível de defesa	Ferramenta	Papel
Guarda em tempo de compilação	TypeScript	Capturar tipos incorretos no estágio de escrita do código
Validação de entrada de API	Zod	Validar os dados de entrada estritamente (garantir que age seja sempre um número)
Conversão implícita de tipos	Prisma / Drizzle ORM	Lidar automaticamente com as diferenças de tipos entre SQLite e PostgreSQL

Mover o "guardião da validação de dados" da camada do banco de dados para a camada da aplicação Node.js é uma estratégia-chave para aproveitar a velocidade de desenvolvimento do SQLite e, ao mesmo tempo, garantir a escalabilidade futura.

Ao usar um ORM, desde que você declare type: 'boolean' no seu código, o ORM o converte automaticamente para 1/0 ao salvar no SQLite, e o converte de volta para true/false ao ler, ocultando perfeitamente as diferenças de tipos subjacentes.

ALTER TABLE é capenga: O que pode e o que não pode ser modificado

O suporte do SQLite para modificar estruturas de tabelas é muito limitado:

Operação	Suportado
Adicionar coluna (`ADD COLUMN`)	Sim
Renomear coluna (`RENAME COLUMN`)	Sim
Excluir coluna (`DROP COLUMN`)	Sim (em versões mais novas)
Renomear tabela (`RENAME TO`)	Sim
Alterar tipo de coluna	Não
Adicionar/remover restrições `UNIQUE`, `NOT NULL`	Não
Modificar chave primária	Não
Modificar chave estrangeira	Não

Uma vez que precise realizar qualquer uma das modificações "não suportadas", o SQLite exige que você execute a estratégia de "recriar e mover".

Os quatro passos para recriar e mover: O caminho de atualização de tabelas do SQLite

Como não pode ser modificado diretamente, a prática padrão recomendada pelos documentos oficiais é construir uma casa nova, mudar os móveis, explodir a casa velha e colocar a placa nova:

Passo	Ação	Descrição
1	Criar tabela nova	`CREATE TABLE users_new (...)` usando a estrutura correta
2	Copiar dados	`INSERT INTO users_new SELECT ... FROM users`
3	Excluir tabela velha	`DROP TABLE users`
4	Renombrar tabela	`ALTER TABLE users_new RENAME TO users`

Esses quatro passos devem ser executados de uma só vez; qualquer queda de energia ou crash da aplicação no meio do caminho resultará na perda de dados.

Garantir que as atualizações não percam dados: Duas linhas de defesa de segurança

Linha de defesa 1: Defesa física, copiar o arquivo diretamente

O SQLite é essencialmente apenas um arquivo. Antes de executar qualquer alteração de esquema, simplesmente faça uma cópia do arquivo .db como backup.

const fs = require('fs');
fs.copyFileSync('my_project.db', 'my_project_backup.db');

Se as coisas derem errado, substituir o arquivo restaura tudo em un instante. Esta é uma vantagem que outros bancos de dados grandes não podem oferecer.

Linha de defesa 2: Pacote de Transaction, a máquina do tempo do banco de dados

Envolva todos os passos de migração dentro de uma única Transaction; se algum passo falhar, todo o processo será revertido automaticamente (Rollback) como se nada tivesse acontecido.

const Database = require('better-sqlite3');
const db = new Database('my_project.db');

const migrateData = db.transaction(() => {
  db.prepare(`
    CREATE TABLE users_new (
      id INTEGER PRIMARY KEY AUTOINCREMENT,
      name TEXT NOT NULL,
      age INTEGER NOT NULL DEFAULT 18
    )
  `).run();

  db.prepare(`
    INSERT INTO users_new (id, name, age)
    SELECT id, name, COALESCE(age, 18) FROM users
  `).run();

  db.prepare('DROP TABLE users').run();
  db.prepare('ALTER TABLE users_new RENAME TO users').run();
});

try {
  migrateData();
  console.log('Tabela atualizada com sucesso');
} catch (error) {
  console.error('A atualização falhou, dados restaurados com segurança:', error.message);
}

"Arquivo de backup + Vinculação de Transaction" é o airbag da migração do seu banco de dados.

Controle a informalidade do SQLite com uma atitude rigorosa

Domine a informalidade do SQLite com uma arquitetura rígida na camada de aplicação para desfrutar da sua velocidade de desenvolvimento ultrarrápida e evitar dívidas técnicas futuras.

O sistema de tipos do SQLite é muito informal, e o ALTER TABLE tem muitas limitações.

No entanto, desde que você realize verificação de tipos com TypeScript + validação com Zod + abstração com ORM no lado do Node.js, combinado com a estratégia de segurança de backup físico + Transaction, você dapat desfrutar com segurança da eficiência de desenvolvimento oferecida pelo SQLite enquanto pavimenta o caminho para migrar para o PostgreSQL no futuro.

Reference

Não use o PostgreSQL para tudo! Quais são as vantagens da arquitetura embarcada e configuração zero do SQLite? Onde estão os limites do SQLite? Quando você deve escolher o SQLite e quando o PostgreSQL?

Tue, 19 May 2026 18:00:00 +0800

Você já pensou no fato de que o navegador que você abre todos os dias, o software de comunicação no seu celular e até a ferramenta de notas no seu computador ocultam o mesmo banco de dados leve?

Ele não exige que você instale nenhum software de servidor, não precisa de configurações de conta ou senha e nem precisa de conexão com a Internet. É simplesmente um arquivo, que repousa silenciosamente no seu disco rígido, pronto para atendê-lo a qualquer momento.

Essa existência discreta é o SQLite.

O que é o SQLite? O banco de dados mais amplamente implantado no mundo

SQLite é um mecanismo de banco de dados relacional embarcado escrito em C.

Ele não possui um processo de servidor independente, mas é diretamente embarcado em sua aplicação para ser executado.

Isso é completamente diferente do PostgreSQL ou MySQL com os quais você está familiarizado. Os bancos de dados tradicionais são servidores independentes executados separadamente, e seu programa deve “comunicar-se” com eles por meio de um protocolo de rede (TCP/IP).

But SQLite é diferente; é simplesmente um bloco de código que roda diretamente dentro da sua aplicação, lendo e gravando aquele arquivo .db no seu disco rígido.

Dimensão de comparação	SQLite (Embarcado)	PostgreSQL (Cliente-Servidor)
Modo de operação	Diretamente embarcado na aplicação, sem servidor independente	Processo de servidor independente, via conexão de rede
Requisitos de config.	Configuração zero, sem instalação, sem credenciais	Requer instalação, configuração de conta/senha e firewall
Armaz. de dados	Arquivo único multiplataforma	Múltiplos arquivos sob o diretório do servidor
Método de backup	Copiar diretamente aquele arquivo	Requer ferramentas dedicadas como pg_dump

É precisamente por causa dessa característica de “plug-and-play” que o SQLite se tornou o mecanismo de banco de dados mais implantado no mundo.

Desde os sistemas operacionais Android e iOS, navegadores Chrome e Firefox, até o Adobe Lightroom, WhatsApp e até mesmo o sistema de voo do Airbus A350, ele está em toda parte.

Usando o SQLite no Node.js

Se você é um desenvolvedor Node.js, usar o SQLite é extremamente simples. Você não precisa instalar nenhum software de servidor de banco de dados no seu computador, precisa apenas instalar um pacote npm para começar.

As opções mais comumente usadas na indústria hoje:

Nome do pacote	Características	Cenário recomendado
`sqlite3`	O mais tradicional, suporta APIs assíncronas	Quando precisa lidar com muitas tarefas assíncronas simultaneamente
`better-sqlite3`	Excelente desempenho, design de API intuitivo, extremamente rápido	Recomendação principal, para eficiência de desenvolvimento e velocidade de execução

Criar um banco de dados e consultá-lo com o better-sqlite3 leva menos de cinco minutos:

const Database = require('better-sqlite3');
const db = new Database('my_project.db');

db.prepare('CREATE TABLE IF NOT EXISTS users (name TEXT, age INTEGER)').run();

const insert = db.prepare('INSERT INTO users (name, age) VALUES (?, ?)');
insert.run('John', 25);

const user = db.prepare('SELECT * FROM users WHERE name = ?').get('John');
console.log(user); // { name: 'John', age: 25 }

Se o arquivo não existir, o better-sqlite3 o criará automaticamente para você.

O SQLite suporta uma sintaxe SQL mais poderosa do que você imagina

Muitas pessoas pensam que o SQLite é muito básico, mas ele suporta a grande maioria da sintaxe SQL padrão, incluindo muitos recursos avançados:

Categoria de sintaxe	Itens suportados
Operações básicas	`SELECT`, `INSERT`, `UPDATE`, `DELETE`
Definição de dados	`CREATE TABLE`, `CREATE INDEX`, `CREATE VIEW`
Consultas avançadas	`WITH` (CTEs recursivas), Funções de janela (Window Functions)
Tratamento de conflito	`UPSERT` (`INSERT ... ON CONFLICT DO UPDATE`)
Processamento de JSON	Funções integradas como `json_extract`, `json_array`, `json_object`, etc.
Controle de transação	`BEGIN`, `COMMIT`, `ROLLBACK`, `SAVEPOINT`
Consultas de junção	`INNER JOIN`, `LEFT JOIN`, `RIGHT JOIN` e `FULL OUTER JOIN`

A filosofia central do SQLite é “pequeno e bonito”, suportando a maioria das capacidades SQL que você precisa no dia a dia, mantendo-se extremamente leve.

Onde estão os limites do SQLite?

A leveza tem um preço. Se compararmos o SQLite a uma mercearia hipster com apenas um caixa de pagamento, o PostgreSQL seria um Costco equipado com 50 caixas registradoras.

1. Congestionamento de gravação

Quando o SQLite grava dados, ele bloqueia todo o arquivo do banco de dados.

Imagine um restaurante com apenas um banheiro: 100 pessoas podem olhar o cardápio do lado de fora (ler) ao mesmo tempo, mas contanto que 1 pessoa entre e tranque a porta (gravar), todas as outras só podem fazer fila e esperar.

Embora a ativação do modo WAL (Write-Ahead Logging) possa melhorar o desempenho de leitura/gravação simultânea, fundamentalmente ainda não é possível realizar gravações simultâneas multithread em diferentes linhas de dados.

2. Não é possível distribuir em múltiplos servidores

A essência do SQLite é um arquivo físico. Se o seu sistema for implantado em múltiplos servidores (escala horizontal), esses servidores não podem compartilhar o mesmo arquivo com segurança.

3. Falta de gerenciamento de permissões detalhado

O SQLite não possui o conceito de “contas de usuário”. Qualquer pessoa que possa ler esse arquivo .db no nível do sistema operacional pode ver e modificar todos os dados.

Para sistemas de negócios que exigem auditorias rigorosas de dados pessoais, isso é inaceitável.

SQLite vs. PostgreSQL: Decisões de seleção de tecnologia

As ferramentas não são boas nem ruins, apenas adequadas ou não. Aqui está um checklist definitivo para ajudá-lo a tomar decisões:

Pergunta	Resposta “Sim” → Escolha o SQLite	Resposta “Não” → Escolha o PostgreSQL
Existe apenas um servidor backend, ou ele roda totalmente de forma local?	Sim	Não (requer escala horizontal, múltiplas máquinas)
O comportamento do sistema é dominado pela leitura, sem gravações simultâneas de alta frequência?	Sim	Não (os usuários competirão para gravar simultaneamente)
Não precisa de permissões de conta de banco de dados detalhadas ou indexação avançada?	Sim	Não (depende fortemente de recursos avançados)

Comparações de cenários mais específicos:

Cenário	Seleção recomendada	Razão
Software desktop, Aplicativos móveis, Dispositivos IoT	SQLite	Os dados viajam com o dispositivo, sem instalação
Blogs pessoais, Sites de portfólio/institucionais	SQLite	Muita leitura, pouca gravação, economiza custos de manutenção de servidor
Desenvolvimento rápido de protótipos, Demos	SQLite	Basta criar um arquivo para começar
Fóruns comunitários, Plataformas de comércio eletrônico	PostgreSQL	Alta concorrência de gravação, requer bloqueio a nível de linha
Implantação distribuída em múltiplos servidores	PostgreSQL	Precisa compartilhar a fonte de dados entre diferentes máquinas
Sistemas sensíveis como médicos ou financeiros	PostgreSQL	Requer controle estrito de permissões baseado em funções

O seu banco de dados é um bloco de notas de bolso ou uma central telefônica central?

Se os dados são “monomáquina, estáticos, de proprietário único”, escolha o SQLite para desfrutar de extrema leveza e liberdade;

Se os dados são “na nuvem, dinâmicos, altamente interativos”, deixe o PostgreSQL assumir o controle.

A filosofia central do SQLite é “um componente interno da aplicação”, enquanto o PostgreSQL se posiciona como “um centro independente da arquitetura do sistema”.

A próxima vez que tomar uma decisão de arquitetura, não se apresse em sacar o PostgreSQL. Pergunte-se primeiro:

“O meu banco de dados é um bloco de notas de bolso ou uma central telefônica central?”

Quando a resposta estiver clara, a escolha naturalmente se tornará óbvia.