Convex 自托管后端接入 Postgres 与 MySQL：环境变量、连接配置与源码原理

数据库后端【免费下载链接】convex-backendThe open-source reactive database for app developers项目地址https://gitcode.com/gh_mirrors/co/convex-backend点击查看免费下载导读Convex 是一个开源响应式数据库后端默认以 SQLite 作为本地持久化存储但对于需要高可用与托管运维的生产环境官方推荐将后端连接到托管式 Postgres 或 MySQL 服务。本文基于仓库 self-hosted/advanced/postgres_or_mysql.md 展开完整讲解POSTGRES_URL、MYSQL_URL、INSTANCE_NAME、DO_NOT_REQUIRE_SSL等环境变量的用法与数据库命名规则并结合仓库源码如 crates/db_connection/src/lib.rs、crates/clusters/src/lib.rs、self-hosted/docker-build/run_backend.sh剖析后端如何解析连接串、派生数据库名、注入 SSL 参数让读者既能照着文档完成 Neon/PlanetScale/本地 Postgres/MySQL 的接入也能理解底层实现原理。一、为什么生产环境要考虑 Postgres 或 MySQLConvex 后端本身被设计为同时兼容 SQLite、Postgres 与 MySQL 三种数据库。默认情况下self-hosted/docker/docker-compose.yml 中的 Docker 镜像使用本地 SQLite 存储数据存放在 Docker volumedata:/convex/data中。SQLite 方案适合本地开发与快速起步是官方推荐的入门配置详见 self-hosted/README.md如果运行的是需要保证可用性guaranteed uptime的生产负载则应优先选择托管式 Postgres 或 MySQL 服务例如 NeonPostgres或 PlanetScaleMySQL/Vitess官方测试确认 Convex 后端可与Postgres v17和MySQL v8协同工作其他版本也可能兼容但未做验证。需要特别注意一个硬性约束后端必须与数据库托管在同一区域且网络距离尽可能近。后端与数据库之间的任何额外延迟都会直接拖累查询性能这一点在 postgres_or_mysql.md 中被反复强调。1.1 迁移前先导出数据在不同数据库提供方之间迁移时务必先使用官方 CLI 导出数据npx convex export该命令会将当前部署的数据导出为文件随后再在新数据库环境上执行npx convex deploy重新部署 Convex 函数详见下文“部署后的重部署”说明。二、环境变量速查表以下变量在接入外部数据库时最常用全部在 docker-compose.yml 的environment段中透传并由容器入口脚本 self-hosted/docker-build/run_backend.sh 消费环境变量作用取值要点POSTGRES_URL指定 Postgres 连接串优先级最高不含数据库名与查询参数形如postgresql://userhost:5432MYSQL_URL指定 MySQL 连接串不含数据库名形如mysql://user:passhost:3306DATABASE_URL已弃用兼容旧行为等价于 Postgres 连接设置时会打印弃用警告DO_NOT_REQUIRE_SSL关闭对数据库连接的 SSL 强制要求仅建议本地开发使用设置后若存在 SSL 仍会优先使用INSTANCE_NAME指定实例名间接决定数据库名默认convex-self-hosted连字符会被替换为下划线INSTANCE_SECRET实例密钥与INSTANCE_NAME配对后端启动必需从 run_backend.sh 的入口逻辑可以看出完整的优先级链if [ -n $POSTGRES_URL ]; then DB_SPEC$POSTGRES_URL DB_FLAGS(${POSTGRES_DB_FLAGS[]}) # --db postgres-v5 elif [ -n $MYSQL_URL ]; then DB_SPEC$MYSQL_URL DB_FLAGS(${MYSQL_DB_FLAGS[]}) # --db mysql-v5 elif [ -n $DATABASE_URL ]; then # 弃用警告按 Postgres 处理以保持向后兼容 else DB_SPEC$SQLITE_DB # 回退到 SQLite fi即POSTGRES_URLMYSQL_URLDATABASE_URL弃用 SQLite 回退。最终这些参数被拼装为convex-local-backend的命令行参数--db postgres-v5 DB_SPEC或--db mysql-v5 DB_SPECpostgres-v5/mysql-v5对应 crates/clusters/src/db_driver_tag.rs 中的DbDriverTag枚举值同时--instance-name $INSTANCE_NAME、${DO_NOT_REQUIRE_SSL:--do-not-require-ssl}等参数也会一并传入。三、连接 Neon 上的托管 Postgres生产场景3.1 获取连接串并建库从 Neon 控制台复制连接字符串并创建后端专用的数据库export DATABASE_CONNECTIONconnection string psql $DATABASE_CONNECTION -c CREATE DATABASE convex_self_hosted3.2 构造 POSTGRES_URLPOSTGRES_URL是不含数据库名和查询参数的连接串。以 Neon 为例其结尾应为neon.tech。文档给出了用sed剥掉路径与查询串的做法export POSTGRES_URL$(echo $DATABASE_CONNECTION | sed -E s/\/[^/](\?.*)?$//)该正则将形如postgresql://user:passep-xxx.neon.tech/convex_self_hosted?sslmoderequire的完整连接串中的/convex_self_hosted?sslmoderequire部分剥离得到postgresql://user:passep-xxx.neon.tech。3.3 在托管平台上注册环境变量若运行在 Fly.io 等平台通过平台命令注册密钥fly secrets set POSTGRES_URL$POSTGRES_URL若在本机运行直接重启后端容器即可让环境变量生效POSTGRES_URL已在 docker-compose.yml 的environment中声明透传。3.4 验证连接并重部署函数启动后端后检查日志应能看到类似Connected to Postgres的行。这一日志来自 crates/db_connection/src/lib.rstracing::info!(Connected to Postgres database: {}, deployment_name);另外切换到新数据库后必须重新部署已有的 Convex 函数npx convex deploy3.5 为什么 URL 中不能带数据库名源码剖析在 crates/clusters/src/lib.rs 中Postgres 分支会校验连接串路径必须为空或/否则直接报错anyhow::ensure!( cluster_url.path() || cluster_url.path() /, cluster url already contains db name: {}, cluster_url.path() );随后后端依据deployment_name即实例名自动拼接数据库名let db_name deployment_name.replace(-, _); cluster_url.set_path(db_name);这正是“不要在POSTGRES_URL中包含数据库名”的根本原因——数据库名由后端根据实例名自动计算并写入连接串路径。四、本地连接 Postgres开发场景本地已有 Postgres 实例时psql postgres -c CREATE DATABASE convex_self_hosted然后设置连接串并关闭 SSL 强制要求export POSTGRES_URLpostgresql://your-usernamehost.docker.internal:5432 export DO_NOT_REQUIRE_SSL1 docker compose up要点说明host.docker.internal用于从 Docker 容器内访问宿主机上的 Postgres同样不要在POSTGRES_URL中包含数据库名DO_NOT_REQUIRE_SSL对应后端--do-not-require-ssl参数。其语义在 crates/local_backend/src/config.rs 中有明确注释关闭后不强制要求数据库连接使用 SSL但如果数据库支持 SSL仍会优先使用官方注释强调该选项“只应在测试中设置”。4.1 SSL 参数如何注入源码验证在 crates/clusters/src/lib.rs 中adjust_postgres_url会根据require_ssl与require_leader标志向连接串追加查询参数if require_ssl { cluster_url .query_pairs_mut() .append_pair(sslmode, require); } if require_leader { cluster_url .query_pairs_mut() .append_pair(target_session_attrs, read-write); }因此设置了DO_NOT_REQUIRE_SSL时不会注入sslmoderequire而在 Neon 等托管场景默认强制 SSL后端会注入sslmoderequire并对会话附加target_session_attrsread-write要求连接到可写的 leader 节点见 crates/db_connection/src/lib.rs 的TargetSessionAttrs::ReadWrite。五、本地连接 MySQL开发场景mysql -e CREATE DATABASE convex_self_hosted; export MYSQL_URLmysql://your-usernamehost.docker.internal:3306 export DO_NOT_REQUIRE_SSL1 docker compose up与 Postgres 一致数据库名由后端推导URL 中不要带库名。六、连接 PlanetScale 上的 MySQL生产场景在 PlanetScale 创建数据库必须命名为convex_self_hosted然后export MYSQL_URLmysql://your-username:your-passwordaws.connect.psdb.cloud docker compose up6.1 MySQL 分支的源码行为从 crates/clusters/src/lib.rs 可以看出 MySQL 分支与 Postgres 的关键差异后端不会把数据库名写入连接串路径而是保持无库连接、在持久化层按需USE对应的库// NOTE: We do not set any database so we can reuse connections between // database. The persistence layer will select the correct database. if require_ssl { cluster_url .query_pairs_mut() .append_pair(require_ssl, true) .append_pair(verify_ca, true); } let db_name deployment_name.replace(-, _);即db_name同样由实例名推导-替换为_但以独立字段PersistenceArgs::MySql { url, db_name, ... }传递供 crates/db_connection/src/lib.rs 中ConvexMySqlPool连接后选择数据库。MySQL 路径还要求连接串用户名非空crates/clusters/src/lib.rs若缺失会报cluster url username must be set且不打印完整 URL 以防泄露密码。七、数据库命名规则与 INSTANCE_NAME后端使用的持久化数据库名 实例名instance name中-替换为_后的结果实例名实际连接的数据库convex-self-hosted默认convex_self_hostedyour-instance-nameyour_instance_name在 Docker 容器中通过INSTANCE_NAME环境变量设置实例名。例如使用 Postgresexport POSTGRES_URLconnection string export INSTANCE_NAMEyour-instance-name psql $POSTGRES_URL -c CREATE DATABASE your_instance_name;源码侧LocalConfig::name()crates/local_backend/src/config.rs在未设置INSTANCE_NAME时回退到DEV_INSTANCE_NAMEpub fn name(self) - String { self.instance_name .clone() .unwrap_or(DEV_INSTANCE_NAME.to_owned()) }而DEV_INSTANCE_NAME定义于 crates/keybroker/src/lib.rs取自常量文件 crates/keybroker/dev/instance_name.txt内容为carnitas用于本地开发Docker 镜像的入口脚本 run_backend.sh 则始终透传--instance-name $INSTANCE_NAME因此容器内默认实例名由镜像默认值决定即文档所述convex-self-hosted。随后deployment_name.replace(-, _)即产生convex_self_hosted这与前文所有建库命令中的库名完全对应。八、连接流程全景从环境变量到持久化层综合 run_backend.sh、crates/db_connection/src/lib.rs 与 crates/clusters/src/lib.rs一条完整调用链如下容器入口脚本读取POSTGRES_URL/MYSQL_URL或回退 SQLite组装--db postgres-v5/--db mysql-v5与--do-not-require-ssl、--instance-name等参数convex-local-backend解析参数LocalConfig得到DbDriverTag、db_spec连接串、实例名persistence_seed/connect_persistencecrates/db_connection/src/lib.rs调用persistence_args_from_cluster_urlcrates/clusters/src/lib.rs校验用户名非空、路径不含库名Postgres路径写入推导出的库名按需注入sslmoderequire与target_session_attrsread-writeMySQL保持无库连接注入require_ssltrueverify_catrue库名单独传递创建连接池PostgresPersistence::create_pool/ConvexMySqlPool::new初始化持久化层日志分别输出Connected to Postgres database: {deployment_name}或Connected to MySQL database: {db_name}crates/db_connection/src/lib.rs 与 crates/db_connection/src/lib.rs。九、常见问题与注意事项连接串必须可被 URL 解析后端使用 Rusturl库解析连接串Postgres 路径带库名会直接报错用户名缺失会报cluster url username must be set。SSL 策略托管服务Neon、PlanetScale默认强制 SSL本地开发可用DO_NOT_REQUIRE_SSL1关闭强制要求但官方建议仅测试环境使用。数据库需预先创建后端不会自动建库所有示例都先用psql/mysql客户端显式CREATE DATABASE。迁移数据与函数切换数据库提供方前先npx convex export导出数据切换后需npx convex deploy重新部署函数。延迟敏感后端与数据库必须在同一区域就近部署否则查询性能会显著下降。DATABASE_URL已弃用旧配置中若使用DATABASE_URL启动日志会打印弃用警告并仍按 Postgres 语义处理以保持向后兼容见 run_backend.sh。十、扩展阅读self-hosted/README.md自托管总览包含 Docker 启动、admin key 生成与前端对接self-hosted/docker/docker-compose.yml完整环境变量清单self-hosted/advanced/hosting_on_own_infra.md自有基础设施托管方案self-hosted/advanced/fly/README.mdFly.io 托管方案含 secrets 配置self-hosted/advanced/railway/README.mdRailway 托管方案self-hosted/advanced/upgrading.md版本升级指南crates/db_connection/src/lib.rs 与 crates/clusters/src/lib.rs持久化连接与连接串解析的实现源码。赞分享数据库后端【免费下载链接】convex-backendThe open-source reactive database for app developers项目地址https://gitcode.com/gh_mirrors/co/convex-backend点击查看免费下载相关推荐使用 Redis 作为 sccache 缓存后端环境变量、连接协议与源码级配置指南使用 Redis 作为 sccache 缓存后端环境变量、连接协议与源码级配置指南 导读 本文以 sccache 官方文档 docs/Redis.md htt开发工具构建工具OpenMetadata Prefect 管道连接器配置指南从 Prefect Cloud 到自托管 Server 的接入与实现原理OpenMetadata Prefect 管道连接器配置指南从 Prefect Cloud 到自托管 Server 的接入与实现原理 本篇技术指南以 Open数据目录数据血缘数据治理后端MCP 服务Prisma 1.13 自托管服务器与数据库连接器完全指南Docker 部署、认证与 MySQL/Postgres 配置Prisma 1.13 自托管服务器与数据库连接器完全指南Docker 部署、认证与 MySQL/Postgres 配置 Prisma API 运行在 Pri后端数据库GraphQL创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考