Flujos seguros de migración de bases de datos para agentes de programación con IA

Los cambios en bases de datos de producción necesitan un flujo distinto al de las ediciones de código habituales. Un agente de programación con IA puede inspeccionar un esquema, rastrear las consultas de la aplicación y preparar archivos de migración más rápido de lo que la mayoría de los equipos tarda en programar una revisión. Esa velocidad no debe convertirse en permiso para modificar producción solo porque un prompt incluya la palabra «deploy».

Los flujos seguros de migración separan la planificación de la autoridad. El agente puede preparar pruebas y un conjunto de cambios preciso. Una persona puede revisar las consecuencias operativas, demostrar que la recuperación funciona y aprobar una única ejecución acotada. Esta separación evita el fallo conocido en el que un ALTER TABLE aparentemente inofensivo termina bloqueando el proceso de pago, provoca una reescritura descontrolada o deja un despliegue a medias que nadie sabe explicar.

Este artículo utiliza comandos de PostgreSQL porque su comportamiento respecto a bloqueos y transacciones está descrito con claridad en su documentación. El flujo también sirve para otras bases de datos relacionales, pero no copies la sintaxis ni las suposiciones de PostgreSQL en otro motor sin consultar antes su manual.

Los cambios en producción necesitan una autoridad separada de la generación de código

Un archivo de migración y una migración en producción son actos distintos. El primero describe una intención. El segundo utiliza una autoridad limitada contra un sistema activo, con usuarios, réplicas, copias de seguridad y versiones de la aplicación que pueden no coincidir.

Los equipos suelen cometer el error de conceder a un agente una conexión amplia a la base de datos porque facilita el desarrollo local. Esa conexión acaba cruzando entornos, y el agente no puede distinguir un nombre de host de pruebas de un clúster de producción si ambos aceptan las mismas credenciales. Peor aún, un agente que puede ejecutar SQL arbitrario no tiene un motivo natural para detenerse antes de reescribir una tabla. Solo ve una tarea y una herramienta.

Divide el trabajo en fases distintas, con entradas y permisos diferentes:

1. El descubrimiento lee los metadatos del esquema, el historial de migraciones, el código de las consultas y las restricciones operativas.
2. La planificación produce SQL, el comportamiento esperado de los bloqueos, los efectos sobre los datos, las comprobaciones previas, las consultas de verificación y una decisión de recuperación.
3. La revisión confirma que el plan coincide con el estado real de producción y que la organización acepta el riesgo.
4. La ejecución aplica un artefacto aprobado a un único destino identificado.
5. La verificación demuestra que la aplicación y la base de datos alcanzaron el estado previsto antes de dar por terminado el despliegue.

La distinción útil es entre reversibilidad y capacidad de recuperación. Añadir una columna que admita valores nulos suele ser reversible: una sentencia posterior puede eliminarla si ningún código depende de ella. Actualizar millones de filas con una expresión defectuosa puede no ser reversible, aunque alguien escriba una actualización aparentemente inversa. Es posible que no sepas qué valores originales se sobrescribieron. La capacidad de recuperación significa que tienes una forma probada de restaurar o contener el daño. Trata ambos conceptos como campos separados en cada plan de migración.

Un agente nunca debe deducir autoridad sobre producción a partir de una rama del repositorio, una etiqueta de ticket o una variable de entorno proporcionada en un prompt. Esas señales describen una intención, y la intención suele ser incorrecta. La ejecución debe exigir un destino seleccionado fuera del contexto textual del agente, un artefacto preparado cuyo resumen se haya registrado y una persona que vea exactamente qué se ejecutará.

Convierte el plan de migración en un artefacto revisable

Un plan revisable ofrece al operador información suficiente para rechazar una migración antes de que llegue a la base de datos. «Añadir un índice» no es un plan. El tamaño de la tabla, el objetivo de la consulta, la forma del índice, la restricción transaccional, la exposición a bloqueos y la consulta de verificación sí lo convierten en un plan.

Pide al agente que produzca un directorio con archivos fijos en lugar de un párrafo en una solicitud de cambios. Por ejemplo:

