从托管托管数据库迁移到本地数据库服务器：sqlc 的 servers 配置迁移指南

从托管托管数据库迁移到本地数据库服务器sqlc 的 servers 配置迁移指南【免费下载链接】sqlcGenerate type-safe code from SQL项目地址: https://gitcode.com/gh_mirrors/sq/sqlc从 sqlc 1.27.0 开始managed databases托管数据库功能要求配置文件提供数据库服务器 URI从 sqlc 1.31.1 起配置中新增了顶层servers映射用于声明可供查询分析使用的本地数据库服务器连接。本指南基于官方迁移文档完整讲解如何将原先依赖托管数据库的 sqlc 项目迁移到本地运行的 MySQL/PostgreSQL 服务器上涵盖本地数据库启动、sqlc 升级、servers配置写入以及重新生成代码的全过程并结合仓库源码揭示sqlc_managed_前缀数据库的自动创建机制。背景为什么需要迁移sqlc 的 managed databases 特性自 v1.22.0 引入详见 托管数据库指南可以让 sqlc 自动创建只读数据库为查询分析query analysis、lint 检查sqlc vet和验证sqlc verify提供真实的数据库环境。相比纯静态解析连接真实数据库能让 sqlc 对复杂查询生成更准确的类型安全代码。从 v1.27.0 开始managed databases 不再使用云端隐式托管而是要求在你的配置文件中显式提供一个数据库服务器的 URI连接字符串。这意味着项目必须能访问到一个真实运行的数据库服务器。为了让迁移过程更平滑v1.31.1 又引入了顶层servers配置段允许在配置中声明一个或多个数据库服务器供 managed database 逻辑按引擎匹配使用。因此本指南的目标是把项目的查询分析底座从托管迁移到本地运行的真实数据库服务器整体分三步走在本地启动数据库服务器推荐 Docker Compose同时支持 MySQL 与 PostgreSQL升级 sqlc 到 v1.31.1 或更高版本以使用servers配置在配置文件中添加servers映射并重新执行sqlc generate。第一步在本地运行一个数据库服务器本地运行数据库服务器的方案很多官方迁移指南推荐使用 [Docker Compose]可同时支持 MySQL 和 PostgreSQL如果你在 macOS 上使用 PostgreSQL[Postgres.app] 也是不错的选择。说明本指南中的 Docker Compose 配置与端口均以官方迁移文档为准请根据你本机实际占用情况调整端口映射。使用 Docker Compose 启动 MySQL创建docker-compose.yml内容如下version: 3.8 services: mysql: image: mysql/mysql-server:8.0 ports: - 3306:3306 restart: always environment: MYSQL_DATABASE: dinotest MYSQL_ROOT_PASSWORD: mysecretpassword MYSQL_ROOT_HOST: %要点说明MYSQL_DATABASE: dinotest容器启动时自动创建的初始数据库名后续 sqlc 会在该服务器上以sqlc_managed_前缀另建分析用数据库MYSQL_ROOT_PASSWORDroot 用户的密码对应后续servers.uri连接串中的密码部分MYSQL_ROOT_HOST: %允许任意主机通过 root 连接避免容器网络下连接被拒3306:3306将容器 3306 端口映射到宿主机servers.uri中的localhost:3306即访问此端口。使用 Docker Compose 启动 PostgreSQL若使用 PostgreSQL创建如下docker-compose.ymlversion: 3.8 services: postgresql: image: postgres:16 ports: - 5432:5432 restart: always environment: POSTGRES_DB: postgres POSTGRES_PASSWORD: mysecretpassword POSTGRES_USER: postgres要点说明POSTGRES_USER/POSTGRES_PASSWORD数据库超级用户及密码对应连接串中的用户名和密码POSTGRES_DB: postgres初始默认数据库5432:5432映射到宿主机的 PostgreSQL 默认端口。启动服务docker compose up -d启动后可通过docker compose ps确认容器状态并验证端口连通性例如mysql -h127.0.0.1 -P3306 -uroot -p或psql -h localhost -p 5432 -U postgres。第二步升级 sqlcservers配置项需要较新的 sqlc 版本。官方迁移指南明确要求必须运行sqlc v1.31.1 或更高版本才能使用servers配置。从仓库的 变更日志 可以看到相关演进脉络v1.27.0 引入了 Managed databases with any accessible servermanaged databases 开始面向任意可访问的数据库服务器同版本还收录了 Add migration guide for hosted managed databases 的文档变更正是本指南所对应的迁移文档。升级方式取决于你的安装渠道如go install、Homebrew、预编译二进制等请以官方安装方式为准。升级完成后可用sqlc version确认版本号。第三步向配置中添加 serversservers是配置文件sqlc.yaml/sqlc.yml/sqlc.json详见 配置参考中的顶层映射。官方迁移指南给出的 diff 如下version: 2 cloud: project: PROJECT_ID servers: - name: mysql uri: mysql://localhost:3306 - name: postgres uri: postgres://localhost:5432/postgres?sslmodedisable从源码结构看servers对应 internal/config/config.go 中的Config.Servers []Server字段每个Server包含三个可选字段字段类型说明namestring服务器名称便于识别json:name,omitempty可选enginestring引擎标识取值如mysql、postgresql可选uristring数据库服务器连接 URI必填其中引擎常量定义于同一文件的 internal/config/config.gomysql、postgresql、sqlite、clickhouse、googlesql、mssql、duckdb。不过需要注意managed database 的自动建库逻辑目前只支持 MySQL 与 PostgreSQL详见下文原理分析。同时使用 MySQL 与 PostgreSQL如果你的项目同时包含 MySQL 和 PostgreSQL 的查询集可以在servers中并列声明两台服务器由 managed 客户端按引擎自动匹配这一点可在 internal/dbmanager/client.go 的源码中看到遍历servers列表按server.Engine engine选择对应的URI。结合managed: true的完整配置示例如下对齐 托管数据库指南 的格式version: 2 servers: - name: mysql engine: mysql uri: mysql://root:mysecretpasswordlocalhost:3306/dinotest - name: postgres engine: postgresql uri: postgres://postgres:mysecretpasswordlocalhost:5432/postgres?sslmodedisable sql: - schema: schema.sql queries: query.sql engine: postgresql database: managed: true gen: go: out: db使用环境变量推荐连接串中可能包含密码等敏感信息官方文档推荐使用${}语法引用环境变量避免将凭据硬编码进配置文件version: 2 servers: - engine: postgresql uri: ${DATABASE_URI} sql: - schema: schema.sql queries: query.sql engine: postgresql database: managed: true从源码实现看URI 中的${...}占位符会在运行时由 internal/shfmt 的Replacer展开dbmanager客户端在创建连接前调用m.replacer.Replace(base)完成替换见 internal/dbmanager/client.go因此密码等敏感信息可以安全地放在环境变量中。与 cloud 配置的关系迁移前配置文件中的cloud.project用于关联 sqlc Cloud 项目迁移到本地服务器后servers与cloud相互独立、可以并存。如果你不再使用云端服务保留或移除cloud段均可servers段负责提供本地连接。若项目未配置servers却使用了managed: true运行时将报错no PostgreSQL database server found错误文案见 internal/dbmanager/client.go这正是迁移后最常见的问题之一。第四步重新生成代码完成配置后在项目根目录执行sqlc generate官方迁移指南指出一个带有sqlc_managed_前缀的数据库会被自动创建并用于查询分析。sqlc_managed_数据库的底层原理这一行为的实现位于 internal/dbmanager/client.go 的ManagedClient.CreateDatabase其工作流程可以概括为计算数据库名以查询集 schema 的 SQL 内容Migrations为输入用 FNV-64 哈希生成一个固定 ID再拼接前缀得到数据库名sqlc_managed_hash若调用方未显式指定Prefix默认前缀即sqlc_managed见 internal/dbmanager/client.go。由于名称由 schema 内容哈希决定同一 schema 的后续运行会复用同名数据库按引擎匹配服务器遍历配置中的servers找到与查询集引擎一致的服务器 URI当前仅放行mysql与postgresql两种引擎其他引擎直接返回unsupported engine错误internal/dbmanager/client.go幂等建库先查询pg_database判断数据库是否已存在不存在则执行CREATE DATABASE并通过singleflight保证并发运行只建一次应用 schema连接到新库逐条执行查询集的 DDLmigrations任一条失败则DROP DATABASE ... WITH (FORCE)回滚清理internal/dbmanager/client.go。也就是说sqlc generate会自动完成建库 → 灌入 schema → 用真实数据库做查询分析 → 按查询缓存分析结果的完整链路这也是 managed databases 相比纯静态解析能显著提升复杂查询代码质量的原因。顺带一提sqlc createdb仓库还提供了sqlc createdb命令Create an ephemeral database见 CLI 参考。它的实现位于 internal/cmd/createdb.go会找出配置中database.managed: true的查询集将 schema 文件自动剔除回滚语句作为迁移交给dbmanager建库并使用sqlc_createdb_时间戳作为前缀最终把新库的 URI 打印到标准输出。它常被用于在sqlc vet、sqlc verify等流程之外手动调试分析环境。迁移后的验证与日常使用完成sqlc generate后建议按以下顺序验证迁移结果确认代码生成正常sqlc generate无报错且生成的*.sql.go文件类型准确运行 vet 检查sqlc vet会在 managed database 上执行依赖真实连接的 lint 规则如内置的sqlc/db-prepare它会对每条查询做真实 prepare 以验证 SQL 合法性。从 internal/cmd/vet.go 可以看到sqlc vet同样通过dbmanager.NewClient(c.Conf.Servers)走 managed 建库链路与sqlc generate共用同一套基础设施检查数据库服务器\lPostgreSQL或SHOW DATABASES;MySQL可以看到sqlc_managed_*前缀的分析库已被创建说明配置生效。如果你的 lint 规则需要真实连接但尚未配置任何规则推荐先启用内置规则sqlc/db-prepare最小配置如下来自 托管数据库指南version: 2 servers: - engine: postgresql uri: postgres://localhost:5432/postgres?sslmodedisable sql: - schema: schema.sql queries: query.sql engine: postgresql database: managed: true rules: - sqlc/db-prepare常见问题与注意事项连接串格式mysql://localhost:3306这类 URI 只指定了主机与端口若数据库要求认证需在 URI 中补齐用户名密码例如mysql://root:mysecretpasswordlocalhost:3306/dinotest。PostgreSQL 建议显式带上?sslmodedisable避免本机 TLS 协商失败。引擎支持范围managed 自动建库目前只支持 MySQL 与 PostgreSQL。如果你的查询集使用 SQLite 等其他引擎即使配置了servers也不会走 managed 链路。报错no PostgreSQL database server found说明没有在servers中找到与查询集引擎匹配的条目。请检查servers中engine字段与查询集engine是否一致。报错unsupported engine查询集引擎不是mysql/postgresql见 internal/dbmanager/client.go。调试连接行为SQLCDEBUGdatabasesmanaged可以强制禁用非 managed 的直连仅允许 managed 数据库连接用于排查连接来源问题相关逻辑见 internal/cmd/vet.go。更多调试开关可参考 环境变量参考。清理分析库sqlc_managed_*数据库由 sqlc 按需复用名称由 schema 哈希决定一般无需手动清理如需彻底重建可在服务器上手动删除对应数据库后重新sqlc generate。与sqlc verify的关系sqlc verify对比云端归档查询集与本地结果同样使用dbmanager.NewClient(conf.Servers)复用本地服务器见 internal/cmd/verify.go因此迁移后该命令也会自动使用本地 managed 数据库。总结迁移到本地数据库服务器的本质是把云端托管这一环节替换为配置servers指向本地运行的 MySQL/PostgreSQL其余使用方式managed: true、sqlc generate自动建sqlc_managed_前缀数据库、sqlc vet与sqlc verify复用分析库保持不变。完成 Docker Compose 启动数据库、升级 sqlc 至 v1.31.1、写入servers配置三步之后你的项目即可完全脱离托管环境在本地获得同等甚至更可控的查询分析能力。【免费下载链接】sqlcGenerate type-safe code from SQL项目地址: https://gitcode.com/gh_mirrors/sq/sqlc创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考