Saltar al contenido principal
Midaz aplica las migraciones de esquema de PostgreSQL mediante imágenes de runner de migración dedicadas (una para el Ledger, otra para Tracer), desacopladas de los binarios de la aplicación. Las aplicaciones no migran al iniciar. Arrancan contra un esquema que el runner ya migró.

​
Por qué un runner dedicado

El runner dedicado tiene estas propiedades:
  • Las migraciones se ejecutan una vez, como un paso separado.
  • La imagen de la aplicación no incluye el SQL de migración y no cambia el esquema.
  • La imagen del runner se ejecuta bajo un contexto de seguridad reforzado (consulta Postura de seguridad).

​
Imágenes del runner

Cada versión incluye dos imágenes: Ambas imágenes comparten la misma forma:
  • Base: migrate/migrate, en una versión fijada.
  • Se ejecuta como USER 65532:65532 (sin root, agnóstico al UID).
  • Punto de entrada en shell POSIX que arma un DSN a partir de variables de entorno, ejecuta migrate ... up y termina.
  • No escribe nada en disco. Postgres registra el progreso de la migración en la tabla schema_migrations, por lo que readOnlyRootFilesystem: true es seguro.
El runner del Ledger aplica primero onboarding y luego transaction, en una sola invocación. El runner de Tracer aplica su única base de datos en un solo paso.

​
Contrato de entorno

Cada punto de entrada acepta una anulación de URL ya construida o las variables individuales DB_*. La anulación de URL tiene prioridad cuando está definida.

​
Runner del Ledger

​
Runner de Tracer

​
Forma del DSN

Cuando el punto de entrada arma el DSN a partir de las variables DB_*, produce:
La contraseña se codifica en formato percent-encoding para que los caracteres reservados de URI (% @ : / ? # & + space [ ]) no rompan el DSN. El % se codifica primero para que los escapes ya insertados no se codifiquen dos veces. El punto de entrada imprime marcadores de fase (applying onboarding migrations, applying transaction migrations, applying tracer migrations, migrations complete).

​
Ejecutar el runner del Ledger manualmente

El chart de Helm ejecuta el runner por ti. Para ejecutarlo manualmente, apúntalo a tus bases de datos mediante DB_* (o *_DATABASE_URL) y ejecútalo una vez antes de que el ledger inicie:
El runner sale con 0 en caso de éxito (incluido el caso idempotente sin efecto) y con un valor distinto de cero en caso de error.

​
Despliegue en Kubernetes

En producción, ejecuta cada runner de migración como un Job de Kubernetes (normalmente un Job PreSync de Argo CD o un hook de Helm) que se completa antes del rollout de la aplicación. El chart de Helm configura esto por ti. Las secciones siguientes cubren las propiedades que importan si escribes tus propios manifiestos.
El runner migra las bases de datos indicadas por su entorno, una vez.

​
Postura de seguridad

El runner funciona bajo un contexto de seguridad de pod reforzado:
  • Sin root: la imagen establece USER 65532:65532.
  • Agnóstico al UID: los archivos de migración pertenecen a root y son legibles por cualquier usuario, de modo que cualquier UID puede leerlos.
  • Seguro para readOnlyRootFilesystem: migrate no escribe ningún estado en el sistema de archivos.
La misma imagen funciona sin problemas bajo runAsNonRoot: true, readOnlyRootFilesystem: true y capabilities: drop [ALL].

​
TLS

Los puntos de entrada respetan sslmode desde el entorno (DB_ONBOARDING_SSLMODE, DB_TRANSACTION_SSLMODE o DB_SSL_MODE), con disable como valor predeterminado. En producción se recomienda establecer require (o algo más estricto). El runner en shell no reproduce la aplicación de TLS en código, la clasificación de errores ni la telemetría que las aplicaciones usan para sus propias conexiones. Controlas el TLS de las migraciones únicamente a través de sslmode, a cambio de un runner mínimo y sin dependencias.

​
Convenciones e idempotencia

  • Up/down emparejados: cada migración tiene un archivo .up.sql y un archivo .down.sql.
  • Idempotente: ejecutar migrate up cuando el esquema ya está en la última versión no tiene efecto. Volver a ejecutar el runner después de una aplicación parcial o completa es seguro.
  • CLI fijada: las imágenes del runner usan una versión fijada de golang-migrate.

​
Actualización desde versiones anteriores

Para adoptar el nuevo modelo:
  1. Descarga la versión que incluye las imágenes del runner.
  2. En Kubernetes, agrega los Jobs midaz-ledger-migrations y midaz-tracer-migrations a tu pipeline de despliegue para que se ejecuten antes del rollout de la aplicación. Si usas el chart de Helm oficial, esto ya está hecho por ti.

​
Páginas relacionadas