O que é SQLite como banco de documentos

SQLite é uma biblioteca de banco de dados embutida. Em vez de depender de um processo de servidor, a aplicação lê e grava um arquivo local usando a própria biblioteca.

A ideia de usá-lo como banco de documentos combina tabelas relacionais com documentos JSON. Uma coluna pode guardar o documento, enquanto as funções JSON do SQLite permitem ler e alterar partes dele com SQL.

O SQLite foi criado por D. Richard Hipp e teve seu primeiro lançamento em 2000. O assunto continua relevante porque equipes pequenas precisam de persistência simples para protótipos, ferramentas locais, testes e aplicações com pouca operação de infraestrutura.

💡
Dica

Pense no SQLite como um arquivo de dados com uma linguagem de consulta completa, não como um banco improvisado.

Como funciona

O documento costuma ser armazenado em uma coluna TEXT. O conteúdo continua sendo JSON, mas o banco pode validar sua estrutura e extrair valores com funções como json_extract.

A consulta combina o modelo familiar de tabelas com caminhos JSON. Assim, você pode filtrar uma linha por um campo interno, ordenar por um valor do documento ou projetar apenas as propriedades necessárias para a tela.

Também é possível construir ou modificar documentos com funções como json_object e json_set. A analogia mais simples é uma gaveta: a tabela organiza as gavetas e o JSON organiza os itens flexíveis dentro de cada uma.

Quando uma lista interna precisa virar linhas, json_each e outras funções de tabela ajudam a percorrer o documento. O ganho é manter o SQL como ponto de encontro entre dados fixos e atributos variáveis.

Principais recursos

O recurso mais útil é a leitura de propriedades internas sem carregar todo o documento para o código da aplicação. Isso reduz lógica duplicada em APIs pequenas e ferramentas de linha de comando.

  • Validação: a função json_valid ajuda a impedir que texto inválido entre na coluna.
  • Extração: json_extract lê valores em caminhos como $.cliente.nome.
  • Atualização: json_set, json_insert e json_remove alteram propriedades sem reconstruir tudo manualmente.
  • Exploração: json_each permite examinar listas e objetos como linhas de uma consulta.

Outro diferencial é a combinação com transações, índices, chaves estrangeiras e o restante do SQL. Você não precisa escolher entre um formato flexível e as garantias básicas de um banco relacional.

O resultado funciona bem quando o documento é parte de uma entidade pequena e o acesso é local ou controlado. Ele fica menos atraente quando muitos clientes precisam escrever ao mesmo tempo ou quando a consulta depende de um catálogo documental enorme.

Como começar: instalação ou acesso passo a passo

Para testar no computador, instale o executável oficial do SQLite ou use um pacote da sua distribuição. Em ambientes Linux e macOS, o comando costuma estar disponível pelo gerenciador de pacotes. No Windows, baixe os binários na página oficial e coloque o executável no PATH.

Crie um banco e uma tabela com uma coluna para o documento. A restrição com json_valid é uma proteção simples contra registros quebrados.

sqlite3 catalogo.db
CREATE TABLE produtos (
  id INTEGER PRIMARY KEY,
  documento TEXT NOT NULL CHECK (json_valid(documento))
);
.quit

Depois, abra o arquivo novamente e insira um documento. O comando a seguir usa json_object para evitar erros de escape no terminal.

sqlite3 catalogo.db
INSERT INTO produtos (documento)
VALUES (json_object('nome', 'Café especial', 'preço', 29.90, 'estoque', 12));
SELECT id, json_extract(documento, '$.nome') AS nome
FROM produtos;
⚠️
Atenção

O comando sqlite3 é uma interface de teste. Em uma aplicação real, use parâmetros na biblioteca da sua linguagem para não montar SQL com entrada do usuário.

Exemplo prático

Imagine uma ferramenta local de catálogo em que produtos compartilham nome e preço, mas cada categoria possui atributos próprios. Um produto de café pode ter origem e torra, enquanto um acessório pode ter material e tamanho.

Os campos comuns continuam no JSON para manter o exemplo compacto. A consulta abaixo encontra produtos com preço até 50 e mostra o nome usando a mesma conexão SQLite.

SELECT
  json_extract(documento, '$.nome') AS nome,
  json_extract(documento, '$.preço') AS preço
FROM produtos
WHERE CAST(json_extract(documento, '$.preço') AS REAL) <= 50
ORDER BY preço;

Se o estoque mudar, atualize somente a propriedade necessária. A transação protege a alteração e mantém o restante do documento intacto.

