Skip to main content

Running Database Migrations

This guide explains how to configure your application to run a pre-deployment database migration job before the main service starts.

Infrastream supports automated database migrations via the runMigrationJob feature. When enabled, the platform creates a one-off Cloud Run Job that runs your migration container before deploying the main service. The main deployment is gated — it only proceeds after the migration job completes successfully.

Prerequisites​

  • You must have an existing Application manifest.
  • Your application's BuildDefinition or ExternalApplication should produce a container image that can run migrations (e.g., a Flyway, Liquibase, or custom migration runner).
  • You must have a Database manifest provisioned.

Step 1: Enable Migration Jobs in Your Application​

In your Application manifest, set runMigrationJob: true:

apiVersion: lowops.manifests.v1
kind: Application
metadata:
  name: payment-api
  project: payment-gateway
  environment: production
  organizational-unit: retail-banking
  organization: fincorp
spec:
  source: payment-api
  container: payment-api
  target: CLOUD_RUN
  project: payment-gateway
  runMigrationJob: true            # ← Enable pre-deployment migration
  accessControl:
    database:
      name: payments-db
      schema: public
      privileges:
        - USAGE
        - CREATE
      secretSource:
        envVar: DATABASE_URL

Step 2: Ensure Your Container Supports Migrations​

The migration job uses a dedicated container image from your build definition. Ensure your Dockerfile or build pipeline produces an image that can run migrations when invoked.

Common patterns:

  • Flyway / Liquibase: The same container can run migrations via an entrypoint override
  • Custom scripts: Include a /migrate.sh script that the job invokes

Note: The platform creates a google_cloud_run_v2_job resource. The main google_cloud_run_v2_service is configured to depend on the successful completion of this job.

Step 3: Configure Schema Management​

If your migration tool (e.g., Flyway) manages schema creation, you should disable automatic schema creation to avoid conflicts:

  accessControl:
    database:
      name: payments-db
      schema: public
      privileges:
        - USAGE
        - CREATE
      skipSchemaCreation: true     # ← Let your migration tool handle DDL
      extensions:
        - pgcrypto                 # PostgreSQL extensions to enable
        - uuid-ossp
      secretSource:
        envVar: DATABASE_URL

Step 4: Commit, Review, and Merge​

After your PR is merged, the deployment flow becomes:

The migration job runs before every deployment, ensuring your database schema is always up-to-date with the deployed code version.