Skip to content

Docker Usage

Jump to bottom
Arael Espinosa edited this page Apr 6, 2026 · 2 revisions

Docker Usage

The repository includes a Dockerfile for building and running the migrator as a container.

Public Image

A pre-built multi-arch image is published to Docker Hub on every release:

docker pull cl8dep/db-migrator:latest
# or a specific version
docker pull cl8dep/db-migrator:0.2.2

Supported platforms: linux/amd64, linux/arm64.

Running with Docker

docker run --rm \
  -e DB_MIGRATOR_SOURCE_DB_PASSWORD=secret \
  -e DB_MIGRATOR_TARGET_DB_PASSWORD=secret \
  -v $(pwd)/config.yaml:/app/config.yaml:ro \
  cl8dep/db-migrator:latest run --config /app/config.yaml

For CI environments (no ANSI color codes):

docker run --rm \
  -e DB_MIGRATOR_SOURCE_DB_PASSWORD=secret \
  -e DB_MIGRATOR_TARGET_DB_PASSWORD=secret \
  -v $(pwd)/config.yaml:/app/config.yaml:ro \
  cl8dep/db-migrator:latest run --config /app/config.yaml --no-color

Building Locally

Single platform (fastest):

docker build -t db-migrator .

Multi-arch (for publishing to a registry):

docker buildx build \
  --platform linux/amd64,linux/arm64 \
  --provenance=false \
  -t cl8dep/db-migrator:latest \
  --push \
  .

Note: --provenance=false is required. Without it, buildx wraps the manifest in an OCI attestation index that Cloud Run does not support.

Docker Compose (local development)

The compose file defines three services:

Service Port (host) Description
source-db 5433 Source PostgreSQL with seed data
target-db 5434 Empty target PostgreSQL
migrator — Runs the migration once, then exits 
docker-compose up
docker-compose up --build   # rebuild after code changes

Cloud Run Job (GCP)

Cloud Run requires an image from a registry accessible without OCI attestation wrapping. Use Google Artifact Registry for GCP deployments.

1. Push to Artifact Registry

gcloud auth configure-docker us-central1-docker.pkg.dev

docker buildx build \
  --platform linux/amd64 \
  --provenance=false \
  -t us-central1-docker.pkg.dev/YOUR_PROJECT/db-migrator/db-migrator:latest \
  --push \
  .

2. Create the Job

gcloud run jobs create db-migrator \
  --image us-central1-docker.pkg.dev/YOUR_PROJECT/db-migrator/db-migrator:latest \
  --region us-central1 \
  --project YOUR_PROJECT \
  --service-account db-migrator@YOUR_PROJECT.iam.gserviceaccount.com \
  --add-cloudsql-instances SOURCE_PROJECT:REGION:SOURCE_INSTANCE \
  --add-cloudsql-instances YOUR_PROJECT:REGION:TARGET_INSTANCE \
  --add-volume name=dump-storage,type=cloud-storage,bucket=YOUR_DUMP_BUCKET \
  --add-volume-mount volume=dump-storage,mount-path=/dumps \
  --set-secrets /secrets/config.yaml=db-migrator-config:latest \
  --set-secrets DB_MIGRATOR_SOURCE_DB_PASSWORD=DB_MIGRATOR_SOURCE_DB_PASSWORD:latest \
  --set-secrets DB_MIGRATOR_TARGET_DB_PASSWORD=DB_MIGRATOR_TARGET_DB_PASSWORD:latest \
  --args="run,--config,/secrets/config.yaml,--no-color" \
  --memory 1Gi \
  --task-timeout 7200

3. Upload config to Secret Manager (regional)

gcloud secrets create db-migrator-config \
  --project YOUR_PROJECT \
  --replication-policy manual \
  --locations us-central1 \
  --data-file=config.yaml

# Update an existing secret version
gcloud secrets versions add db-migrator-config \
  --project YOUR_PROJECT \
  --data-file=config.yaml

4. Execute

gcloud run jobs execute db-migrator \
  --region us-central1 \
  --project YOUR_PROJECT

# Stream logs
gcloud run jobs executions logs tail \
  --project YOUR_PROJECT \
  --region us-central1

Cloud SQL Auth Proxy (Unix socket)

When using --add-cloudsql-instances, Cloud Run mounts a Unix socket at /cloudsql/PROJECT:REGION:INSTANCE. Use that path as host in config.yaml:

migration:
  source:
    host: "/cloudsql/source-project:us-central1:source-instance"
    port: 5432
    ...
  target:
    host: "/cloudsql/your-project:us-central1:target-instance"
    port: 5432
    ...

The Service Account needs roles/cloudsql.client on both projects.

Environment Variables

Variable Description
DB_MIGRATOR_SOURCE_DB_PASSWORD Password for source database
DB_MIGRATOR_TARGET_DB_PASSWORD Password for target database
NO_COLOR Set to any non-empty value to disable ANSI color output

Clone this wiki locally