migrations/2025-04-add-orders-status-index/
  up.sql
  verify.sql
  preflight.sql
  recovery.md
  manifest.json

El manifiesto debe vincular los archivos con el destino previsto e indicar qué descubrió el agente. Este ejemplo no expone credenciales ni afirma que exista una copia de seguridad solo porque alguien la haya solicitado.

{
  "migration_id": "2025-04-add-orders-status-index",
  "engine": "postgresql",
  "target": "production-orders",
  "change": "create index for filtered order status query",
  "transaction_mode": "outside_transaction",
  "requires_backup_restore_check": true,
  "expected_write_blocking": "none during index build",
  "stop_conditions": [
    "target schema differs from preflight result",
    "backup restore check fails",
    "index is invalid after execution"
  ]
}

Una persona que revise el cambio debería poder responder cinco preguntas a partir de este artefacto:

• ¿Qué base de datos y qué esquema recibirán el cambio?
• ¿Qué SQL exacto se ejecutará y el ejecutor lo envolverá en una transacción?
• ¿Qué operación bloqueará, reescribirá, analizará o consumirá espacio adicional?
• ¿Qué pruebas demuestran que la base de datos puede recuperarse si algo sale mal?
• ¿Qué consultas o señales de la aplicación demuestran que todo ha funcionado?

Exige que el agente indique sus incertidumbres. Si no puede establecer la versión de PostgreSQL, el tamaño de la tabla, la versión actual de la migración o el rango de compatibilidad de la aplicación que realiza las llamadas, debe expresarlo como una condición de parada. Inventar confianza a partir de un acceso parcial al repositorio es peor que dejar un punto abierto.

Mantén el SQL generado inmutable después de la revisión. Si una persona modifica up.sql, vuelve a generar la suma de comprobación y envía otra vez el artefacto a revisión. Un fallo habitual comienza con una migración revisada y continúa con una apresurada «pequeña corrección» en el shell de despliegue. El comando real deja de ser el comando revisado, y el registro de auditoría cuenta una historia tranquilizadora pero falsa.

Clasifica la operación antes de decidir cómo ejecutarla

El verbo SQL no dice lo suficiente sobre el riesgo operativo. ALTER TABLE incluye cambios que terminan rápidamente y otros que mantienen bloqueos o reescriben tantos datos que agotan el almacenamiento. Un flujo seguro clasifica la operación concreta, la versión de la base de datos, el tamaño de la tabla y la carga simultánea antes de asignarle una ruta de ejecución.

La documentación de ALTER TABLE de PostgreSQL deja clara la parte incómoda: muchas formas adquieren un bloqueo ACCESS EXCLUSIVE salvo que el manual indique lo contrario. Ese bloqueo entra en conflicto con las lecturas y las escrituras. «En pruebas funcionó rápido» dice poco si el entorno de pruebas no tiene transacciones largas, tráfico de informes ni una fracción de los datos.

Usa cuatro categorías prácticas:

No llames segura a toda operación que se ejecute en línea. CREATE INDEX CONCURRENTLY de PostgreSQL evita bloquear las escrituras durante la creación, tal como se documenta en CREATE INDEX. También tarda más, no puede ejecutarse dentro de un bloque de transacción y puede dejar un índice no válido después de un fallo. El consejo popular de «usar siempre concurrently» pasa por alto esas condiciones. Úsalo cuando la disponibilidad de escritura sea importante y tu ejecutor de migraciones pueda respetar sus reglas.

Una consulta de planificación puede dar al revisor una primera estimación útil del tamaño de la tabla y de los índices:

SELECT
  pg_size_pretty(pg_total_relation_size('public.orders')) AS total_size,
  pg_size_pretty(pg_relation_size('public.orders')) AS table_size,
  pg_size_pretty(pg_indexes_size('public.orders')) AS indexes_size;

El resultado esperado tiene una fila con tres valores de tamaño legibles. Considéralo una señal para estimar el tamaño, no una promesa sobre la duración. El tamaño de las filas, el estado de la caché, las escrituras simultáneas, la replicación, el rendimiento del disco y las transacciones activas cambian el resultado.

