1. 为什么我要给 Claude Code 配一个只读的 GaussDB 通道先说结论我写了一个用 Go 实现的 MCP 服务把 GaussDB 的查询能力以只读方式暴露给 Claude Code让 AI 能直接查表结构、看样本数据、跑分析型 SQL但绝对碰不到任何写操作。整个服务的核心就一句话——连接串层面只读 SQL 解析层面拦截 工具暴露层面收敛三层防护叠在一起才敢让它连生产库。事情的起因很朴素。我手上有一套跑在 GaussDB 上的业务系统日常排查问题、写报表、对数据口径动不动就要连库查半天。Claude Code 出来之后我第一反应就是能不能让它直接帮我查毕竟它写 SQL 的能力比我手敲快多了尤其是那种多表关联加窗口函数的分析语句我描述需求它出 SQL我再也不用对着字段名一个个拼。但问题马上来了。Claude Code 本身是个通用编码助手它没有内置任何数据库连接能力你要让它碰数据库就得通过 MCPModel Context Protocol给它挂工具。MCP 是什么你可以把它理解成 AI 世界的 USB 接口——AI 是主机MCP 服务是外设插上去之后 AI 就能调用外设提供的能力。这个类比我觉得比任何官方定义都好懂USB 协议规定了外设怎么描述自己、主机怎么调用MCP 也一样它规定了工具怎么注册、参数怎么传、结果怎么回。那为什么不直接用现成的数据库 MCP我试过几个通用的 SQL MCP 服务问题集中在三点第一它们大多面向 MySQL、PostgreSQL 这类主流库对 GaussDB 的兼容性参差不齐GaussDB 虽然内核源自 PostgreSQL但在驱动、系统表、语法细节上有自己的东西第二通用服务往往把执行任意 SQL当成一个工具暴露出去这意味着 AI 理论上能跑DELETE、UPDATE、DROP连生产库就是拿命开玩笑第三很多服务没有做结果集大小限制一条SELECT * FROM 大表就能把上下文窗口撑爆。所以我的需求非常明确一个专为 GaussDB 设计的、只读的、带结果集保护的 MCP 服务。用 Go 写是因为它编译出来是单文件二进制扔到服务器上就能跑没有运行时依赖部署成本几乎为零而且 Go 的并发模型处理数据库连接池很顺手标准库的database/sql配合驱动足够稳。这篇文章我会把整个实现思路、关键代码、踩过的坑全部摊开讲。适合两类人看一类是想给 Claude Code 挂数据库能力但担心安全的同行另一类是单纯想学 MCP 服务怎么写的人。哪怕你用的不是 GaussDB把驱动换掉、SQL 方言调一调整套框架可以直接复用。2. 整体架构设计与只读方案选型2.1 三层只读防护的设计逻辑只读这件事绝对不能只靠一层。我见过太多人觉得我建个只读账号就万事大吉了结果账号权限配错、或者 SQL 里藏了个函数调用把数据改了。所以我的设计是三层叠加任何一层被绕过后面还有兜底。第一层是数据库账号权限。这是最根本的一层在 GaussDB 里创建一个只有CONNECT和USAGE权限、对所有业务表只有SELECT权限的账号。这一层的作用是哪怕前面所有代码逻辑都失效了数据库自己会拒绝写操作。这是最后一道物理防线必须有。第二层是 SQL 语句解析拦截。在服务收到 AI 发来的 SQL 之后执行之前先做一次解析判断这条语句是不是纯查询。这里不能简单用字符串匹配SELECT开头因为WITH ... SELECT、EXPLAIN SELECT、甚至SELECT ... INTO都能绕过。我的做法是提取语句的第一个关键字只放行白名单里的查询类语句同时扫描整条语句里有没有危险关键字。第三层是工具暴露收敛。我不给 AI 一个执行任意 SQL的万能工具而是拆成几个语义明确的工具查表列表、查表结构、查索引、执行查询。每个工具的参数都做了约束比如查询工具强制要求带LIMIT或者服务端自动补LIMIT。这三层的顺序是有讲究的工具层挡住AI 想干什么SQL 层挡住AI 写了什么账号层挡住数据库最终执行了什么。任何一层单独拿出来都不够叠起来才踏实。2.2 为什么选 Go 而不是 Python 或 Node选型的时候我认真对比过。Python 写 MCP 服务生态最成熟官方 SDK 就是 Python 的Node 也不差很多示例都是 TS 写的。但我最后还是选了 Go理由有这么几条。部署形态。Go 编译出来是一个静态二进制scp到服务器上chmod x就能跑不需要装 Python 环境、不需要pip install一堆依赖、不用担心虚拟环境冲突。生产服务器上装运行时本身就是一种风险能省则省。并发与连接池。MCP 服务本质是个长驻进程要处理 AI 发来的并发请求。Go 的database/sql自带连接池SetMaxOpenConns、SetMaxIdleConns、SetConnMaxLifetime这几个参数调一调就能控制住对数据库的压力。Python 的同步驱动在高并发下要么阻塞要么得上异步复杂度上去了。类型安全。MCP 的协议消息是 JSON-RPCGo 的结构体标签处理序列化反序列化很干净字段类型错了编译期就报。Python 动态类型写起来快但线上出个None相关的 bug 排查起来头疼。性能。这个其实不是主要因素因为瓶颈在数据库查询本身不在服务框架。但 Go 启动快、内存占用低跑在边缘节点上很舒服。当然 Go 也有代价MCP 的官方 SDK 对 Go 的支持不如 Python 完善很多协议细节我得自己对着规范实现。但 MCP 协议本身不复杂JSON-RPC 2.0 加一套方法约定手写一遍反而理解得更透。2.3 MCP 协议的核心交互流程在动手写代码之前得先把 MCP 的交互流程理清楚。MCP 基于 JSON-RPC 2.0客户端Claude Code和服务端我的 Go 程序之间通过标准输入输出或者 SSE 通信。核心方法有这么几个initialize握手交换协议版本和能力声明tools/list客户端问你有哪些工具服务端返回工具清单和参数 schematools/call客户端说我要调用某个工具参数是这些服务端执行并返回结果notifications/initialized客户端通知服务端初始化完成整个流程是Claude Code 启动时读取配置发现我注册了这个 MCP 服务就拉起进程发initialize然后发tools/list拿到工具列表之后在对话中根据用户意图决定调用哪个工具发tools/call拿到结果后继续推理。理解了这个流程代码结构就清晰了一个主循环读 stdin 的 JSON-RPC 消息根据method字段分发到不同处理函数处理完把响应写回 stdout。就这么简单没有什么魔法。3. 核心细节解析与实操要点3.1 GaussDB 连接与驱动选择GaussDB 的连接这块有个坑要先说清楚。GaussDB 对外提供两种兼容模式一种是兼容 PostgreSQL 的一种是兼容 Oracle 的。我这边用的是 PostgreSQL 兼容模式所以理论上可以用lib/pq或者pgx这类驱动。但实测下来直接用社区驱动会有一些兼容性问题比如某些系统表的字段名对不上、information_schema的返回格式有差异。我的做法是用 GaussDB 官方提供的 Go 驱动或者用pgx配合自定义的查询语句来规避兼容性问题。连接串的格式大致是这样dsn : fmt.Sprintf( host%s port%d user%s password%s dbname%s sslmodedisable connect_timeout10 application_nameclaude_mcp_readonly, host, port, user, password, dbname, )这里有几个参数值得展开说。connect_timeout10是防止数据库不可达时服务卡死10 秒足够建立连接超了就该报错。application_name设成claude_mcp_readonly是个好习惯这样在数据库端的会话列表里一眼就能认出哪些连接是 MCP 服务开的排查问题或者紧急 kill 会话的时候很方便。连接池的配置我调过好几轮最后定下来是这样db.SetMaxOpenConns(5) db.SetMaxIdleConns(2) db.SetConnMaxLifetime(30 * time.Minute) db.SetConnMaxIdleTime(5 * time.Minute)MaxOpenConns设 5 是因为 MCP 服务的查询请求不会特别密集AI 一次对话里顶多查几次5 个连接绰绰有余设大了反而给数据库增加压力。ConnMaxLifetime设 30 分钟是为了避免长时间空闲连接被数据库端或者中间网络设备悄悄断掉导致下次查询报连接已关闭。这个参数在云数据库场景下尤其重要很多云厂商的负载均衡会在几分钟不活动后断开空闲连接。提示连接池参数没有万能值要根据你的数据库规格和 MCP 服务的实际调用频率来调。如果发现查询偶尔报连接错误优先怀疑ConnMaxLifetime设太长。3.2 SQL 只读校验的实现细节这是整个服务最核心的部分也是最容易出问题的地方。我的校验逻辑分两步走先提取语句类型再扫描危险模式。提取语句类型不能简单地strings.HasPrefix因为 SQL 前面可能有注释、可能有空白、可能是WITH开头的 CTE。我的做法是先去掉前导注释和空白然后取第一个单词转大写func extractStatementType(sql string) string { s : stripLeadingComments(sql) s strings.TrimSpace(s) fields : strings.Fields(s) if len(fields) 0 { return } return strings.ToUpper(fields[0]) }白名单我定的是SELECT、WITH、EXPLAIN、SHOW、DESC、DESCRIBE。这几个都是纯查询或者元数据查询不会改数据。注意EXPLAIN要小心EXPLAIN ANALYZE因为ANALYZE会真正执行语句如果里面藏了个写操作就麻烦了。所以我对EXPLAIN额外做了一层检查如果语句里包含ANALYZE就拒绝。第二步是危险关键字扫描。我维护了一个黑名单包含INSERT、UPDATE、DELETE、DROP、TRUNCATE、ALTER、CREATE、GRANT、REVOKE、COPY、VACUUM、CALL、DO这些。扫描的时候要注意不能简单地对整条 SQL 做strings.Contains因为字段名或者字符串字面量里可能包含这些词。比如SELECT * FROM orders WHERE status DELETED这里DELETED包含DELETE简单匹配就误杀了。我的处理方式是先做词法层面的切分把字符串字面量和标识符区分开只在标识符和关键字层面做匹配。这个用正则或者简单的状态机都能实现。如果不想搞太复杂一个折中方案是把黑名单词加上词边界匹配比如\bDELETE\b能过滤掉大部分误判。var dangerousPattern regexp.MustCompile( (?i)\b(INSERT|UPDATE|DELETE|DROP|TRUNCATE|ALTER|CREATE|GRANT|REVOKE|COPY|VACUUM|CALL|DO|MERGE)\b, )注意正则匹配只是辅助手段不能作为唯一防线。真正的安全底线是数据库账号权限。SQL 校验的作用是尽早拦截、给出清晰错误而不是保证绝对安全。3.3 结果集大小控制与超时保护AI 的上下文窗口是有限的一条返回十万行的查询能把整个对话搞崩。所以结果集控制必须做而且要在服务端强制做不能指望 AI 自己加LIMIT。我的策略是双保险。第一服务端自动给查询包一层LIMIT。如果 AI 写的 SQL 没有LIMIT我就在外面套一层SELECT * FROM (原SQL) AS _wrapped LIMIT 1000。如果已经有LIMIT但超过 1000就改成 1000。第二即使有LIMIT返回的数据也要做字节数截断比如单次返回不超过 256KB超了就截断并提示 AI结果被截断请缩小查询范围。超时保护同样重要。我设了两个超时查询超时 30 秒整个工具调用超时 60 秒。查询超时用context.WithTimeout传给db.QueryContext到点自动取消。工具调用超时是防止某些非查询操作比如元数据查询卡住整个服务。ctx, cancel : context.WithTimeout(context.Background(), 30*time.Second) defer cancel() rows, err : db.QueryContext(ctx, wrappedSQL)这里有个细节context取消之后数据库驱动会尝试取消正在执行的查询但 GaussDB 端可能不会立即响应。所以超时时间不能设得太短否则会出现客户端已经超时返回了数据库还在跑的情况白白消耗资源。30 秒是我实测下来比较平衡的值。3.4 工具设计给 AI 的接口要克制工具设计这块我的原则是宁可多几个专用工具也不要一个万能工具。最后我暴露了四个工具工具名功能关键参数list_tables列出指定 schema 下的所有表schema可选默认 publicdescribe_table查看表结构含字段、类型、注释table_name必填list_indexes查看表的索引信息table_name必填run_query执行只读查询sql必填为什么拆这么细因为每个工具的语义越明确AI 用错的概率越低。如果只给一个run_queryAI 想查表结构也得自己拼information_schema的 SQL容易拼错而且不同数据库的系统表不一样。我直接封装好AI 只要说帮我看看 orders 表的结构它就知道调describe_table。run_query的参数描述里我特意写清楚了限制只支持 SELECT 类查询结果最多返回 1000 行超时 30 秒。这个描述会作为工具 schema 的一部分传给 AIAI 看到之后就会自觉写更精确的查询而不是上来就SELECT *。工具返回结果的格式也有讲究。我统一返回 JSON 字符串包含columns列名数组和rows二维数组而不是拼成表格文本。因为结构化数据 AI 更好解析而且后续如果要做二次处理也方便。错误信息也统一格式包含error字段和hint字段hint里给出修正建议比如检测到写操作关键字 DELETE本服务只支持只读查询。4. 完整实操流程与关键代码实现4.1 项目结构与依赖初始化项目结构我保持得很简单就三个文件gaussdb-mcp/ ├── main.go # 入口MCP 主循环 ├── mcp.go # MCP 协议消息定义与处理 ├── db.go # 数据库连接、SQL 校验、查询执行 └── go.mod依赖也很少主要是数据库驱动和 JSON 处理标准库就够。go.mod大概长这样module gaussdb-mcp go 1.21 require ( github.com/jackc/pgx/v5 v5.5.0 )初始化项目就是go mod init gaussdb-mcp然后go get拉驱动。这里我选pgx而不是lib/pq因为pgx性能更好对 PostgreSQL 协议的支持更完整GaussDB 的 PostgreSQL 兼容模式下用起来更顺。4.2 MCP 主循环与消息分发MCP 服务的入口就是一个读 stdin、写 stdout 的循环。核心逻辑是这样func main() { scanner : bufio.NewScanner(os.Stdin) scanner.Buffer(make([]byte, 1024*1024), 1024*1024) encoder : json.NewEncoder(os.Stdout) for scanner.Scan() { line : scanner.Bytes() var req JSONRPCRequest if err : json.Unmarshal(line, req); err ! nil { continue } resp : handleRequest(req) if resp ! nil { encoder.Encode(resp) } } }scanner.Buffer那行很重要默认的bufio.Scanner缓冲区只有 64KBAI 发来的 SQL 如果很长比如带一堆IN条件的查询会超过限制导致读取失败。我把它调到 1MB基本够用。handleRequest里根据method分发func handleRequest(req *JSONRPCRequest) *JSONRPCResponse { switch req.Method { case initialize: return handleInitialize(req) case tools/list: return handleToolsList(req) case tools/call: return handleToolsCall(req) case notifications/initialized: return nil // 通知类消息不需要响应 default: return errorResponse(req.ID, -32601, method not found) } }initialize的响应要声明服务端能力告诉客户端我支持 toolsresult : map[string]interface{}{ protocolVersion: 2024-11-05, capabilities: map[string]interface{}{ tools: map[string]interface{}{}, }, serverInfo: map[string]interface{}{ name: gaussdb-readonly-mcp, version: 1.0.0, }, }协议版本号要和你用的 Claude Code 版本匹配写错了握手会失败。我用的2024-11-05是当时比较稳定的版本你实际用的时候对着官方文档确认一下。4.3 工具注册与 schema 定义tools/list返回的工具清单每个工具都要有name、description、inputSchema。inputSchema是 JSON Schema 格式描述参数类型和是否必填。以run_query为例{ name: run_query, description: 执行只读 SQL 查询。仅支持 SELECT/WITH/EXPLAIN/SHOW 类语句 结果最多返回 1000 行单次查询超时 30 秒。, inputSchema: map[string]interface{}{ type: object, properties: map[string]interface{}{ sql: map[string]interface{}{ type: string, description: 要执行的只读 SQL 语句, }, }, required: []string{sql}, }, }description的写法很关键。我特意把限制条件写进去因为这段描述会进入 AI 的上下文相当于给 AI 的使用说明书。写得越清楚AI 越不容易越界。实测下来把最多 1000 行写进描述后AI 主动加LIMIT的比例明显提高。4.4 查询执行与结果封装run_query的执行流程是校验 SQL → 包装 LIMIT → 执行 → 封装结果。校验部分前面讲过了这里说包装和执行。包装 LIMIT 的逻辑要处理几种情况原 SQL 没有LIMIT、有LIMIT但值太大、有LIMIT且值合理。我的实现是统一在外面套一层func wrapWithLimit(sql string, maxRows int) string { return fmt.Sprintf( SELECT * FROM (%s) AS _mcp_wrapped LIMIT %d, strings.TrimSuffix(strings.TrimSpace(sql), ;), maxRows, ) }这样不管原 SQL 有没有LIMIT最终返回都不会超过maxRows。注意要把末尾的分号去掉否则套进子查询会语法错误。执行和结果封装rows, err : db.QueryContext(ctx, wrappedSQL) if err ! nil { return toolError(查询执行失败: err.Error()) } defer rows.Close() columns, _ : rows.Columns() var result [][]interface{} for rows.Next() { values : make([]interface{}, len(columns)) pointers : make([]interface{}, len(columns)) for i : range values { pointers[i] values[i] } rows.Scan(pointers...) result append(result, values) }这里有个坑rows.Scan扫出来的[]byte类型直接 JSON 序列化会变成 base64 字符串可读性极差。所以我在封装前做了一次类型转换把[]byte转成stringnil转成null。这个转换函数虽然简单但不做的话 AI 拿到的数据全是乱码。结果封装成 JSONoutput : map[string]interface{}{ columns: columns, rows: result, count: len(result), }如果结果被截断len(result) maxRows我在输出里加一个truncated: true字段提示 AI结果可能不完整。4.5 在 Claude Code 中注册服务服务写好了怎么让 Claude Code 用上在 Claude Code 的配置文件里加一段 MCP 服务声明。配置文件的位置各平台不一样我这边是放在用户目录下的配置里。声明格式大致是这样{ mcpServers: { gaussdb-readonly: { command: /path/to/gaussdb-mcp, args: [], env: { GAUSSDB_HOST: your-host, GAUSSDB_PORT: 5432, GAUSSDB_USER: readonly_user, GAUSSDB_PASSWORD: your-password, GAUSSDB_DBNAME: your-db } } } }连接信息通过环境变量传不硬编码在代码里这样二进制可以复用不同环境换配置就行。密码放环境变量里虽然也不是绝对安全但比写在代码里强至少不会跟着代码进版本库。配置好之后重启 Claude Code它启动时会拉起这个进程握手成功后你就能在对话里让它查库了。测试的时候可以先问一句列出数据库里所有的表看它能不能正确调用list_tables。提示第一次配置建议先用测试库验证确认工具调用链路通了、只读拦截生效了再换成生产库的只读账号。别一上来就连生产出问题不好排查。5. 常见问题与排查技巧实录5.1 握手失败与工具不显示最常见的问题是 Claude Code 启动后工具列表是空的或者压根没识别到这个 MCP 服务。排查顺序是这样先看进程有没有被拉起来。如果配置文件路径写错了或者二进制没有执行权限进程根本起不来。手动在终端跑一下二进制看有没有报错输出。再看握手日志。MCP 服务可以通过 stderr 输出调试日志注意是 stderr不是 stdoutstdout 被 JSON-RPC 占用了。我在initialize处理函数里加了一行log.Println(initialize called)日志会打到 stderrClaude Code 一般会把 stderr 收集起来。如果看不到这行日志说明消息根本没到服务端问题在配置或者进程启动环节。如果握手成功但工具不显示检查tools/list的返回格式。JSON-RPC 的响应必须是{jsonrpc:2.0,id:...,result:{...}}结构result里tools是数组。格式错一个字段客户端就解析不了。我踩过一次坑id字段忘了回填客户端一直等响应等到超时。5.2 查询报连接已关闭或超时这个问题的根源通常是连接池配置。前面说过云数据库或者中间有负载均衡的场景空闲连接会被悄悄断掉。表现就是服务刚启动时查询正常放一段时间不查再查就报错。解决办法是把ConnMaxLifetime调短比如 10 分钟让连接在被动断开之前主动重建。同时ConnMaxIdleTime也调短比如 5 分钟空闲太久的连接直接回收。这样虽然会多几次建连开销但避免了用到一半发现连接死了的尴尬。另一个可能是查询本身太慢。如果一条查询跑了 30 秒还没出结果context超时会取消它返回超时错误。这时候要看 SQL 是不是缺索引、是不是扫了全表。我一般会让 AI 先跑EXPLAIN看看执行计划确认走没走索引再决定要不要优化。5.3 SQL 被误拦截只读校验太严格会误杀正常查询。我遇到过几次查询里有个字段叫created_at结果被CREATE关键字匹配到了。这就是前面说的词边界问题\bCREATE\b能解决大部分但字段名如果正好叫create不带下划线还是会误判。我的处理方式是给用户一个申诉通道拦截的时候错误信息里明确说明检测到关键字 XXX如果这是字段名而非操作关键字请用双引号包裹字段名重试。GaussDB 里用双引号包裹标识符是标准做法SELECT create FROM t这样写我的校验逻辑会先剥离引号内容再匹配就不会误判了。还有一种误拦截是WITH开头的 CTE 里包含了DELETE之类的词作为 CTE 名字。这种比较少见遇到了就改 CTE 名字或者用双引号包裹。5.4 结果集太大导致上下文爆炸即使有 1000 行限制如果每行字段特别多、字段值特别长返回的 JSON 也可能几百 KB。AI 的上下文窗口塞进去这么多数据后面的对话就没空间了。我的应对是加字节数限制。在封装结果的时候统计一下序列化后的字节数超过 256KB 就截断行数直到降到限制以内。同时返回truncated: true和hint: 结果过大已截断建议增加 WHERE 条件或减少查询字段。更根本的解决办法是引导 AI 写更精确的查询。我在run_query的描述里加了一句建议先查少量样本确认字段含义再执行完整查询。实测下来AI 看到这句会先跑LIMIT 10看看数据长什么样再决定怎么查全量。5.5 常见问题速查表现象可能原因排查方向工具列表为空配置路径错、进程未启动手动跑二进制看报错握手超时响应格式错、id 未回填检查 JSON-RPC 响应结构查询报连接关闭连接池空闲超时调短 ConnMaxLifetime查询超时SQL 慢、缺索引跑 EXPLAIN 看执行计划SQL 被误拦截关键字匹配到字段名用双引号包裹字段名结果被截断数据量超限加 WHERE 条件或减字段中文乱码字符集不匹配检查连接串字符集参数6. 一些实操心得与扩展思路写这个服务的过程中有几个心得值得单独拎出来说。关于只读账号的权限配置。很多人建只读账号的时候只给了SELECT但忘了USAGE权限。GaussDB 里要访问一个 schema 下的表得先有 schema 的USAGE权限否则连表都看不到。另外information_schema和pg_catalog的访问权限也要确认不然list_tables和describe_table会返回空。我建议建完账号之后用这个账号手动连一次把四个工具对应的查询都跑一遍确认权限没问题。关于 SQL 校验的边界。我一开始想做得非常严格后来发现太严格反而影响体验。比如EXPLAIN我本来想禁掉因为EXPLAIN ANALYZE会真执行。但EXPLAIN对排查慢查询太有用了最后还是放行只是额外拦截ANALYZE。安全性和可用性之间要找个平衡点不能为了绝对安全把工具做成废物。关于日志。MCP 服务的日志一定要打到 stderr而且要有开关。生产环境不需要详细日志但排查问题的时候需要。我用环境变量MCP_LOG_LEVEL控制debug级别打印每条 SQL 和耗时info级别只打印错误。这样平时不吵出问题能查。关于扩展。这个框架搭好之后扩展方向很多。比如可以加一个explain_query工具专门跑执行计划可以加查询结果缓存同样的 SQL 短时间内不重复查可以加慢查询日志把超过阈值的 SQL 记下来供后续优化。甚至可以把只读校验做成可配置的不同环境用不同的白名单。最后分享一个小技巧如果你想让 AI 更懂你的数据库可以在 MCP 服务里加一个get_schema_summary工具返回所有表的名称和注释。AI 在对话开始时调一次就能建立起对整个库的认知后面写 SQL 的时候表名、字段名都不容易写错。这个工具返回的数据量不大就是表名和注释但对 AI 理解上下文帮助很大。我在实际使用中发现AI 查库最常犯的错误不是写错 SQL 语法而是猜错字段名和表关系。有了 schema 摘要之后它写出来的 SQL 一次通过率明显提高。这个投入产出比很高值得加上。