fix-bug

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Fix Bug from GitHub Issue

从GitHub Issue修复Bug

Systematic workflow for turning a GitHub issue into a working fix in the DBHub codebase.

将GitHub Issue转化为DBHub代码库中可用修复方案的系统化工作流程。

Workflow

工作流程

Fetch → 2. Analyze → 3. Locate → 4. Reproduce → 5. Plan → 6. Implement → 7. Verify → 8. PR

获取 → 2. 分析 → 3. 定位 → 4. 重现 → 5. 规划 → 6. 实现 → 7. 验证 → 8. 提交PR

Step 1: Fetch Issue

步骤1：获取Issue

bash

undefined

bash

undefined

From URL: https://github.com/owner/repo/issues/123

从URL：https://github.com/owner/repo/issues/123

gh issue view 123 --json title,body,labels,comments,state

From another repo

从其他仓库获取

gh issue view 123 --repo owner/repo --json title,body,labels,comments,state


| Input | How to fetch |
|-------|-------------|
| `https://github.com/owner/repo/issues/42` | `gh issue view 42 --repo owner/repo` |
| `#42` or `42` | `gh issue view 42` (current repo) |
| `owner/repo#42` | `gh issue view 42 --repo owner/repo` |

gh issue view 123 --repo owner/repo --json title,body,labels,comments,state


| 输入内容 | 获取方式 |
|-------|-------------|
| `https://github.com/owner/repo/issues/42` | `gh issue view 42 --repo owner/repo` |
| `#42` 或 `42` | `gh issue view 42`（当前仓库） |
| `owner/repo#42` | `gh issue view 42 --repo owner/repo` |

Step 2: Analyze Issue

步骤2：分析Issue

Extract from the issue:

What's broken: Expected vs actual behavior
Reproduction steps: How to trigger the bug
Environment: Database type, connection method (DSN, SSH tunnel, TOML config), transport (stdio/HTTP)
Labels/comments: May reveal affected area or prior investigation
Linked PRs/issues: Check for related context

从Issue中提取以下信息：

问题所在：预期行为与实际行为的差异
重现步骤：触发bug的操作流程
环境信息：数据库类型、连接方式（DSN、SSH隧道、TOML配置）、传输方式（stdio/HTTP）
标签/评论：可能揭示受影响区域或之前的调查结果
关联PR/Issue：查看相关上下文信息

Step 3: Locate Relevant Code

步骤3：定位相关代码

Use the issue details to identify which part of the codebase is affected. DBHub has a clear modular structure — most bugs fall into one of these areas:

Bug Category	Where to Look	Key Files
Connection failures	Connector implementations	`src/connectors/{db-type}/index.ts` , `src/connectors/manager.ts`
SQL execution errors	Tool handlers	`src/tools/execute-sql.ts` , `src/utils/allowed-keywords.ts`
Schema/table listing	Search tool	`src/tools/search-objects.ts`
DSN parsing issues	Parser logic	`src/connectors/{db-type}/index.ts` (DSNParser), `src/utils/dsn-obfuscate.ts` , `src/utils/safe-url.ts`
SSH tunnel problems	Tunnel utilities	`src/utils/ssh-tunnel.ts` , `src/utils/ssh-config-parser.ts`
TOML config issues	Config loading	`src/config/toml-loader.ts` , `src/types/config.ts`
Multi-database routing	Manager & tools	`src/connectors/manager.ts` , `src/utils/tool-handler-helpers.ts`
Custom tool issues	Custom handler	`src/tools/custom-tool-handler.ts` , `src/tools/registry.ts`
HTTP transport	Server setup	`src/server.ts`
Read-only violations	SQL validation	`src/utils/allowed-keywords.ts` , `src/utils/sql-parser.ts`
Row limiting	SQL rewriting	`src/utils/sql-row-limiter.ts`
API endpoint issues	API handlers	`src/api/sources.ts` , `src/api/requests.ts`
AWS IAM auth	Token signing	`src/utils/aws-rds-signer.ts`

Search for error messages, function names, or file paths mentioned in the issue. Trace the code path from entry point to the failure.

利用Issue细节确定代码库中受影响的部分。DBHub具有清晰的模块化结构——大多数bug属于以下领域之一：

Bug类别	查找位置	关键文件
连接失败	连接器实现	`src/connectors/{db-type}/index.ts` , `src/connectors/manager.ts`
SQL执行错误	工具处理器	`src/tools/execute-sql.ts` , `src/utils/allowed-keywords.ts`
Schema/表列表问题	搜索工具	`src/tools/search-objects.ts`
DSN解析问题	解析器逻辑	`src/connectors/{db-type}/index.ts` （DSNParser）, `src/utils/dsn-obfuscate.ts` , `src/utils/safe-url.ts`
SSH隧道问题	隧道工具	`src/utils/ssh-tunnel.ts` , `src/utils/ssh-config-parser.ts`
TOML配置问题	配置加载	`src/config/toml-loader.ts` , `src/types/config.ts`
多数据库路由	管理器与工具	`src/connectors/manager.ts` , `src/utils/tool-handler-helpers.ts`
自定义工具问题	自定义处理器	`src/tools/custom-tool-handler.ts` , `src/tools/registry.ts`
HTTP传输问题	服务器设置	`src/server.ts`
只读权限违规	SQL验证	`src/utils/allowed-keywords.ts` , `src/utils/sql-parser.ts`
行限制问题	SQL重写	`src/utils/sql-row-limiter.ts`
API端点问题	API处理器	`src/api/sources.ts` , `src/api/requests.ts`
AWS IAM认证	令牌签名	`src/utils/aws-rds-signer.ts`

