Skip to content

docs: fix parameter syntax inconsistency for MySQL and SQLite #4036

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Aug 2, 2025

Conversation

kotahorii
Copy link
Contributor

Summary

This PR fixes parameter syntax inconsistency in the howto documentation where examples only showed PostgreSQL syntax ($1, $2), causing confusion and errors for MySQL and SQLite users.

Problem

As reported in #3697, the generic howto documentation files showed only PostgreSQL parameter syntax:

  • Used $1, $2 placeholders which only work with PostgreSQL
  • Caused silent failures in MySQL code generation (functions generated without parameters)
  • Caused syntax errors in SQLite compilation
  • Created confusion for developers using multi-database setups

Solution

Updated four key documentation files to include database-specific examples:

Modified Files:

  • docs/howto/update.md
  • docs/howto/insert.md
  • docs/howto/delete.md
  • docs/howto/select.md

Changes Made:

Added database-specific sections with clear syntax examples:

  • PostgreSQL: $1, $2 syntax
  • MySQL and SQLite: ? placeholder syntax

Added explanatory notes about parameter binding differences

Maintained existing Go code examples (they remain database-agnostic)

Added clarification about MySQL not supporting RETURNING clause

Example of Changes

Before:

-- name: UpdateAuthor :exec
UPDATE authors SET bio = $2 WHERE id = $1;

After:

**PostgreSQL:**
-- name: UpdateAuthor :exec
UPDATE authors SET bio = $2 WHERE id = $1;

**MySQL and SQLite:**
-- name: UpdateAuthor :exec
UPDATE authors SET bio = ? WHERE id = ?;

Impact

  • ✅ Eliminates confusion for MySQL/SQLite users
  • ✅ Prevents silent code generation failures
  • ✅ Provides clear guidance for multi-database projects
  • ✅ Maintains backward compatibility (PostgreSQL examples preserved)
  • ✅ Aligns with existing database-specific tutorial documentation

Test Plan

  • Verified all syntax examples are database-appropriate
  • Confirmed tutorials already use correct database-specific syntax
  • Ensured documentation structure remains consistent
  • Cross-referenced with official database documentation

Fixes #3697

🤖 Generated with Claude Code

Update howto documentation to include database-specific parameter syntax:
- PostgreSQL: $1, $2, etc.
- MySQL/SQLite: ? placeholders

Changes made to:
- docs/howto/update.md
- docs/howto/insert.md
- docs/howto/delete.md
- docs/howto/select.md

This resolves confusion where the generic examples only showed PostgreSQL
syntax, causing silent failures in MySQL code generation and syntax errors
in SQLite.

Fixes sqlc-dev#3697

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
@dosubot dosubot bot added the size:M This PR changes 30-99 lines, ignoring generated files. label Aug 2, 2025
@kyleconroy kyleconroy merged commit 17ace55 into sqlc-dev:main Aug 2, 2025
8 checks passed
@dosubot dosubot bot added the lgtm This PR has been approved by a maintainer label Aug 2, 2025
@kotahorii kotahorii deleted the fix-mysql-sqlite-docs-syntax branch August 3, 2025 01:46
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
lgtm This PR has been approved by a maintainer size:M This PR changes 30-99 lines, ignoring generated files.
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Updating Rows: Documented syntax doesn't produce expected result for MySQL and Sqlite
2 participants