El agente también debería inspeccionar los bloqueadores antes de una operación con una exposición importante a bloqueos. PostgreSQL muestra las sesiones activas en pg_stat_activity; eso no te da permiso para terminarlas. El plan debe identificar al responsable de cualquier carga de larga duración y especificar si la migración espera, se reprograma o se ejecuta durante una ventana de mantenimiento.

Una copia de seguridad restaurada es el requisito de entrada

Un comando de copia de seguridad ejecutado correctamente demuestra que un programa escribió un archivo. No demuestra que el archivo se restaure, que contenga los objetos necesarios ni que el procedimiento de restauración funcione bajo presión. Haz una comprobación de restauración antes de realizar un trabajo destructivo o difícil de revertir.

Para una base de datos de PostgreSQL, un volcado lógico en formato personalizado puede tener este aspecto:

pg_dump -Fc -d "$SOURCE_DATABASE" -f "orders-preflight.dump"
pg_restore -l "orders-preflight.dump" | sed -n '1,12p'
createdb migration_restore_check
pg_restore -d migration_restore_check "orders-preflight.dump"
psql -d migration_restore_check -c "SELECT count(*) FROM public.orders;"

El comando de listado debería mostrar entradas del archivo, como la definición de una tabla, una entrada de datos de tabla y definiciones de índices. La consulta final debería mostrar un resultado de una columna con el número de filas restauradas. Registra el resultado del comando, el identificador del volcado, el destino de restauración y el resultado de la comprobación en el registro de migración. No incluyas direcciones de bases de datos ni contraseñas en ese registro.

Una comprobación de restauración lógica no sustituye una prueba de recuperación física, una recuperación a un momento dado, un simulacro de promoción de una réplica ni la garantía de copias de seguridad de un proveedor. Responde a una pregunta más concreta: ¿este volcado puede restaurarse en una base de datos y producir los objetos y la estructura de datos esperados? Esa respuesta limitada aún detecta archivos dañados, extensiones ausentes, problemas de roles y procedimientos que solo funcionaban en el portátil de quien los escribió.

Elige el método de recuperación antes de ejecutar, no después de un error. El plan debe indicar cuál de estas opciones se aplica:

• Una migración inversa es segura porque no se han descartado datos y la aplicación tolera la reversión.
• La ruta de recuperación es restaurar en una base de datos de reemplazo, con una persona responsable de decidir el cambio de destino.
• La ruta es un procedimiento de recuperación de una réplica o de un proveedor, con un objetivo de punto de recuperación documentado.
• El cambio no puede recuperarse limpiamente, por lo que necesita una ventana de mantenimiento y una aceptación explícita del riesgo.

La última categoría es legítima. Fingir que existe una recuperación porque la plantilla de despliegue exige rellenar ese campo no lo es. He visto equipos escribir DROP COLUMN como recuperación para un relleno que había cambiado datos de clientes, y después descubrir que eliminar la columna nueva solo borraba sus pruebas mientras los valores antiguos seguían siendo incorrectos.

Expande primero y elimina después

La mayoría de los cambios de esquema que afectan a la aplicación deben mantener la compatibilidad entre versiones mezcladas. Durante un despliegue, los procesos antiguos y nuevos pueden ejecutarse al mismo tiempo porque los trabajadores tardan en terminar, los usuarios mantienen abiertas sus solicitudes o una recuperación reinicia una versión anterior. Una migración que presupone una única versión instantánea de la aplicación convierte el comportamiento normal de un despliegue en una interrupción.

Supón que necesitas sustituir orders.status_text por un orders.status_code restringido. La versión insegura añade la nueva columna, reescribe todas las filas, cambia el código de la aplicación y elimina la columna antigua en una sola versión. Tiene varios puntos de fallo y ningún lugar tranquilo donde detenerse.

Usa una secuencia de expansión y contracción:

