O método sqlite3.Connection.iterdump() permite exportar a estrutura e os dados de um banco SQLite como uma sequência de comandos SQL. Em versões recentes do Python, o parâmetro filter torna esse recurso ainda mais útil porque permite limitar o dump a objetos cujo nome corresponde a um padrão. Isso ajuda em migrações parciais, auditorias, testes, backups seletivos e diagnósticos sem precisar exportar todo o banco.
Neste guia, você vai aprender como funciona o filtro do iterdump, como combinar padrões, como validar o resultado e quais cuidados tomar antes de restaurar o SQL gerado. O foco é usar o recurso de maneira previsível, segura e adequada para bancos reais.
O que o iterdump faz
Ao chamar conn.iterdump(), o Python percorre o catálogo interno do SQLite e produz instruções como CREATE TABLE, INSERT, CREATE INDEX e outros comandos necessários para reconstruir o banco. O retorno é um iterador de strings, o que significa que você pode processar o dump linha por linha sem carregar tudo na memória.
import sqlite3
with sqlite3.connect("app.db") as conn:
for linha in conn.iterdump():
print(linha)
Essa abordagem é prática para bancos pequenos e médios e também pode ser integrada a pipelines de backup. Para conhecer melhor a base da biblioteca, veja o artigo sobre sqlite3 no Python. Também vale revisar context managers no Python para fechar conexões corretamente.
Como funciona o parâmetro filter
O parâmetro filter aceita um padrão aplicado aos nomes dos objetos do banco. Ele segue a lógica do operador LIKE do SQLite. Assim, o caractere % representa qualquer sequência de caracteres e _ representa um único caractere.
with sqlite3.connect("app.db") as conn:
for linha in conn.iterdump(filter="cliente%"):
print(linha)
Nesse exemplo, o dump tende a incluir objetos cujo nome começa com cliente, como clientes, clientes_enderecos e índices associados. Isso é especialmente útil quando o banco agrupa tabelas por prefixo.
Exemplo prático com banco de testes
import sqlite3
conn = sqlite3.connect(":memory:")
conn.executescript("""
CREATE TABLE clientes (
id INTEGER PRIMARY KEY,
nome TEXT NOT NULL
);
CREATE TABLE clientes_tags (
cliente_id INTEGER,
tag TEXT
);
CREATE TABLE pedidos (
id INTEGER PRIMARY KEY,
cliente_id INTEGER,
total REAL
);
INSERT INTO clientes(nome) VALUES ('Ana'), ('Carlos');
INSERT INTO pedidos(cliente_id, total) VALUES (1, 120.50);
""")
linhas = list(conn.iterdump(filter="clientes%"))
print("\n".join(linhas))
O resultado permite inspecionar somente a parte do esquema relacionada aos clientes. Como o retorno é um iterador, você pode escrever diretamente em arquivo:
with sqlite3.connect("app.db") as conn, open(
"clientes.sql", "w", encoding="utf-8"
) as arquivo:
for linha in conn.iterdump(filter="clientes%"):
arquivo.write(linha + "\n")
Filtros úteis
Alguns padrões comuns são:
usuario%: objetos que começam com usuario;%log%: objetos que contêm log;tmp_%: objetos temporários ou auxiliares por convenção;relatorio_202_: nomes com um único caractere na última posição.
O uso de uma convenção de nomes consistente facilita muito os dumps seletivos. Isso também melhora a organização de migrações e scripts de manutenção.
Validando o conteúdo do dump
Nunca assuma que um filtro gerou exatamente o conjunto esperado. Antes de usar o arquivo em outro ambiente, revise os comandos produzidos e teste a restauração em um banco temporário.
def validar_dump(sql_linhas: list[str]) -> None:
banco_teste = sqlite3.connect(":memory:")
script = "\n".join(sql_linhas)
banco_teste.executescript(script)
banco_teste.close()
Além de verificar erros de sintaxe, consulte sqlite_master no banco restaurado para confirmar as tabelas e índices criados.
with sqlite3.connect(":memory:") as teste:
teste.executescript(script)
objetos = teste.execute(
"SELECT type, name FROM sqlite_master ORDER BY type, name"
).fetchall()
print(objetos)
Dependências entre tabelas
Um dump parcial pode não conter tudo o que uma tabela precisa. Uma tabela filtrada pode depender de outra por chave estrangeira, trigger ou view. O SQLite pode aceitar parte do script, mas a aplicação poderá falhar depois.
Antes de exportar, mapeie relacionamentos com PRAGMA foreign_key_list, consulte triggers e views e documente as dependências. Para reforçar o tema, consulte tratamento de erros no Python e logging no Python.
Segurança ao restaurar
Um arquivo de dump é código SQL executável. Não restaure arquivos recebidos de fontes desconhecidas. Revise o conteúdo, limite permissões do processo e restaure primeiro em um ambiente isolado.
Mesmo em ambientes internos, proteja o arquivo contra alterações indevidas. Você pode calcular um hash SHA-256 e armazená-lo junto do backup:
from hashlib import sha256
from pathlib import Path
conteudo = Path("clientes.sql").read_bytes()
print(sha256(conteudo).hexdigest())
Para práticas gerais de segurança, consulte a documentação oficial do sqlite3 no Python e a documentação do SQL do SQLite.
Compatibilidade entre versões
Antes de usar filter, confirme a versão do Python disponível no ambiente. Em projetos que precisam funcionar em versões mais antigas, crie um fallback. Uma opção é gerar o dump completo e filtrar com cuidado, embora isso seja menos confiável porque os comandos podem ocupar várias linhas e ter dependências.
import inspect
import sqlite3
assinatura = inspect.signature(sqlite3.Connection.iterdump)
if "filter" in assinatura.parameters:
linhas = conn.iterdump(filter="clientes%")
else:
linhas = conn.iterdump()
Em bibliotecas distribuídas para terceiros, documente a versão mínima do Python e adicione testes de compatibilidade.
Backups consistentes
O iterdump é útil, mas não substitui automaticamente todas as estratégias de backup. Em bancos grandes ou muito ativos, avalie a API de backup do SQLite, snapshots do sistema de arquivos ou ferramentas operacionais específicas. Garanta que o dump represente um estado consistente e evite alterações concorrentes durante a exportação.
Uma abordagem simples é abrir uma transação de leitura, gerar o dump e registrar o horário, a versão do aplicativo e a versão do esquema.
Boas práticas
- Use padrões específicos para evitar incluir objetos demais.
- Teste a restauração em banco temporário.
- Verifique dependências entre tabelas, views e triggers.
- Registre a versão do Python e do SQLite.
- Proteja o arquivo de dump como código executável.
- Não use dumps parciais como única forma de backup.
- Automatize testes de integridade após a restauração.
Conclusão
O parâmetro filter de sqlite3.Connection.iterdump() transforma o dump do SQLite em uma ferramenta mais seletiva. Ele é útil para exportar grupos de tabelas, preparar fixtures, investigar módulos específicos e reduzir o volume de dados em tarefas controladas.
O principal cuidado é lembrar que nomes filtrados não eliminam dependências. Valide o SQL, teste a restauração, revise relações e mantenha uma estratégia completa de backup. Com essas precauções, o recurso se torna uma opção simples e poderosa para manutenção de bancos SQLite em Python.
