Guardarraíles para herramientas de backfill de ejecución única

Por qué los scripts de backfill necesitan guardarraíles

Un backfill es un trabajo que se ejecuta una sola vez para actualizar registros existentes y que cumplan una nueva regla. Tal vez añadiste una columna nueva y necesitas poblarla. Tal vez estás corrigiendo filas dañadas por un lanzamiento con bugs. O estás reestructurando datos tras una migración.

Aunque la lógica sea simple, el riesgo no lo es. Los backfills tocan datos reales de producción, a menudo a alta velocidad. Una cláusula WHERE equivocada puede actualizar millones de filas. Un bucle que asume “un usuario = un registro” puede crear duplicados. Un script que se ejecuta al mediodía puede sobrecargar la base de datos y tumbar tu app.

Los scripts internos siguen necesitando reglas de seguridad porque suelen eludir protecciones normales como revisión de código, pruebas, despliegue gradual y monitoreo. Y a diferencia de una petición web, un backfill sigue hasta terminar o hasta estrellarse.

Disparadores comunes incluyen:

• Añadir un campo nuevo (como status o normalized_email) y rellenarlo para usuarios existentes
• Corregir datos creados por automatizaciones (incluyendo prototipos generados por IA que escribieron filas inconsistentes)
• Recalcular valores derivados tras un bug o cambio de lógica

“Ejecutar una vez” no significa “alguien promete ejecutarlo una vez”. Significa que la herramienta evita re-ejecuciones accidentales, muestra lo que cambiará antes de tocar nada y deja evidencia de lo ocurrido. Los guardarraíles convierten un script arriesgado en una operación controlada que puedes explicar, repetir de forma segura si hace falta y auditar después.

Delimítalo como un pequeño cambio en producción

Trata un backfill de ejecución única como un pequeño despliegue a producción. Si lo mantienes vago, crecerá hasta convertirse en un script que toca más datos de los previstos.

Empieza con un objetivo de una frase lo bastante específico como para poder discutirlo. Nombra qué cambiará, qué registros califican y qué no se tocará. “Actualizar todos los usuarios” no es un alcance. “Poner email_verified=true para usuarios creados antes de 2025-01-01 que ya tienen un token verificado, y dejar al resto sin cambios” sí lo es.

Decide desde el principio cómo demostrarás que funcionó. El éxito debe ser medible, no una sensación al terminar el script. Combina totales con algunas comprobaciones puntuales para atrapar errores lógicos pronto.

Un plan simple de éxito suele incluir conteos esperados, algunos IDs de ejemplo para inspeccionar antes y después, y al menos una comprobación de cordura (por ejemplo, no introducir nulls ni crear duplicados). Si el cambio es reversible, escribe cómo lo revertirías. Si no es fácilmente reversible, trátalo como una ejecución de mayor riesgo y endurece los guardarraíles.

Elige la ventana horaria y el enfoque de despliegue más seguros. Si el cambio puede afectar inicios de sesión, facturación o permisos, evita las horas pico. Si es posible, haz una primera ejecución pequeña, verifica resultados y luego continúa.

Finalmente, sé explícito sobre quién puede ejecutarlo y quién debe revisarlo. “Cualquiera del equipo” es cómo ocurren escrituras accidentales en producción. Una buena línea base: una persona prepara y explica el plan, una segunda persona revisa la consulta y el alcance, y solo un conjunto reducido de cuentas de confianza puede ejecutar.

Si heredaste un prototipo generado por IA (por ejemplo de Cursor, v0, o Replit), asume que hay casos borde en el modelo de datos y en las rutas de autenticación. Eso hace que un alcance estricto y una revisión real sean aún más importantes.

Control de acceso y aprobaciones que realmente funcionen

Una herramienta de backfill de ejecución única es peligrosa sobre todo porque es rápida. Una persona puede cambiar muchos datos antes de que alguien lo note. El patrón más seguro es separar quién puede ejecutarla, quién puede aprobarla y quién puede inspeccionar lo ocurrido.

Empieza con el principio de menor privilegio. Trata el backfill como un “mini-sistema” con un conjunto de permisos restringido. Para muchos equipos, tres roles son suficientes:

• Runner: puede ejecutar el trabajo solo con parámetros aprobados
• Approver: puede revisar el plan y desbloquear una sola ejecución
• Observer: puede ver logs y resultados, pero no puede ejecutar

Para ejecuciones de mayor riesgo (pagos, auth, PII, borrados), añade un paso claro de ruptura de seguridad. Hazlo deliberadamente molesto: una segunda aprobación, un token con tiempo limitado y una razón explícita que quede guardada. Esto evita los accidentes tipo “lo ejecuto rápido” a las 2 a. m.