1. Añade status_code como columna que admita nulos y agrega estructuras de apoyo que no rompan la aplicación actual.
2. Despliega código que lea el nuevo campo cuando esté presente y escriba ambos campos, o que derive uno de forma segura a partir del otro.
3. Rellena las filas existentes en lotes acotados y registra el progreso fuera del contexto temporal del chat del agente.
4. Comprueba que todas las filas cumplen la nueva condición y que los lectores utilizan el nuevo campo.
5. En una versión posterior, deja de escribir el campo antiguo, espera el periodo de retención acordado y elimínalo.

El bucle por lotes es importante. Un único UPDATE gigante mantiene los recursos ocupados durante demasiado tiempo, genera un pico de registros de escritura anticipada, somete a las réplicas a presión y dificulta razonar sobre la recuperación. Una consulta acotada ofrece al operador un punto entre confirmaciones para examinar el retraso de replicación, la tasa de errores y la carga de la base de datos.

Este patrón de PostgreSQL actualiza un lote seleccionado por clave primaria y devuelve las filas modificadas:

WITH batch AS (
  SELECT id
  FROM public.orders
  WHERE status_code IS NULL
  ORDER BY id
  FOR UPDATE SKIP LOCKED
  LIMIT 500
)
UPDATE public.orders AS o
SET status_code = CASE o.status_text
  WHEN 'new' THEN 10
  WHEN 'paid' THEN 20
  WHEN 'shipped' THEN 30
  ELSE NULL
END
FROM batch
WHERE o.id = batch.id
RETURNING o.id;

El ejecutor repite esta operación mientras haya filas devueltas y mientras la correspondencia produzca valores aceptables. SKIP LOCKED puede ser adecuado para un trabajador controlado porque evita esperar a las filas retenidas por otra transacción. No demuestra que se hayan procesado todas las filas. La consulta de verificación debe comprobar si quedan valores nulos y si existen valores de origen inesperados:

SELECT status_text, count(*)
FROM public.orders
WHERE status_code IS NULL
GROUP BY status_text
ORDER BY count(*) DESC;

Si la consulta devuelve un valor desconocido, detente. No permitas que un agente decida que un estado de producción inesperado puede convertirse en un valor de enumeración predeterminado solo porque quiere terminar la tarea.

La ejecución necesita condiciones de parada estrictas y comandos acotados

Una migración aprobada aún puede encontrarse con un estado de producción distinto al que inspeccionó el planificador. El ejecutor debe realizar comprobaciones previas inmediatamente antes de la ejecución y detenerse cuando no coincidan. Aquí es donde un flujo resulta más seguro que un procedimiento que alguien sigue de memoria.

Usa un ejecutor específico que acepte únicamente un identificador de artefacto y un selector de destino. Debe rechazar SQL insertado directamente desde un terminal, rechazar un artefacto cuya suma de comprobación haya cambiado y mostrar la identidad del destino antes de comenzar. Puede ejecutar primero SQL de comprobación previa en modo de solo lectura y después exigir una aprobación separada para la parte que modifica datos.

Establece explícitamente los límites de tiempo de la sesión. PostgreSQL documenta lock_timeout y statement_timeout como controles independientes. El primero cancela la espera para adquirir un bloqueo; el segundo cancela una sentencia que tarda demasiado. Un preámbulo razonable para una operación breve sobre metadatos podría ser:

SET lock_timeout = '5s';
SET statement_timeout = '60s';
SELECT current_database(), current_user, now();

No traslades esos valores sin más a creaciones de índices o rellenos de datos. Un tiempo de espera es un presupuesto que el plan debe justificar. Si el comando necesita treinta minutos con la carga prevista, un límite de sesenta segundos solo crea un fallo predecible. Para crear un índice de forma concurrente, usa una ruta del ejecutor que no envuelva el comando en una transacción:

CREATE INDEX CONCURRENTLY IF NOT EXISTS orders_status_code_idx
ON public.orders (status_code);

Después de este comando, verifica el índice en lugar de asumir que tuvo éxito porque el proceso terminó correctamente. PostgreSQL registra su validez en los metadatos del catálogo, y una creación concurrente fallida puede dejar un índice no válido que tendrás que inspeccionar y eliminar antes de volver a intentarlo. Incluye esa comprobación en verify.sql, junto con un plan de consulta orientado a la aplicación cuando corresponda.

