Skip to main content
Las migraciones son archivos SQL versionados en migrations/ aplicados con @insforge/cli. Cada ejecución exitosa se registra en system.custom_migrations. El flujo de trabajo es de solo avance.

​
Conceptos

Una migración es un archivo SQL prefijado con una marca de tiempo UTC de 14 dígitos: <YYYYMMDDHHmmss>_<name>.sql. El CLI aplica archivos pendientes en orden dentro de una transacción, establece search_path en public y registra el historial solo en caso de éxito. PostgREST recarga automáticamente los metadatos del esquema. BEGIN/COMMIT/ROLLBACK dentro de un archivo se rechaza.

​
Uso

Vincule el backend y luego cree un archivo.
Escriba el SQL.
Aplique migraciones pendientes y verifique el historial.
Apunte a un archivo único con up <version>, o aplique todo pendiente hasta e incluyendo un destino con up --to <version>.

​
Casos de uso específicos

Adoptar migraciones en un proyecto existente: ejecute db migrations fetch primero para materializar el historial remoto en archivos locales. Una vez aplicado remotamente, nunca edite una migración in situ. En su lugar, escriba una migración hacia adelante. Una vez que opte por participar, rute todos los cambios de esquema a través de archivos. Las ediciones ad hoc del panel causan una desviación entre git y system.custom_migrations.

​
Sentencias no transaccionales

Como el CLI ejecuta cada archivo de migración dentro de una sola transacción (el mismo motivo por el que se rechazan BEGIN/COMMIT/ROLLBACK), algunos comandos de PostgreSQL que no pueden ejecutarse dentro de un bloque de transacción fallarán en una migración con un error como CREATE INDEX CONCURRENTLY cannot run inside a transaction block. Los más comunes son:
  • CREATE INDEX CONCURRENTLY — usa un CREATE INDEX normal en una migración cuando sea aceptable un bloqueo de escritura breve, o ejecuta la construcción concurrente fuera de una migración (más abajo).
  • VACUUM — el vacuum rutinario lo gestiona el autovacuum de PostgreSQL, así que rara vez necesitas ejecutarlo tú.
  • REINDEX ... CONCURRENTLY, ALTER TYPE ... ADD VALUE (en PostgreSQL antiguo) y comandos similares.
Ejecuta estos comandos fuera de una migración con la ruta de SQL sin procesar «unrestricted» del CLI, que ejecuta la sentencia sin envolverla en una transacción:
El npx @insforge/cli db query normal (sin --unrestricted) envuelve tu sentencia en una transacción, por lo que da el mismo error; usa --unrestricted para los comandos no transaccionales.
Ambas rutas de db query aplican un statement_timeout de 30 segundos, así que CREATE INDEX CONCURRENTLY o VACUUM sobre una tabla grande pueden agotar el tiempo de espera.

​
Más recursos