También protege contra el fallo más común en el mundo real: ejecutar en el entorno equivocado. Añade comprobaciones estrictas antes de cualquier escritura. Verifica el host de la base de datos, el nombre del entorno y un valor canario conocido (por ejemplo, una configuración que solo exista en producción) y rechaza continuar si algo no coincide. Si soportas múltiples tenants, exige una lista blanca explícita de tenants.

Guarda una pista de auditoría inmutable para poder responder “quién ejecutó qué, cuándo y por qué” en segundos. Registra la identidad del operador, la versión del código, los parámetros, los conteos de filas, inicio/fin y las aprobaciones usadas.

Modo dry-run: muestra los cambios antes de que ocurran

Un dry-run es la forma más barata de detectar errores antes de tocar producción. Para una herramienta de backfill de ejecución única, trata el dry-run como una funcionalidad de primera clase, no como un extra.

La salida del dry-run debe responder cuatro preguntas rápidamente:

• ¿Cuántas filas cambiarán?
• ¿Qué cambiará (con ejemplos)?
• Aproximadamente cuánto tiempo tomará
• ¿Si no hará nada?

Lo último importa. Si tus filtros están mal, quieres que la herramienta anuncie “0 actualizaciones” antes de perder una hora viendo logs.

Haz del dry-run la opción por defecto. Requiere una bandera explícita (por ejemplo, --execute) para realmente escribir cambios. Esa única elección evita el clásico incidente de “probé y olvidé quitar las credenciales reales”.

Un buen informe de dry-run no necesita ser largo. Debe mostrar totales (escaneadas, que coinciden, que cambiarán) y una pequeña muestra de valores antes/después para algunos IDs, con las diferencias exactas de campos. Si la herramienta genera SQL o construye joins complejos, imprimir el SQL final y los parámetros habitualmente revela filtros faltantes, la tabla equivocada o un bug de zona horaria.

Ejemplo: planeas backfillear user.status = 'active' para cuentas que verificaron el email. El dry-run debería mostrar “Matched: 12,430; Will change: 12,429” y destacar el único registro que no cambiaría porque ya está activo. Ese número es una comprobación de cordura.

Logs de progreso y observabilidad de la ejecución

Un backfill de ejecución única es más seguro cuando puedes responder, en segundos: qué está haciendo ahora, qué cambió y qué hacer si se detiene. La salida del terminal sola no basta. Trata la ejecución como un pequeño trabajo de producción con rastro documental.

Empieza con logs estructurados que sean fáciles de buscar. Cada línea de log debe incluir un run ID, una marca de tiempo y los parámetros de lanzamiento (entorno, flag de dry-run, tamaño de lote, filtros de alcance). Así, cuando alguien pregunte “tocamos al cliente X?”, puedes probarlo.

Registra algunos eventos de forma consistente: inicio (quién, qué versión, qué parámetros), progreso por lotes (escaneadas, actualizadas, saltadas, errores), cualquier throttling/backoff y final (totales, duración, éxito o fallo). Si un chequeo de seguridad detiene la ejecución, regístralo claramente como “stop reason”, no como un error genérico.

El progreso debe ser visible mientras el script corre, no solo al final. Una línea cada N registros está bien, pero incluye números accionables: lotes procesados, tasa actual, ETA aproximada y conteo de errores.

Escribe el progreso en un sitio durable por si el terminal muere. Opciones comunes son una tabla en la base de datos (una fila por ejecución más checkpoints por lote) o un archivo de log enviado a tu sistema normal de logs. El registro durable debe incluir el último checkpoint completado para que puedas decidir si reanudar o parar.

Finalmente, añade hooks de alerta para resultados importantes: ejecuciones fallidas, completadas parcialmente y ejecuciones atascadas (sin progreso en un tiempo establecido). Si un lote sigue reintentando durante 10 minutos, alerta para que alguien pueda pausar el trabajo antes de causar carga extra o cambios a medias.

Evitar re-ejecuciones y doble procesamiento

Una herramienta de backfill de ejecución única debe asumir que alguien pulsará “run” dos veces. Puede ser tú cinco minutos después por un timeout, o un compañero que no vio tu mensaje. Tu tarea es hacer que el segundo intento sea inofensivo.

Empieza por idempotencia cuando sea posible. Si el backfill fija un campo a un valor calculado, escríbelo para que reejecutarlo produzca el mismo estado final. Si el backfill crea filas, prefiere un upsert con clave estable en vez de un insert ciego. Si no puedes hacerlo totalmente idempotente, haz que lo "ya procesado" sea fácil de detectar y saltar.

Un ledger de ejecuciones es el siguiente guardarraíl. Crea una tabla pequeña que registre cada ejecución, incluyendo una firma de la ejecución (entradas + versión de código + alcance objetivo). Antes de trabajar, comprueba el ledger y detente si esa firma ya se completó con éxito.

