sqlite3.Connection.iterdump() exporta la estructura y los datos de una base SQLite como una secuencia de instrucciones SQL. En versiones recientes de Python, el parámetro filter permite limitar el volcado a objetos cuyos nombres coinciden con un patrón. Esto resulta útil para migraciones parciales, fixtures de pruebas, auditorías, copias selectivas y diagnósticos.
En esta guía aprenderás cómo funciona el filtro, cómo validar el resultado y qué precauciones tomar antes de restaurar el SQL generado.
Qué devuelve iterdump
Al ejecutar conn.iterdump(), Python produce un iterador de cadenas con instrucciones como CREATE TABLE, INSERT y CREATE INDEX.
import sqlite3
with sqlite3.connect("app.db") as conn:
for linea in conn.iterdump():
print(linea)
Como el resultado es un iterador, puedes escribirlo directamente en un archivo. Para ampliar conceptos, consulta la guía sobre sqlite3 en Python y el artículo sobre context managers en Python.
Cómo funciona filter
El argumento filter usa un patrón similar a LIKE de SQLite. El símbolo % representa cualquier secuencia de caracteres y _ representa un carácter.
with sqlite3.connect("app.db") as conn:
for linea in conn.iterdump(filter="cliente%"):
print(linea)
Este patrón puede incluir tablas como clientes, clientes_direcciones e índices relacionados.
Ejemplo completo
import sqlite3
conn = sqlite3.connect(":memory:")
conn.executescript("""
CREATE TABLE clientes (
id INTEGER PRIMARY KEY,
nombre 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(nombre) VALUES ('Ana'), ('Carlos');
INSERT INTO pedidos(cliente_id, total) VALUES (1, 120.50);
""")
lineas = list(conn.iterdump(filter="clientes%"))
print("\n".join(lineas))
Para guardar el resultado:
with sqlite3.connect("app.db") as conn, open(
"clientes.sql", "w", encoding="utf-8"
) as archivo:
for linea in conn.iterdump(filter="clientes%"):
archivo.write(linea + "\n")
Patrones útiles
usuario%: objetos que empiezan por usuario.%log%: objetos que contienen log.tmp_%: objetos con un prefijo temporal.reporte_202_: nombres con un carácter variable al final.
Una convención consistente de nombres facilita los volcados selectivos y mejora la organización de migraciones.
Validar antes de restaurar
No debes asumir que el filtro incluyó todas las dependencias. Restaura primero en una base temporal.
def validar_dump(lineas: list[str]) -> None:
prueba = sqlite3.connect(":memory:")
prueba.executescript("\n".join(lineas))
prueba.close()
También conviene consultar sqlite_master:
objetos = prueba.execute(
"SELECT type, name FROM sqlite_master ORDER BY type, name"
).fetchall()
Dependencias entre objetos
Una tabla incluida puede depender de otra tabla, vista o trigger que no coincida con el patrón. Revisa claves foráneas con PRAGMA foreign_key_list, inspecciona triggers y documenta relaciones entre módulos.
Para scripts de mantenimiento robustos, revisa manejo de excepciones en Python y logging en Python.
Seguridad
Un archivo de dump contiene SQL ejecutable. No restaures archivos de fuentes desconocidas. Revisa las instrucciones, limita permisos y usa un entorno aislado.
from hashlib import sha256
from pathlib import Path
contenido = Path("clientes.sql").read_bytes()
print(sha256(contenido).hexdigest())
Consulta la documentación oficial de sqlite3 en Python y la referencia de SQL de SQLite.
Compatibilidad de versiones
Comprueba si la versión desplegada admite filter. En proyectos compatibles con intérpretes antiguos, documenta una versión mínima o implementa un fallback controlado.
import inspect
import sqlite3
firma = inspect.signature(sqlite3.Connection.iterdump)
if "filter" in firma.parameters:
lineas = conn.iterdump(filter="clientes%")
else:
lineas = conn.iterdump()
Filtrar después un dump textual completo puede ser frágil porque las instrucciones pueden ocupar varias líneas y las dependencias no siempre son evidentes.
Consistencia con escrituras concurrentes
El dump debe representar un estado coherente. Si la aplicación sigue escribiendo, coordina la operación con una transacción o una ventana de mantenimiento. En bases grandes o activas, evalúa la API de backup de SQLite.
Guarda junto al archivo la fecha, la versión de la aplicación, la versión del esquema, Python y SQLite.
Pruebas automatizadas
Una prueba fiable crea una base de origen, genera el dump filtrado, lo restaura y verifica filas y objetos esperados.
def restaurar_y_verificar(lineas):
destino = sqlite3.connect(":memory:")
destino.executescript("\n".join(lineas))
total = destino.execute(
"SELECT COUNT(*) FROM clientes"
).fetchone()[0]
assert total == 2
destino.close()
Incluye pruebas con patrones sin coincidencias, guiones bajos, vistas, índices, triggers y claves foráneas.
Buenas prácticas
- Usa patrones específicos.
- Restaura primero en una base temporal.
- Revisa claves foráneas, vistas, índices y triggers.
- Registra versiones y metadatos del esquema.
- Trata el dump como código ejecutable.
- Mantén copias completas además de exportaciones parciales.
- Automatiza controles de integridad.
Cuándo conviene usarlo
Los dumps filtrados son adecuados para fixtures, depuración por módulo, migraciones controladas, demostraciones y pruebas. No deben ser el único mecanismo de backup de una base de producción compleja.
Conclusión
El parámetro filter de sqlite3.Connection.iterdump() permite exportar objetos seleccionados de SQLite desde Python. Reduce ruido y facilita tareas específicas.
Sin embargo, filtrar nombres no incluye automáticamente todas las dependencias. Valida el SQL, restaura en aislamiento, revisa relaciones y conserva backups completos. Con estas precauciones, el recurso es una herramienta práctica para flujos de trabajo con SQLite.