搜索Issue中提到的错误信息、函数名称或文件路径。跟踪从入口点到故障点的代码路径。

Step 4: Reproduce

步骤4：重现问题

If integration tests exist for the area: Write a failing test that captures the bug. DBHub's test infrastructure makes this straightforward:

Database connector bugs → extend existing integration test in
```
src/connectors/__tests__/
```
Utility bugs → add cases to existing unit tests in
```
src/utils/__tests__/
```
Tool handler bugs → add to
```
src/tools/__tests__/
```
Config bugs → add to
```
src/config/__tests__/
```

Use the test fixtures in

src/__fixtures__/

for multi-database or readonly/max_rows scenarios.

If no test infrastructure applies: Trace the code path and confirm the logic flaw by reading.

如果该区域存在集成测试： 编写一个能复现bug的失败测试。DBHub的测试基础设施让这一过程变得简单：

数据库连接器bug → 在
```
src/connectors/__tests__/
```
中扩展现有集成测试
工具类bug → 在
```
src/utils/__tests__/
```
中添加测试用例到现有单元测试
工具处理器bug → 添加到
```
src/tools/__tests__/
```
配置类bug → 添加到
```
src/config/__tests__/
```

使用

src/__fixtures__/

中的测试夹具处理多数据库或只读/最大行数场景。

如果没有适用的测试基础设施： 跟踪代码路径，通过阅读代码确认逻辑缺陷。

Step 5: Plan the Fix

步骤5：规划修复方案

For non-trivial fixes (multi-file, architectural impact): use

EnterPlanMode

For simple fixes (single function, clear root cause): proceed directly.

对于非简单修复（涉及多文件、架构影响）：使用

EnterPlanMode

。

对于简单修复（单个函数、明确根本原因）：直接进行修复。

Step 6: Implement

步骤6：实现修复

Fix the root cause, not just the symptom
Keep changes minimal and focused
Follow existing code conventions (see CLAUDE.md for style guide)
Use parameterized queries for any database operations
Validate inputs with zod schemas where appropriate

修复根本原因，而非仅仅解决表面症状
保持更改最小且聚焦
遵循现有代码规范（参见CLAUDE.md风格指南）
任何数据库操作使用参数化查询
适当情况下使用zod schema验证输入

Step 7: Verify

步骤7：验证修复

Run the relevant tests to confirm the fix:

bash

pnpm test:unit                    # Quick check — no Docker needed
pnpm test src/path/to/test.ts     # Run the specific test file
pnpm test:integration             # Full integration suite if needed

Check that:

The failing test (if written) now passes
No existing tests regressed
The diff fully addresses the issue

运行相关测试确认修复有效：

bash

pnpm test:unit                    # 快速检查 — 无需Docker
pnpm test src/path/to/test.ts     # 运行特定测试文件
pnpm test:integration             # 如有需要，运行完整集成测试套件

检查以下内容：

编写的失败测试（如果有）现在已通过
现有测试未出现回归问题
代码变更完全解决了Issue中的问题

Step 8: Create PR

步骤8：创建PR

Create a branch:
bash
```
git checkout -b fix/issue-123
```

Commit changes referencing the issue:

bash

git add <changed-files>
git commit -m "$(cat <<'EOF'
Fix: <short description>

Closes #123
EOF
)"

Push and create the PR:

bash

git push -u origin fix/issue-123
gh pr create --title "Fix: <short description>" --body "$(cat <<'EOF'
## Summary
<What was broken and how this fixes it>

## Changes
<Bullet list of changes>

Closes #123

## Test plan
- [ ] Existing tests pass
- [ ] New test covers the bug scenario (if applicable)
EOF
)"

Return the PR URL to the user.

创建分支：
bash
```
git checkout -b fix/issue-123
```

提交变更并引用Issue：

bash

git add <changed-files>
git commit -m "$(cat <<'EOF'
Fix: <简短描述>

Closes #123
EOF
)"

推送并创建PR：

bash

git push -u origin fix/issue-123
gh pr create --title "Fix: <简短描述>" --body "$(cat <<'EOF'
## 总结
<问题是什么以及此修复如何解决问题>

## 变更内容
<变更点的项目符号列表>

Closes #123

## 测试计划
- [ ] 现有测试通过
- [ ] 新增测试覆盖bug场景（如适用）
EOF
)"

将PR URL返回给用户。

Common Mistakes

常见错误

Fixing symptoms instead of root cause: Trace the full code path before patching
Skipping reproduction: A fix without a repro is a guess
Scope creep: Fix the reported issue, don't refactor surrounding code
Missing edge cases: Check if the fix handles related scenarios mentioned in comments
Not testing with the right database: If the bug is database-specific, test with that connector

只修复表面症状而非根本原因：在修补前跟踪完整代码路径
跳过重现步骤：没有重现的修复只是猜测
范围蔓延：只修复报告的Issue，不要重构周边代码
遗漏边缘情况：检查修复是否处理了评论中提到的相关场景
未使用正确的数据库测试：如果bug是数据库特定的，使用对应连接器测试