Una decisión real de abortar necesita señales identificadas. Detén la ejecución si la comprobación previa encuentra una versión de migración inesperada, espacio libre insuficiente, un bloqueador activo fuera de la ventana permitida, una restauración de copia fallida, una suma de comprobación incorrecta o un resultado que difiera del predicado de verificación. El operador no debería tener que negociar con un agente mientras crece la espera por un bloqueo.

La aprobación debe vincular a una persona con una única ejecución real

La fatiga de aprobación aparece cuando los sistemas piden aprobar cada llamada SQL. Las personas terminan aprobando por inercia o desactivan los prompts. Una sola aprobación al comienzo de un proceso de agente definido resulta útil cuando identifica el proceso, caduca al terminarlo y no cubre silenciosamente otra sesión posterior.

La aprobación debe mostrar suficiente contexto para que una persona pueda rechazar la ejecución: la identidad firmada del proceso, el destino seleccionado, el identificador del artefacto, la clase de acción prevista y si el canal de acción puede escribir. No debe mostrar una contraseña sin procesar ni exigir que el agente la maneje. La persona autoriza la acción, no la divulgación del secreto.

Sallyport encaja en este límite porque mantiene las credenciales API y SSH en su almacén cifrado, permite que un agente compatible con MCP solicite acciones mediante sp mcp y devuelve los resultados de las acciones en lugar de secretos en texto claro. Su aprobación de sesión independiente y la aprobación opcional por clave pueden hacer que una acción sobre una base de datos de producción requiera una decisión humana sin colocar una credencial reutilizable en el contexto del agente.

Mantén la aprobación limitada a la fase de ejecución. El agente de descubrimiento puede utilizar una ruta de solo lectura. El agente de ejecución puede recibir una sesión que caduque con su proceso y acceder únicamente a la ruta de acción aprobada. La revocación inmediata importa porque el operador necesita una forma de detener una ejecución después de un resultado previo inesperado, no solo cuando termina el script de despliegue.

No sustituyas un diseño operativo claro por un lenguaje de políticas que tu equipo no pueda explicar bajo presión. El límite fiable es sencillo: el acceso bloqueado deniega todas las acciones, un nuevo proceso de ejecución necesita autorización y las credenciales especialmente sensibles pueden exigir una decisión nueva en cada uso. Es más fácil de auditar que un conjunto de reglas inferidas que nadie recuerda haber escrito.

Los registros de auditoría deben reconstruir el cambio sin secretos

Después de una migración fallida, las preguntas son sencillas: quién la ejecutó, contra qué destino, qué artefacto exacto se ejecutó, cuándo se detuvo y si modificó datos. Un registro genérico del terminal rara vez responde a todo. Puede omitir el destino, perder el comando después de limpiar el historial del shell o incluir secretos que nunca deberían haberse registrado.

Registra eventos estructurados para la planificación, la aprobación, la comprobación previa, la ejecución, la verificación, la revocación y el fallo. Cada evento debe incluir el identificador de la migración y el resumen del artefacto para que un investigador pueda vincular la revisión con la ejecución real. Incluye la identidad de la base de datos devuelta por la comprobación previa, no solo el nombre solicitado por quien hizo la llamada.

Una estructura mínima de evento podría ser esta:

{
  "event": "migration.verify",
  "migration_id": "2025-04-add-orders-status-index",
  "artifact_sha256": "recorded-digest",
  "target_identity": "production-orders",
  "result": "passed",
  "observed": "index valid; query returned expected columns"
}

Evita registrar parámetros SQL cuando puedan contener datos personales, tokens o contenido de clientes. Registra en su lugar el resumen del artefacto y un identificador de sentencia seguro. El sistema de ejecución puede conservar diagnósticos protegidos durante un periodo definido, pero el diario de auditoría debe seguir siendo útil sin convertirse en otro almacén de secretos.

