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 needed

Check 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