Apply Migrations

This guide explains how to apply CRM database migrations when your local setup only has gcloud and Cloud SQL Proxy.

Prerequisites

• gcloud CLI is installed and authenticated
• Cloud SQL Proxy is installed (cloud-sql-proxy)
• pnpm is installed
• You are in the monorepo root

1. Get the Cloud SQL connection name

If you already know it, skip this step.

gcloud sql instances describe development-crm-db-89b171c7 \
  --project=selegic-crm-01 \
  --format='value(connectionName)'

Expected output format:

PROJECT_ID:REGION:INSTANCE

For this environment:

selegic-crm-01:us-central1:development-crm-db-89b171c7

2. Start Cloud SQL Proxy

Run this in a dedicated terminal and keep it running:

cloud-sql-proxy selegic-crm-01:us-central1:development-crm-db-89b171c7 \
  --address 127.0.0.1 \
  --port 5432

3. Configure DATABASE_URL

CRM Prisma config reads DATABASE_URL from crm/server/.env.

Use this format:

DATABASE_URL=postgresql://<user>:<url-encoded-password>@127.0.0.1:5432/<database_name>

Important:

• URL-encode special characters in the password (@, :, %, &, ?, /, #, +)
• Use 127.0.0.1 (or localhost) because proxy is local
• Keep port as 5432 unless you changed the proxy port

4. Install dependencies

From the repository root:

pnpm install

5. Apply migrations

Run both migration sets from the repository root:

pnpm --filter @repo/crm-db run db:core:migrate
pnpm --filter @repo/crm-db run db:org:migrate

What they do:

• db:core:migrate: applies migrations from packages/crm/db/src/core/migrations
• db:org:migrate: applies migrations from packages/crm/db/src/organization/migrations

6. Verify migration status (optional)

pnpm --filter @repo/crm-db exec prisma migrate status --config=src/config/prisma.config.ts
pnpm --filter @repo/crm-db exec prisma migrate status --config=src/config/prisma.config.org.ts

Troubleshooting

P1001: Cannot reach database server

• Ensure Cloud SQL Proxy is still running
• Confirm proxy port matches your DATABASE_URL
• Verify instance connection name is correct

Authentication failed

• Re-check DB username/password
• Ensure password is URL-encoded
• Confirm your DB user has access to the target database

No migration found

• Confirm you run commands from repo root
• Confirm you are using @repo/crm-db scripts

Notes

• Use prisma migrate deploy (already used by repo scripts) for shared environments
• Avoid prisma migrate reset unless you intentionally want to drop and recreate the database