從托管托管數(shù)據(jù)庫遷移到本地數(shù)據(jù)庫服務器sqlc 的 servers 配置遷移指南【免費下載鏈接】sqlcGenerate type-safe code from SQL項目地址: https://gitcode.com/gh_mirrors/sq/sqlc從 sqlc 1.27.0 開始managed databases托管數(shù)據(jù)庫功能要求配置文件提供數(shù)據(jù)庫服務器 URI從 sqlc 1.31.1 起配置中新增了頂層servers映射用于聲明可供查詢分析使用的本地數(shù)據(jù)庫服務器連接。本指南基于官方遷移文檔完整講解如何將原先依賴托管數(shù)據(jù)庫的 sqlc 項目遷移到本地運行的 MySQL/PostgreSQL 服務器上涵蓋本地數(shù)據(jù)庫啟動、sqlc 升級、servers配置寫入以及重新生成代碼的全過程并結合倉庫源碼揭示sqlc_managed_前綴數(shù)據(jù)庫的自動創(chuàng)建機制。背景為什么需要遷移sqlc 的 managed databases 特性自 v1.22.0 引入詳見 托管數(shù)據(jù)庫指南可以讓 sqlc 自動創(chuàng)建只讀數(shù)據(jù)庫為查詢分析query analysis、lint 檢查sqlc vet和驗證sqlc verify提供真實的數(shù)據(jù)庫環(huán)境。相比純靜態(tài)解析連接真實數(shù)據(jù)庫能讓 sqlc 對復雜查詢生成更準確的類型安全代碼。從 v1.27.0 開始managed databases 不再使用云端隱式托管而是要求在你的配置文件中顯式提供一個數(shù)據(jù)庫服務器的 URI連接字符串。這意味著項目必須能訪問到一個真實運行的數(shù)據(jù)庫服務器。為了讓遷移過程更平滑v1.31.1 又引入了頂層servers配置段允許在配置中聲明一個或多個數(shù)據(jù)庫服務器供 managed database 邏輯按引擎匹配使用。因此本指南的目標是把項目的查詢分析底座從托管遷移到本地運行的真實數(shù)據(jù)庫服務器整體分三步走在本地啟動數(shù)據(jù)庫服務器推薦 Docker Compose同時支持 MySQL 與 PostgreSQL升級 sqlc 到 v1.31.1 或更高版本以使用servers配置在配置文件中添加servers映射并重新執(zhí)行sqlc generate。第一步在本地運行一個數(shù)據(jù)庫服務器本地運行數(shù)據(jù)庫服務器的方案很多官方遷移指南推薦使用 [Docker Compose]可同時支持 MySQL 和 PostgreSQL如果你在 macOS 上使用 PostgreSQL[Postgres.app] 也是不錯的選擇。說明本指南中的 Docker Compose 配置與端口均以官方遷移文檔為準請根據(jù)你本機實際占用情況調(diào)整端口映射。使用 Docker Compose 啟動 MySQL創(chuàng)建docker-compose.yml內(nèi)容如下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容器啟動時自動創(chuàng)建的初始數(shù)據(jù)庫名后續(xù) sqlc 會在該服務器上以sqlc_managed_前綴另建分析用數(shù)據(jù)庫MYSQL_ROOT_PASSWORDroot 用戶的密碼對應后續(xù)servers.uri連接串中的密碼部分MYSQL_ROOT_HOST: %允許任意主機通過 root 連接避免容器網(wǎng)絡下連接被拒3306:3306將容器 3306 端口映射到宿主機servers.uri中的localhost:3306即訪問此端口。使用 Docker Compose 啟動 PostgreSQL若使用 PostgreSQL創(chuàng)建如下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數(shù)據(jù)庫超級用戶及密碼對應連接串中的用戶名和密碼POSTGRES_DB: postgres初始默認數(shù)據(jù)庫5432:5432映射到宿主機的 PostgreSQL 默認端口。啟動服務docker compose up -d啟動后可通過docker compose ps確認容器狀態(tài)并驗證端口連通性例如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 開始面向任意可訪問的數(shù)據(jù)庫服務器同版本還收錄了 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數(shù)據(jù)庫服務器連接 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的完整配置示例如下對齊 托管數(shù)據(jù)庫指南 的格式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使用環(huán)境變量推薦連接串中可能包含密碼等敏感信息官方文檔推薦使用${}語法引用環(huán)境變量避免將憑據(jù)硬編碼進配置文件version: 2 servers: - engine: postgresql uri: ${DATABASE_URI} sql: - schema: schema.sql queries: query.sql engine: postgresql database: managed: true從源碼實現(xiàn)看URI 中的${...}占位符會在運行時由 internal/shfmt 的Replacer展開dbmanager客戶端在創(chuàng)建連接前調(diào)用m.replacer.Replace(base)完成替換見 internal/dbmanager/client.go因此密碼等敏感信息可以安全地放在環(huán)境變量中。與 cloud 配置的關系遷移前配置文件中的cloud.project用于關聯(lián) sqlc Cloud 項目遷移到本地服務器后servers與cloud相互獨立、可以并存。如果你不再使用云端服務保留或移除cloud段均可servers段負責提供本地連接。若項目未配置servers卻使用了managed: true運行時將報錯no PostgreSQL database server found錯誤文案見 internal/dbmanager/client.go這正是遷移后最常見的問題之一。第四步重新生成代碼完成配置后在項目根目錄執(zhí)行sqlc generate官方遷移指南指出一個帶有sqlc_managed_前綴的數(shù)據(jù)庫會被自動創(chuàng)建并用于查詢分析。sqlc_managed_數(shù)據(jù)庫的底層原理這一行為的實現(xiàn)位于 internal/dbmanager/client.go 的ManagedClient.CreateDatabase其工作流程可以概括為計算數(shù)據(jù)庫名以查詢集 schema 的 SQL 內(nèi)容Migrations為輸入用 FNV-64 哈希生成一個固定 ID再拼接前綴得到數(shù)據(jù)庫名sqlc_managed_hash若調(diào)用方未顯式指定Prefix默認前綴即sqlc_managed見 internal/dbmanager/client.go。由于名稱由 schema 內(nèi)容哈希決定同一 schema 的后續(xù)運行會復用同名數(shù)據(jù)庫按引擎匹配服務器遍歷配置中的servers找到與查詢集引擎一致的服務器 URI當前僅放行mysql與postgresql兩種引擎其他引擎直接返回unsupported engine錯誤internal/dbmanager/client.go冪等建庫先查詢pg_database判斷數(shù)據(jù)庫是否已存在不存在則執(zhí)行CREATE DATABASE并通過singleflight保證并發(fā)運行只建一次應用 schema連接到新庫逐條執(zhí)行查詢集的 DDLmigrations任一條失敗則DROP DATABASE ... WITH (FORCE)回滾清理internal/dbmanager/client.go。也就是說sqlc generate會自動完成建庫 → 灌入 schema → 用真實數(shù)據(jù)庫做查詢分析 → 按查詢緩存分析結果的完整鏈路這也是 managed databases 相比純靜態(tài)解析能顯著提升復雜查詢代碼質(zhì)量的原因。順帶一提sqlc createdb倉庫還提供了sqlc createdb命令Create an ephemeral database見 CLI 參考。它的實現(xiàn)位于 internal/cmd/createdb.go會找出配置中database.managed: true的查詢集將 schema 文件自動剔除回滾語句作為遷移交給dbmanager建庫并使用sqlc_createdb_時間戳作為前綴最終把新庫的 URI 打印到標準輸出。它常被用于在sqlc vet、sqlc verify等流程之外手動調(diào)試分析環(huán)境。遷移后的驗證與日常使用完成sqlc generate后建議按以下順序驗證遷移結果確認代碼生成正常sqlc generate無報錯且生成的*.sql.go文件類型準確運行 vet 檢查sqlc vet會在 managed database 上執(zhí)行依賴真實連接的 lint 規(guī)則如內(nèi)置的sqlc/db-prepare它會對每條查詢做真實 prepare 以驗證 SQL 合法性。從 internal/cmd/vet.go 可以看到sqlc vet同樣通過dbmanager.NewClient(c.Conf.Servers)走 managed 建庫鏈路與sqlc generate共用同一套基礎設施檢查數(shù)據(jù)庫服務器\lPostgreSQL或SHOW DATABASES;MySQL可以看到sqlc_managed_*前綴的分析庫已被創(chuàng)建說明配置生效。如果你的 lint 規(guī)則需要真實連接但尚未配置任何規(guī)則推薦先啟用內(nèi)置規(guī)則sqlc/db-prepare最小配置如下來自 托管數(shù)據(jù)庫指南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 只指定了主機與端口若數(shù)據(jù)庫要求認證需在 URI 中補齊用戶名密碼例如mysql://root:mysecretpasswordlocalhost:3306/dinotest。PostgreSQL 建議顯式帶上?sslmodedisable避免本機 TLS 協(xié)商失敗。引擎支持范圍managed 自動建庫目前只支持 MySQL 與 PostgreSQL。如果你的查詢集使用 SQLite 等其他引擎即使配置了servers也不會走 managed 鏈路。報錯no PostgreSQL database server found說明沒有在servers中找到與查詢集引擎匹配的條目。請檢查servers中engine字段與查詢集engine是否一致。報錯unsupported engine查詢集引擎不是mysql/postgresql見 internal/dbmanager/client.go。調(diào)試連接行為SQLCDEBUGdatabasesmanaged可以強制禁用非 managed 的直連僅允許 managed 數(shù)據(jù)庫連接用于排查連接來源問題相關邏輯見 internal/cmd/vet.go。更多調(diào)試開關可參考 環(huán)境變量參考。清理分析庫sqlc_managed_*數(shù)據(jù)庫由 sqlc 按需復用名稱由 schema 哈希決定一般無需手動清理如需徹底重建可在服務器上手動刪除對應數(shù)據(jù)庫后重新sqlc generate。與sqlc verify的關系sqlc verify對比云端歸檔查詢集與本地結果同樣使用dbmanager.NewClient(conf.Servers)復用本地服務器見 internal/cmd/verify.go因此遷移后該命令也會自動使用本地 managed 數(shù)據(jù)庫?？偨Y遷移到本地數(shù)據(jù)庫服務器的本質(zhì)是把云端托管這一環(huán)節(jié)替換為配置servers指向本地運行的 MySQL/PostgreSQL其余使用方式managed: true、sqlc generate自動建sqlc_managed_前綴數(shù)據(jù)庫、sqlc vet與sqlc verify復用分析庫保持不變。完成 Docker Compose 啟動數(shù)據(jù)庫、升級 sqlc 至 v1.31.1、寫入servers配置三步之后你的項目即可完全脫離托管環(huán)境在本地獲得同等甚至更可控的查詢分析能力。【免費下載鏈接】sqlcGenerate type-safe code from SQL項目地址: https://gitcode.com/gh_mirrors/sq/sqlc創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考