BEGIN;
UPDATE produtos
SET documento = json_set(documento, '$.estoque', 10)
WHERE id = 1;
COMMIT;

Para depurar um documento, selecione o JSON completo e compare o resultado de json_extract com o valor esperado. Esse passo simples revela rapidamente caminhos escritos de forma incorreta.

Comparação com alternativas

PostgreSQL com JSONB é uma escolha mais forte para uma aplicação de servidor com vários usuários, consultas complexas e necessidade de crescimento operacional. Ele oferece recursos de servidor e de indexação que não fazem parte da proposta do SQLite.

MongoDB faz sentido quando o documento é o centro do modelo e a equipe quer uma plataforma documental distribuída. O SQLite costuma ser mais simples para uma ferramenta local, um produto embarcado ou um serviço pequeno.

Colunas relacionais normais continuam sendo melhores para campos estáveis e usados em filtros frequentes. O JSON entra bem nos atributos variáveis, mas não deve esconder um modelo que já é claramente relacional.

A força específica do SQLite é o equilíbrio entre arquivo único, SQL conhecido, transações e baixa operação. A decisão correta depende principalmente de concorrência, volume, distribuição e necessidade de consultas especializadas.

Pontos positivos e limitações

O primeiro ponto positivo é a simplicidade. Não há serviço separado para instalar em um ambiente local, e o banco pode acompanhar a aplicação como um arquivo versionado ou criado no primeiro uso.

O segundo é a flexibilidade. Um documento pode receber novos atributos sem uma migração de esquema para cada variação, enquanto a aplicação ainda conta com transações e consultas SQL.

A limitação aparece quando a concorrência de escrita aumenta. O SQLite pode atender muitos cenários, mas seu desenho continua voltado para acesso embutido e arquivos locais, não para substituir automaticamente um banco de servidor.

Outra limitação é a modelagem. Se a equipe guardar tudo em JSON, pode perder clareza, validações específicas, relacionamentos e índices adequados. O formato flexível não elimina a necessidade de um modelo bem pensado.

🔴
Cuidado

Não coloque o arquivo do banco em um diretório público nem o trate como um arquivo comum quando houver várias gravações simultâneas.

Casos de uso reais

Uma ferramenta de desktop pode usar SQLite para guardar preferências, cache e dados de trabalho sem exigir que o usuário configure um servidor. JSON ajuda quando as configurações variam por módulo.

Um protótipo de API pode começar com um arquivo local e a mesma linguagem SQL que a equipe usará em testes. Isso acelera a validação da ideia, desde que os limites de concorrência sejam conhecidos.

Aplicações embarcadas e dispositivos com conectividade intermitente também se beneficiam do arquivo local. O documento JSON pode representar eventos ou configurações que serão sincronizados depois por uma camada própria.

Em testes automatizados, cada cenário pode receber um banco temporário com dados pequenos e isolados. A criação rápida facilita a repetição e reduz dependências externas no pipeline.

Dicas e boas práticas

Comece separando os campos que sempre serão filtrados. Eles podem virar colunas próprias, enquanto os atributos realmente variáveis ficam no documento JSON.

💡
Dica

Use CHECK (json_valid(documento)) e valide regras de negócio na aplicação antes de persistir.

Use parâmetros nas consultas e registre migrações para mudanças de formato. Mesmo um arquivo único precisa de backup, política de recuperação e testes de compatibilidade.

🚀
Pro tip

Quando um caminho JSON aparece em muitos filtros, avalie uma coluna derivada ou um índice adequado para o seu padrão de consulta.

Observe o tamanho dos documentos e a frequência de escrita. Se o arquivo começar a concentrar grande volume, muitos escritores ou consultas analíticas, reavalie a arquitetura antes que a migração vire uma urgência.

⚠️
Atenção

Teste bloqueios e recuperação com o mesmo padrão de concorrência esperado em produção. O comportamento local de uma aplicação com um único escritor pode esconder problemas.

Vale a pena?

Sim, quando você precisa de um banco leve, embutido e fácil de distribuir, com documentos pequenos e uma carga de escrita controlada. SQLite com JSON é uma combinação prática para protótipos, ferramentas locais, testes e produtos embarcados.

Talvez não, quando a aplicação depende de muitos escritores remotos, alta disponibilidade distribuída ou consultas documentais muito especializadas. Nesses casos, compare PostgreSQL, MongoDB ou outro serviço de servidor desde o começo.

O próximo passo é criar um pequeno banco, validar os documentos e medir o padrão real de acesso. A arquitetura fica boa quando a flexibilidade do JSON resolve uma variação concreta sem esconder dados que deveriam ser relacionais.