Skip to content

docs: add sqlc scripts documentation for developers#1154

Open
EricGrill wants to merge 49 commits into
btcsuite:sql-walletfrom
EricGrill:docs/sqlc-scripts-documentation
Open

docs: add sqlc scripts documentation for developers#1154
EricGrill wants to merge 49 commits into
btcsuite:sql-walletfrom
EricGrill:docs/sqlc-scripts-documentation

Conversation

@EricGrill

Copy link
Copy Markdown
Contributor

Summary

  • Add comprehensive SQLC development guide for onboarding new developers
  • Document the dual-database (PostgreSQL/SQLite) architecture and workflow
  • Include all Makefile commands, development workflows, and troubleshooting tips
  • Update developer README with link to the new documentation

Motivation

This PR addresses issue #1109, which was motivated by PR #1065 discussions about the need for documentation to help new developers understand the SQLC code generation infrastructure.

What's Documented

The new sqlc_development_guide.md covers:

  1. Overview - Why btcwallet uses SQLC and the benefits
  2. Architecture - How the dual-database support works with separate dialect directories
  3. Directory Structure - Complete file tree explanation
  4. Prerequisites - Docker tools setup and local alternatives
  5. Makefile Commands - All SQL-related commands (sqlc, sql-format, sql-lint, itest-db)
  6. Development Workflow - Step-by-step guide for adding queries and migrations
  7. SQL Query Writing - SQLC annotations and dialect-specific examples
  8. Migration Writing - File naming conventions and PostgreSQL/SQLite differences
  9. Integration Tests - How to run tests with both database backends
  10. CI/CD Integration - What the GitHub Actions workflow checks
  11. Troubleshooting - Common issues and solutions

Test plan

  • Verify documentation renders correctly on GitHub
  • Verify all internal links work
  • Confirm Makefile commands documented match actual commands
  • Check that code examples are syntactically correct

Closes #1109


Generated with Claude Code

GustavoStingelin and others added 30 commits November 19, 2025 23:39
mohamedawnallah and others added 19 commits December 11, 2025 16:35
Co-authored-by: Mohamed Awnallah <mohamedmohey2352@gmail.com>
Fixes linting complains "calculated cyclomatic complexity
for function UpdateWallet is 12, max is 10 (cyclop)"
This commit adds comprehensive documentation for the SQLC code
generation infrastructure used in btcwallet. The guide covers:

- Overview of the dual-database (PostgreSQL/SQLite) architecture
- Complete directory structure explanation
- All Makefile commands for SQL code generation and linting
- Step-by-step development workflow for adding queries and migrations
- SQL dialect differences between PostgreSQL and SQLite
- Integration testing setup and usage
- CI/CD pipeline integration details
- Common troubleshooting scenarios

This documentation addresses issue btcsuite#1109, which was motivated by
PR btcsuite#1065 discussions about the need for onboarding documentation
for new developers working with the SQL backend.

Closes btcsuite#1109

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants