DBWarden
Compilador de esquemas declarativos que deriva migraciones de bases de datos deterministas a partir de modelos SQLAlchemy.
Tus modelos son el código fuente. SQL es la salida.
Cargando últimos commits…
Backends de base de datos
5
Plugins oficiales
7
Archivos de prueba
166
Versión
v0.20.10
Problema
Las herramientas de gestión de esquemas se dividen en dos campos. Las herramientas imperativas le permiten crear cambios: scripts de revisión que describen cómo pasar de una versión de esquema a la siguiente. Las herramientas declarativas le permiten crear el estado deseado y derivar los cambios por usted. La mayoría de las herramientas imprescindibles le piden que mantenga dos representaciones de su esquema: sus modelos ORM y sus archivos de migración. Cuando se desvían, lo descubres en el momento del despliegue.
¿Por qué es difícil?
La deriva del esquema es el enemigo principal. Hacer que esto sea determinista requiere un motor de diferencias que maneje cambios de nombres, cambios de tipos, cambios de restricciones y pedidos en cinco servidores de bases de datos con diferentes dialectos DDL. Cada migración debe incluir tanto la actualización como la reversión SQL, y la reversión debe probarse con la base de datos real.
Capacidades
Análisis de impacto
dbwarden check-impact escanea el código con análisis AST y un fallback de grep, y reporta cada referencia a una columna o tabla que cambia una migración antes del despliegue.
Generación offline
Exporta el estado de los modelos una vez y genera migraciones en CI o en una máquina sin base de datos con make-migrations --offline.
Snapshots de esquema
Cada migración escribe un snapshot JSON con checksum. Los snapshots alimentan la detección de renombres, los diffs offline y las comparaciones a nivel de columna.
Meta tipado
Una metaclase valida cada atributo de class Meta en tiempo de importación; los typos que producirían DDL incorrecto lanzan DBWardenConfigError de inmediato.
Ingeniería inversa
Genera modelos de SQLAlchemy desde una base viva con generate-models, incluyendo metadatos del backend y un import --base personalizado.
Multi-base de datos
Un proyecto puede apuntar a varias bases con configuraciones aisladas, propiedad de tablas por base y bases opcionales que se omiten si faltan.
Flujo de trabajo
- 01
Señalar los modelos existentes.
DBWarden lee sus modelos SQLAlchemy como la única fuente de verdad.
- 02
hacer-migraciones
Genera un esquema de referencia o diferencias con el estado actual de la base de datos.
- 03
Confirmación generada SQL
Archivos simples SQL: revisables, confirmables, ejecutables en cualquier lugar.
- 04
emigrar
Aplica migraciones pendientes con verificación de convergencia.
- 05
Opcional: análisis de impacto, modo fuera de línea, complementos
Detección de cambios importantes basada en AST, CI sin base de datos, integración de semillas/RBAC/FastAPI.
Decisiones clave
SQL-primera salida
Las migraciones son archivos simples SQL. Sin tiempo de ejecución, sin Python generado. Revisable, comprometible y ejecutable en cualquier lugar.
Diferencia determinista
Mismos modelos + misma instantánea = misma migración. Siempre. Sin estados ocultos, sin dependencias de orden.
Contrato de reversión estricto
Cada migración conlleva actualización + reversión SQL. La reversión del marcador de posición se rechaza de forma predeterminada.
Arquitectura de complementos
7 complementos oficiales para semillas, RBAC, FastAPI, pruebas de sandbox y extensiones PostgreSQL/ClickHouse.
Modelo de seguridad
La generación de migraciones clasifica cada operación, divide los cambios de tipo en pasos expand-contract y asigna severidad. La CLI añade límites de ejecución, comprobaciones de planes pendientes e informes de impacto estructurados, para detener un cambio destructivo antes de que llegue a producción.
El historial queda auditable: snapshots con checksum, migraciones repetibles, reconciliación de merges y soporte de rebase. Los rollbacks se generan cuando es seguro; los cambios irreversibles requieren una declaración explícita en lugar de un placeholder.
Restricciones
- No hay tiempo de ejecución de migración para instalar o versión
- No se generan scripts Python que silenciosamente hacen algo incorrecto
- No se descubrió ninguna desviación del esquema en producción
- Migraciones que se pueden generar en CI sin conexión a base de datos
Bases de datos soportadas
| Base de datos | Round-trip | Notas |
|---|---|---|
| PostgreSQL | Full | Columnas identity/generadas, partitioning, herencia, constraints de exclusión, tipos enum e índices avanzados. |
| MySQL | Full | Paridad DDL, opciones de engine/charset/collation, columnas unsigned y on-update. |
| ClickHouse | Full | Familia MergeTree, motores replicados, proyecciones, diccionarios, vistas materializadas e índices skip. |
| SQLite | Full | WITHOUT ROWID/STRICT, columnas generadas y reconstrucción de tablas para ALTER no soportados. |
| MariaDB | Partial | Capa de esquema completa; quedan brechas en snapshots e ingeniería inversa. |
Round-trip significa modelo → SQL → base viva → validación del modelo.
Estado
Alpha estable: pre-1.0 pero listo para producción. Ningún cambio incompatible se publica sin una ventana de deprecación de 3 meses.
Arnés de prueba
El arnés de pruebas dbwarden-harness es un conjunto de validación de caja negra independiente. Instala DBWarden como consumidor, invoca su CLI público, crea instancias de bases de datos reales desechables a través de Testcontainers y verifica que el SQL compilado produzca el esquema correcto. Este no es un conjunto de pruebas unitarias; es un límite de certificación de versión.
Ecosistema
El compilador es el centro de un conjunto de herramientas con versiones independientes.
wlite
CLI + fijacionesGestión declarativa del esquema SQLite sin la sobrecarga Python. La misma filosofía que DBWarden, reducida a lo que SQLite y C pueden hacer solos.
libwlite
biblioteca CEl motor SQLite de DBWarden se extrajo como una biblioteca C independiente. Analiza archivos de modelo .wlite, administra bases de datos, compara esquemas y genera migraciones.
dbwarden-harness
Certificación de lanzamientoValidación de caja negra independiente en cinco bases de datos reales: instalación PyPI, contrato CLI, aplicación de migración, reversión y descubrimiento de complementos.
dbwarden-redis
Bloqueo de migracionesBloqueo distribuido de migraciones con Redis para despliegues concurrentes.
dbwarden-fastapi
Integración webDependencias de sesión FastAPI, health endpoints y rutas de migración.
dbwarden-ch-rbac
RBAC de ClickHouseRoles, usuarios, grants, políticas de fila, cuotas y perfiles de settings para ClickHouse.
dbwarden-pgsql-types
Tipos de PostgresENUMs, dominios, tipos compuestos y secuencias personalizadas.
dbwarden-pgsql-rbac
RBAC de PostgresRoles, grants, privilegios por defecto y políticas de seguridad a nivel de fila.
dbwarden-pgsql-extensions
Extensiones de PostgresExtensiones, event triggers, funciones, triggers y parámetros de almacenamiento.
dbwarden-plugin-template
Plantilla de pluginScaffolding para construir y probar nuevos plugins de DBWarden.
dbwarden-seeds
Datos semillaGestión de seeds por código y archivos con apply y rollback.
dbwarden-sandbox
Pruebas sandboxProveedores Testcontainers para reproducir migraciones de forma segura.
Compensaciones
- Requiere SQLAlchemy 2.0+ (no compatible con modelos heredados)
- La compilación de esquemas agrega un paso de compilación frente a la migración en tiempo de ejecución
- El enfoque declarativo significa menos control sobre las órdenes de migración