Para el bloqueo, usa algo distribuido (un lock de fila en la BD, advisory lock o una fila de “lock” en el ledger). La regla es simple: si ya hay una ejecución “running” para esa clave de lock, sal.

Ejemplo concreto: estás backfilleando status=active para cuentas con facturas pagadas. La firma incluye la fecha de corte y el filtro. Si alguien lo reejecuta con la misma firma, la herramienta se niega. Si lo reejecuta con una nueva fecha de corte, la herramienta lo permite y la actualización idempotente mantiene las cuentas previas sin cambios.

Diseña para fallos parciales y reintentos seguros

Asume que tu backfill fallará a mitad de camino. Las redes fallan, las filas tienen sorpresas y la app principal sigue atendiendo tráfico. El objetivo no es “nunca fallar”, sino “fallar sin causar desastre”.

Empieza por batchs con un orden claro y un checkpoint. Elige un orden estable (a menudo por clave primaria o por fecha de creación) y registra lo completado tras cada lote. Mantén los lotes lo bastante pequeños para que cada uno termine rápido, así no mantienes locks largos ni creas grandes rollbacks. Si necesitas reanudar, el checkpoint debe indicar dónde continuar sin adivinar.

Los reintentos necesitan una política. Problemas temporales (timeouts, sobrecarga breve) pueden reintentarse. Límites de tasa deben reintentarse con backoff. Errores de validación y desajustes de esquema no deben reintentarse. Errores de permisos deben pausar y alertar. Cualquier cosa que sugiera que podrías estar escribiendo datos incorrectos debe fallar rápido.

Protege la app principal con backpressure. Añade un límite simple de tasa (filas por segundo) y redúcelo automáticamente cuando la base de datos se desacelere. Si la latencia o la tasa de errores de la app sube, el backfill debe retroceder o parar. Un backfill nunca vale una caída del servicio.

Prefiere patrones de escritura seguros: transacciones cortas por lote, comprobaciones de “actualizar solo si no está ya actualizado” y upserts cuando corresponda. Evita transacciones de larga duración que bloqueen tablas grandes. Evita escaneos de tabla completa cuando una consulta dirigida sirve.

Paso a paso: plano para una herramienta de backfill segura de ejecución única

Una herramienta de backfill de ejecución única debe sentirse aburrida de operar. La meta es que el camino seguro sea el más fácil y que las acciones riesgosas sean ruidosas y difíciles.

1. Nail the contract antes de escribir código. Escribe las entradas exactas (rango de fechas, tenant IDs, filtros de status), los registros que esperas tocar y qué significa “terminado”. Añade un preflight que imprima conteos y falle rápido si el filtro es demasiado amplio.

2. Construye el dry-run primero y luego blinda la ejecución. El dry-run debe hacer todo excepto las escrituras: cargar candidatos, aplicar reglas y mostrar un resumen de cambios planeados. Coloca la ejecución real detrás de una bandera explícita como --execute para que olvidar una bandera sea seguro.

3. Crea un run ID, un lock y un run ledger. Genera un run ID único y guarda quién lo inició, cuándo, parámetros y un estado (started, completed, failed). Toma un lock para que dos personas no puedan ejecutar el mismo trabajo a la vez.

4. Añade logs de progreso, checkpoints y reanudar. Registra cuántos elementos se escanearon, actualizaron, saltaron y fallaron cada N registros. Guarda checkpoints (por ejemplo “último ID procesado”) para reanudar tras un crash.

5. Pruébalo en staging y luego canary en producción. Ejecuta contra datos de staging primero. En producción, empieza con un tamaño de lote pequeño (por ejemplo, 50 filas) y verifica el resultado con una consulta o informe simple antes de procesar todo.

Ejemplo concreto: si estás backfilleando un campo created_by faltante, el dry-run debe mostrar cuántas filas cambiarían por tenant, y la ejecución debe escribir solo esas filas mientras registra el run ID en el ledger.

Ejemplo: arreglar un error de datos en producción sin pánico

Un equipo despliega un prototipo generado por IA a producción. Una semana después detectan algo alarmante: muchos usuarios se guardaron con el rol equivocado. Algunos admins pasaron a “member” y algunos members a “admin”. Nadie quiere “ejecutar un script” y esperar.

Construyen una herramienta de backfill de ejecución única que puede probar lo que cambiará antes de tocar nada. Primero, el dry-run lee los roles actuales, calcula los roles correctos desde la fuente de la verdad y muestra un resumen claro: cuántos usuarios cambiarían, algunos ejemplos antes/después (con IDs de usuario, no emails) y un desglose de movimientos entre roles.

