Fix Bug from GitHub Issue
Systematic workflow for turning a GitHub issue into a working fix in the DBHub codebase.
Workflow
- Fetch → 2. Analyze → 3. Locate → 4. Reproduce → 5. Plan → 6. Implement → 7. Verify → 8. PR
Step 1: Fetch Issue
# From 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 |
Step 2: Analyze 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
Step 3: Locate Relevant Code
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.
Step 4: Reproduce
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.
Step 5: Plan the Fix
For non-trivial fixes (multi-file, architectural impact): use EnterPlanMode.
For simple fixes (single function, clear root cause): proceed directly.
Step 6: Implement
- 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
Step 7: Verify
Run the relevant tests to confirm the fix:
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 neededCheck that:
- The failing test (if written) now passes
- No existing tests regressed
- The diff fully addresses the issue
Step 8: Create PR
- Create a branch:
git checkout -b fix/issue-123 - Commit changes referencing the issue:
git add <changed-files> git commit -m "$(cat <<'EOF' Fix: <short description> Closes #123 EOF)" - Push and create the PR:
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.
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