通过Bitbucket CI/CD连接GAE与Prisma管理的Cloud SQL Postgres实例遇阻求助

我通过Bitbucket CI/CD部署连接PostgreSQL CloudSQL实例的Google App Engine应用，使用Prisma ORM管理数据库，但构建阶段执行prisma migrate deploy时触发连接错误：

> prisma migrate deploy
Environment variables loaded from .env
Prisma schema loaded from prisma/schema.prisma
Datasource "db": PostgreSQL database "mydatabasename", schema "public" at "localhost:5432"
Error: P1001: Can't reach database server at `/cloudsql/my-project-id:europe-west1:my-instance-name`:`5432`
Please make sure your database server is running at /cloudsql/my-project-id:europe-west1:my-instance-name`:`5432``.

当前环境配置：

• .env中的DATABASE_URL：

  DATABASE_URL="postgres://username:password@localhost/dbname?host=/cloudsql/my-project-id:region:my-instance-name"
  

• prisma/schema.prisma配置：

  datasource db {
    provider = "postgresql"
    url      = env("DATABASE_URL")
  }
  

我已按官方文档配置Unix套接字连接并设置必要IAM角色，但问题仍未解决。

针对Bitbucket CI/CD + GAE + CloudSQL + Prisma技术栈，按以下步骤排查修复：

1. 在Bitbucket构建流程中启动CloudSQL Auth代理 #

Bitbucket的GAE部署镜像默认不会自动启动CloudSQL代理，必须在执行Prisma迁移前手动启动：
在Bitbucket Pipelines配置文件中添加代理启动步骤：

- step:
    name: Deploy to GAE
    script:
      # 下载适配Linux AMD64环境的CloudSQL代理二进制文件
      - wget -O cloud_sql_proxy https://dl.google.com/cloudsql/cloud_sql_proxy.linux.amd64
      - chmod +x cloud_sql_proxy
      # 后台启动代理，映射实例到本地5432端口
      - ./cloud_sql_proxy -instances=my-project-id:europe-west1:my-instance-name=tcp:5432 &
      # 等待代理初始化完成
      - sleep 10
      # 执行Prisma数据库迁移
      - npx prisma migrate deploy
      # 部署应用到GAE
      - gcloud app deploy

注意：确保Bitbucket Pipelines使用的GCP服务账号已被授予Cloud SQL Client角色，具备访问目标CloudSQL实例的权限。

2. 修正DATABASE_URL格式 #

Prisma对PostgreSQL Unix套接字的URL格式有严格要求，需调整为：

DATABASE_URL="postgresql://username:password@localhost/dbname?host=/cloudsql/my-project-id:europe-west1:my-instance-name"

确认URL中的用户名、密码、数据库名、实例连接名完全匹配CloudSQL实例的实际配置，避免出现拼写或区域代码错误。

3. 验证IAM权限配置 #

• 检查Bitbucket所用GCP服务账号是否拥有Cloud SQL Client（roles/cloudsql.client）角色，该角色是连接CloudSQL实例的必要权限。
• 确认CloudSQL实例的IAM权限列表中已添加该服务账号，若使用私有IP连接，需确保Bitbucket构建环境能访问实例所在的VPC网络。

4. 检查GAE应用的连接配置 #

部署到GAE的应用需在app.yaml中配置CloudSQL实例关联：

runtime: nodejs20
env_variables:
  DATABASE_URL: "postgresql://username:password@localhost/dbname?host=/cloudsql/my-project-id:europe-west1:my-instance-name"
beta_settings:
  cloud_sql_instances: "my-project-id:europe-west1:my-instance-name"

beta_settings中的实例连接名必须与DATABASE_URL中的路径完全一致。

5. 本地测试排除配置问题 #

在本地启动CloudSQL代理，使用相同的DATABASE_URL执行prisma migrate deploy。若本地能正常连接，说明问题出在Bitbucket构建环境的配置环节，需重点检查代理启动步骤或权限配置。

内容的提问来源于stack exchange，提问作者Tom De Kooning