Tras la revisión, la ejecución corre en lotes pequeños (por ejemplo, 500 usuarios a la vez). Cada lote escribe logs de progreso: número de lote, hora de inicio, cuántos cambiaron y errores. También escribe una entrada en el run ledger con un run ID único, quién lo lanzó y la versión exacta del código usada. Ese ledger evita que alguien lo ejecute dos veces por accidente.

Al finalizar, verifican en lugar de adivinar: los conteos coinciden con el dry-run, un puñado de usuarios por rol se ven correctos, las pantallas solo para admin siguen requiriendo admin y los errores de permisos no aumentaron.

Todo ese cuidado sale más barato que un rollback.

Errores comunes que causan incidentes evitables

La mayoría de incidentes con backfills no vienen por bugs “difíciles”. Ocurren porque un script que debería tratarse como un pequeño cambio en producción se trata como una tarea rápida.

Un fallo común es ejecutar contra producción sin protecciones. Alguien apunta el script a prod “solo esta vez”, pero no hay chequeo de entorno, no hay confirmación ni límite de permisos. Una herramienta segura debe dificultar atacar producción por accidente y facilitar probar quién lo ejecutó y por qué.

Errores en dry-run son igual de peligrosos. Un dry-run que usa queries diferentes, filtros distintos o que omite validaciones crea confianza falsa. Luego la ejecución real toca más filas de las esperadas. El dry-run debe ejecutar la misma selección y lógica que la ejecución real, con el paso de escritura reemplazado por una vista previa.

Las re-ejecuciones provocan daño silencioso. Dos personas pueden ejecutar lo mismo simultáneamente, o alguien lo re-ejecuta tras un timeout. Sin un lock o marcador de idempotencia, hay doble procesamiento: filas duplicadas, valores sobrescritos o contadores rotos.

El logging es otro punto ciego. Logs solo en consola desaparecen cuando el terminal se cierra. Tras un incidente no tienes línea de tiempo, conteos ni registro de parámetros.

Los patrones detrás de la mayoría de incidentes evitables son simples:

• No hay chequeos de entorno duros (prod parece staging)
• El dry-run no coincide con la ejecución
• No hay lock ni run ledger, así puede ejecutarse dos veces
• Los logs no se guardan en sitio durable
• No hay batching ni checkpoints, así los fallos obligan a reinicios completos

Ejemplo: un fundador backfillea “customer IDs faltantes” y lo hace como una actualización masiva. Se queda a medias por timeout y lo reejecuta. Ahora la mitad de las filas se cambiaron dos veces y el equipo no sabe cuáles son.

Lista rápida antes de pulsar “run”

Antes de empezar, para un chequeo rápido y aburrido. La mayoría de incidentes ocurren porque alguien confió en el prompt del terminal, saltó el dry-run o olvidó que el script puede ejecutarse dos veces.

• Confirma el entorno de dos maneras: lo que crees que es (config/CLI) y lo que la herramienta verifica (debe negarse a ejecutar si no ve el host o project ID esperado).
• Revisa la salida del dry-run y guarda el resumen en un lugar donde puedas consultarlo luego. Si el dry-run dice 10,000 filas y esperabas 1,000, para.
• Asegúrate de que las aprobaciones están registradas (quién aprobó y cuándo) y de que las comprobaciones de lock/ledger están habilitadas para esa firma exacta.
• Confirma que puedes ver contadores de progreso (procesado, actualizado, saltado, fallado) y que alguien está observando la ejecución.

Al terminar, no lo des por hecho hasta ejecutar las comprobaciones post-run (los conteos cuadran, las muestras se ven correctas y los errores son cero o están entendidos).

Próximos pasos: hazlo repetible y pide una segunda opinión

Una herramienta de backfill de ejecución única es “una vez” solo en ejecución, no en la forma cuidadosa en que se construye. Trata la primera ejecución como un ensayo para el siguiente incidente: documenta el proceso, hazlo repetible y fácil de revisar por otra persona.

Sabe cuándo parar y pedir ayuda. Si descubres casos borde de esquema desconocidos, calidad de datos confusa (nulls, duplicados, IDs desajustados) o algo que involucre auth y permisos, detente. Esos son momentos en los que una segunda opinión rápida evita suposiciones que derivan en escrituras irreversibles.

Mantén documentación corta y amigable para auditoría: qué datos se apuntaron, qué filtros se usaron, en qué entorno se ejecutó, quién aprobó y qué comprobaciones hiciste antes y después. Incluye la versión del script y una copia del resumen del dry-run.

Si trabajas con una base de código generada por IA y no confías en que el backfill sea seguro, FixMyMess (fixmymess.ai) hace diagnóstico del codebase y endurecimiento para problemas como consultas inseguras, riesgo de re-ejecución y brechas de seguridad antes de tocar datos en producción.