La evidencia de manipulación cambia la calidad de una investigación. Un registro que alguien puede editar después de un mal despliegue solo demuestra que alguien tenía acceso a él. Si utilizas un registro de auditoría encadenado mediante hashes, verifícalo de forma independiente durante la revisión del incidente. sp audit verify de Sallyport comprueba sin conexión su cadena de auditoría cifrada sin necesitar acceso al almacén. Esa es la propiedad adecuada para un revisor que no debería recibir credenciales de producción.

La verificación debe probar la carga de trabajo, no solo el DDL

Una migración tiene éxito cuando la carga de trabajo prevista funciona correctamente, no cuando la base de datos acepta una sentencia. Una columna nueva puede existir mientras las escrituras de la aplicación la omiten. Un índice puede ser válido mientras la consulta objetivo no pueda utilizarlo porque su predicado o su tipo de datos difieren. Una restricción puede validarse mientras un trabajador antiguo sigue enviando datos que incumplen el nuevo contrato de la aplicación.

Escribe las consultas de verificación antes de ejecutar, mientras los revisores aún pueden cuestionar sus supuestos. Para una migración de índices, comprueba el estado del catálogo e inspecciona la consulta que la motivó. Para un relleno de datos, cuenta las filas restantes, agrupa los valores de origen inesperados y confirma que la nueva ruta de escritura de la aplicación produce la representación esperada. Para una restricción, prueba escrituras válidas e inválidas en una base de datos desechable antes de pedir a producción que la aplique.

EXPLAIN de PostgreSQL es útil, pero se presta a errores. La decisión del planificador depende de las estadísticas, los valores de los parámetros, la distribución de los datos y la configuración. EXPLAIN (ANALYZE, BUFFERS) ejecuta la consulta y la mide, así que no lo dirijas sin cuidado a una consulta costosa de producción. Úsalo con una consulta segura y representativa, y define un resultado aceptable antes de ver la salida. De lo contrario, cualquier plan se convierte en algo que un operador cansado puede justificar.

Observa los indicadores de la aplicación durante y después del cambio: tasa de errores de las solicitudes, latencia de las consultas del flujo afectado, presión sobre las conexiones, estado de la replicación y fallos de los trabajadores. El agente puede recopilar y presentar esas lecturas, pero la persona responsable del lanzamiento decide si cumplen la condición de salida establecida.

No programes la contracción destructiva solo porque el despliegue de expansión haya pasado. Espera hasta que la observabilidad y el historial de versiones demuestren que ningún proceso antiguo de la aplicación depende ya del esquema anterior. Después ejecuta la eliminación como una migración revisada independiente. Ese cambio adicional cuesta menos que descubrir durante una recuperación que la versión antigua esperaba una columna que eliminaste una hora antes.

La primera ejecución en producción debe ser deliberadamente aburrida

La primera migración en producción asistida por un agente debe añadir un cambio de bajo riesgo y fácil de observar, no rediseñar una tabla bajo carga. Elige una columna adicional que admita nulos, un comentario u otra operación cuyo comportamiento ya conozcas. Úsala para probar los límites: generación del artefacto, selección del destino, aprobación, pruebas de la copia de seguridad, eventos de auditoría, fallo de la comprobación previa, ejecución y verificación.

Haz que el ejercicio demuestre que el sistema sabe rechazar trabajo. Apunta el ejecutor a un destino con una huella de esquema incorrecta y confirma que se detiene. Modifica el archivo revisado y confirma que la comprobación del resumen lo rechaza. Revoca la autorización durante una ejecución de prueba inofensiva y confirma que las acciones posteriores fallan. Estas pruebas muestran si los controles funcionan cuando alguien los necesita, en lugar de limitarse a parecer razonables en un documento de diseño.

Después, amplía las clases de migración permitidas de una en una. Un equipo que puede añadir una columna de forma segura aún no ha demostrado que pueda rellenar una tabla grande, crear un índice concurrente o recuperarse de una transformación de datos incorrecta. Cada clase necesita su propia ejecución observada y sus propios criterios de fallo.

Trata la autoridad sobre producción como algo que el agente toma prestado para un trabajo concreto y pierde después. Ese hábito operativo evitará más daños que cualquier instrucción ingeniosa de un prompt.