ATTACH DATABASE no SQLite: consultas entre arquivos

Uma conexão, vários arquivos

Uma conexão SQLite não fica presa a um único arquivo. Com ATTACH DATABASE, dá pra abrir outros arquivos .db junto com o que você já tinha aberto e consultar todos como se fossem schemas dentro de um mesmo banco. É o mais perto que o SQLite chega de ter "vários bancos no mesmo servidor".

A forma básica é esta:

ATTACH DATABASE 'archive.db' AS archive;

CREATE TABLE archive.old_orders (
    id INTEGER PRIMARY KEY,
    customer TEXT,
    total REAL
);

INSERT INTO archive.old_orders VALUES (1, 'Rosa', 49.99);

SELECT * FROM archive.old_orders;

O arquivo archive.db é criado caso ainda não exista, exatamente como acontece com o banco principal. Daqui pra frente, dentro dessa sessão, tudo que vier com o prefixo archive. mora nesse segundo arquivo. Já o que estiver com prefixo main. (ou sem prefixo nenhum) continua no banco original.

Toda conexão já vem com dois schemas implícitos: o main (o arquivo que você abriu primeiro) e o temp (uma área de rascunho pra tabelas temporárias). O ATTACH simplesmente adiciona mais schemas a essa lista.

A sintaxe do ATTACH DATABASE e o papel do alias

ATTACH DATABASE 'caminho/para/arquivo.db' AS nome_alias;

O alias é o nome do schema que você vai usar para qualificar as tabelas. Ele é local à conexão atual — outra conexão que anexar o mesmo arquivo pode escolher um alias diferente. Use algo curto e descritivo (archive, analytics, cache), porque você vai digitar bastante.

Alguns pontos que vale a pena saber:

• O caminho é relativo ao diretório de trabalho do processo, a menos que seja absoluto.
• A string ':memory:' anexa um banco em memória novinho sob aquele alias.
• O alias não pode colidir com main nem temp, e não pode se repetir entre anexações.

Fazendo join entre bancos SQLite

Esse é o motivo principal pelo qual a maioria das pessoas usa attach. Com dois arquivos na mesma conexão, dá para fazer join entre as tabelas deles em uma única consulta:

ATTACH DATABASE ':memory:' AS archive;

CREATE TABLE main.customers (id INTEGER PRIMARY KEY, name TEXT);
CREATE TABLE archive.orders (id INTEGER, customer_id INTEGER, total REAL);

INSERT INTO main.customers VALUES (1, 'Rosa'), (2, 'Boris');
INSERT INTO archive.orders VALUES (101, 1, 49.99), (102, 2, 12.50);

SELECT c.name, o.total
FROM main.customers AS c
JOIN archive.orders AS o ON o.customer_id = c.id;

O planejador de consultas trata os dois schemas exatamente como trata as tabelas do main. Índices em tabelas anexadas são utilizados normalmente. EXPLAIN QUERY PLAN funciona entre eles. E não tem ida e volta pela rede — os dois arquivos ficam abertos no mesmo processo.

Isso é realmente útil para separar dados quentes de arquivos frios, isolar arquivos por tenant ou extrair dados de referência de um banco de consulta somente leitura.

Anexar banco SQLite em modo somente leitura ou em memória

Se o segundo banco é algo que você quer apenas ler, sem nunca alterar — um conjunto de dados de referência distribuído junto com a aplicação, por exemplo —, dá para anexar em modo somente leitura usando uma URI:

ATTACH DATABASE 'file:reference.db?mode=ro' AS ref;

A forma com URI exige que a biblioteca do SQLite esteja com SQLITE_OPEN_URI habilitado (o que já é o caso na CLI e na maioria dos bindings de linguagens). A partir daí, qualquer INSERT, UPDATE ou DELETE em ref.* vai disparar um erro antes mesmo de encostar no arquivo.

Anexar bancos em memória também é bem prático para preparar dados temporários:

ATTACH DATABASE ':memory:' AS scratch;

CREATE TABLE scratch.tmp_results AS
SELECT customer_id, SUM(total) AS spend
FROM main.orders
GROUP BY customer_id;

SELECT * FROM scratch.tmp_results ORDER BY spend DESC LIMIT 5;

scratch desaparece quando a conexão é fechada. É parecido com temp, mas o tempo de vida fica nas suas mãos.

