本地系统Sequelize连接PostgreSQL CloudSQL出现连接报错如何解决？

报错原文 #

DB connection FAILED ConnectionError [SequelizeConnectionError]: connect ENOENT /cloudsql/prj-theexperiencebox:us-central1:theexperiencebox-01/.s.PGSQL.5432

根因说明 #

该报错的本质是本地环境不存在Cloud SQL要求的Unix套接字文件：默认只有GCP托管环境（App Engine、Cloud Run等）或者启动了Cloud SQL代理的环境，才会自动生成/cloudsql/[实例连接名]路径下的套接字文件，本地开发环境默认没有该路径，所以Sequelize尝试连接时找不到对应文件触发ENOENT错误。

具体排查与解决方案 #

• 场景1：未启动Cloud SQL代理，直接用Unix套接字配置连接 #

  本地开发如果没有启动代理，不要使用Unix套接字模式连接，切换为TCP/IP连接模式即可：

  1. 去掉Sequelize配置中的socketPath参数，改为指定host为Cloud SQL实例的公网IP，port默认值为5432
  2. 前往GCP Cloud SQL控制台，将你本地的公网IP添加到实例的授权网络白名单中
     参考配置示例：

  const sequelize = new Sequelize('数据库名', '数据库用户名', '数据库密码', {
    host: '你的Cloud SQL实例公网IP',
    dialect: 'postgres',
    port: 5432
  })
  

• 场景2：需要用Unix套接字模式连接（模拟生产环境配置） #

  必须先启动Cloud SQL代理在本地生成对应套接字文件：

  1. 先在本地创建套接字目录并赋予读写权限：
     执行命令 sudo mkdir -p /cloudsql && sudo chmod 777 /cloudsql
  2. 启动Cloud SQL代理，命令示例：
     ./cloud_sql_proxy -dir=/cloudsql -instances=prj-theexperiencebox:us-central1:theexperiencebox-01
  3. 代理启动成功后再运行业务代码，此时/cloudsql路径下会自动生成对应的套接字文件，即可正常连接。

• 其他排查项 #

  • 确认Cloud SQL实例连接名拼写正确，可以直接在GCP控制台实例详情页复制，避免手动拼写输错项目ID、区域、实例名
  • Windows环境不支持Unix套接字，直接使用TCP公网IP连接即可
  • 确认Cloud SQL实例处于正常运行状态，没有被暂停、删除或者配置了IP白名单拦截

内容的提问来源于stack exchange，提问作者Shiva