Transações abrangem todos os bancos anexados

Um único BEGIN/COMMIT cobre as escritas no main e em qualquer schema anexado. Ou tudo é commitado, ou tudo sofre rollback — a atomicidade é preservada entre os arquivos:

ATTACH DATABASE ':memory:' AS archive;

CREATE TABLE main.orders (id INTEGER PRIMARY KEY, total REAL);
CREATE TABLE archive.orders (id INTEGER PRIMARY KEY, total REAL);

BEGIN;
    INSERT INTO archive.orders SELECT * FROM main.orders WHERE id < 100;
    DELETE FROM main.orders WHERE id < 100;
COMMIT;

Mover linhas de uma tabela ativa para um arquivo de arquivamento é exatamente o tipo de operação em que você quer essa garantia. Sem atomicidade entre arquivos, uma queda no meio do caminho deixaria você com linhas duplicadas ou, pior, com linhas perdidas.

Um detalhe importante: quando mais de um banco anexado está sendo gravado dentro de uma mesma transação, o SQLite adota um protocolo de commit mais cauteloso, que exige um journal temporário. É mais lento do que um commit em arquivo único, mas continua sendo seguro.

Desanexando bancos com DETACH

Quando terminar de usar um banco anexado, basta desanexá-lo com sqlite detach database:

DETACH DATABASE archive;

O arquivo continua intacto no disco — o DETACH apenas fecha o handle na conexão atual. Duas restrições importantes:

• Não dá pra desanexar o main nem o temp.
• Não dá pra desanexar um banco que está dentro de uma transação ou que tem statements abertos.

Se você esquecer de fazer o detach, não é o fim do mundo: ao fechar a conexão, tudo é liberado.

Limites e erros comuns

Alguns limites práticos que vale conhecer:

• O limite padrão é de 10 bancos anexados por conexão (além do main e do temp). O máximo em tempo de compilação é 125. Se estourar, aparece too many attached databases - max 10.
• Cada arquivo anexado consome cache de páginas. Anexar uma dúzia de bancos grandes não sai de graça — o uso de RAM sobe.
• O próprio ATTACH não pode rodar dentro de uma transação. Execute antes do BEGIN ou depois do COMMIT.

Alguns erros que você provavelmente vai encontrar:

-- O arquivo não existe e o diretório não tem permissão de escrita:
Error: unable to open database: 'missing/path.db'

-- Você tentou escrever em um anexo somente leitura:
Error: attempt to write a readonly database

-- Você usou o mesmo alias duas vezes:
Error: database archive is already in use

A maioria desses erros fica óbvia quando você lê com calma. O que mais pega gente desprevenida é o "already in use" — o ATTACH não substitui um alias existente; você precisa dar DETACH antes.

Um padrão na prática: separação hot/cold

Juntando tudo — um pequeno fluxo de arquivamento que tira do banco principal os pedidos com mais de um ano:

ATTACH DATABASE ':memory:' AS archive;

CREATE TABLE main.orders (
    id INTEGER PRIMARY KEY,
    placed_at TEXT,
    total REAL
);
CREATE TABLE archive.orders AS SELECT * FROM main.orders WHERE 0;

INSERT INTO main.orders VALUES
    (1, '2022-06-01', 19.99),
    (2, '2024-11-15', 49.50),
    (3, '2025-08-22', 12.00);

BEGIN;
    INSERT INTO archive.orders
        SELECT * FROM main.orders WHERE placed_at < date('now', '-1 year');
    DELETE FROM main.orders WHERE placed_at < date('now', '-1 year');
COMMIT;

SELECT 'main' AS db, COUNT(*) FROM main.orders
UNION ALL
SELECT 'archive', COUNT(*) FROM archive.orders;

As linhas antigas vão para archive.orders, e as recentes ficam em main. Relatórios que precisam do histórico podem fazer join entre os dois bancos; já as consultas do dia a dia em main.orders continuam rápidas, porque a tabela fica menor. Mesma conexão, dois arquivos, uma única transação.

Próximo passo: Prepared Statements

O ATTACH serve para dar a uma única conexão acesso a mais dados. Os próximos tópicos vão focar em como as aplicações conversam com o SQLite de forma segura e eficiente — começando pelos prepared statements, que são a base do binding de parâmetros e de consultas à prova de SQL injection.