From 4976cf15f208edd185b570d56eb2bae6fcb95a52 Mon Sep 17 00:00:00 2001
From: kotahorii <khorii.micron@gmail.com>
Date: Sat, 2 Aug 2025 22:17:29 +0900
Subject: [PATCH] docs: fix parameter syntax inconsistency for MySQL and SQLite
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

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 #3697

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

Co-Authored-By: Claude <noreply@anthropic.com>
---
 docs/howto/delete.md | 11 +++++++++++
 docs/howto/insert.md | 35 +++++++++++++++++++++++++++++++++++
 docs/howto/select.md | 15 +++++++++++++++
 docs/howto/update.md | 19 +++++++++++++++++++
 4 files changed, 80 insertions(+)

diff --git a/docs/howto/delete.md b/docs/howto/delete.md
index 68d22a2e46..95045a37a6 100644
--- a/docs/howto/delete.md
+++ b/docs/howto/delete.md
@@ -5,11 +5,22 @@ CREATE TABLE authors (
   id         SERIAL PRIMARY KEY,
   bio        text   NOT NULL
 );
+```
+
+The parameter syntax varies by database engine:
 
+**PostgreSQL:**
+```sql
 -- name: DeleteAuthor :exec
 DELETE FROM authors WHERE id = $1;
 ```
 
+**MySQL and SQLite:**
+```sql
+-- name: DeleteAuthor :exec
+DELETE FROM authors WHERE id = ?;
+```
+
 ```go
 package db
 
diff --git a/docs/howto/insert.md b/docs/howto/insert.md
index ae892998ec..7bb02d6745 100644
--- a/docs/howto/insert.md
+++ b/docs/howto/insert.md
@@ -5,11 +5,22 @@ CREATE TABLE authors (
   id         SERIAL PRIMARY KEY,
   bio        text   NOT NULL
 );
+```
+
+The parameter syntax varies by database engine:
 
+**PostgreSQL:**
+```sql
 -- name: CreateAuthor :exec
 INSERT INTO authors (bio) VALUES ($1);
 ```
 
+**MySQL and SQLite:**
+```sql
+-- name: CreateAuthor :exec
+INSERT INTO authors (bio) VALUES (?);
+```
+
 ```go
 package db
 
@@ -51,7 +62,10 @@ CREATE TABLE authors (
   name text      NOT NULL,
   bio  text
 );
+```
 
+**PostgreSQL:**
+```sql
 -- name: CreateAuthor :one
 INSERT INTO authors (
   name, bio
@@ -69,6 +83,27 @@ INSERT INTO authors (
 RETURNING id;
 ```
 
+**SQLite (with RETURNING support):**
+```sql
+-- name: CreateAuthor :one
+INSERT INTO authors (
+  name, bio
+) VALUES (
+  ?, ?
+)
+RETURNING *;
+
+-- name: CreateAuthorAndReturnId :one
+INSERT INTO authors (
+  name, bio
+) VALUES (
+  ?, ?
+)
+RETURNING id;
+```
+
+Note: MySQL does not support the `RETURNING` clause. Use `:execresult` instead to get the last insert ID.
+
 ```go
 package db
 
diff --git a/docs/howto/select.md b/docs/howto/select.md
index 4c5ae269a8..9a53a1d9ef 100644
--- a/docs/howto/select.md
+++ b/docs/howto/select.md
@@ -8,8 +8,12 @@ CREATE TABLE authors (
   bio        text   NOT NULL,
   birth_year int    NOT NULL
 );
+```
 
+The parameter syntax varies by database engine:
 
+**PostgreSQL:**
+```sql
 -- name: GetAuthor :one
 SELECT * FROM authors
 WHERE id = $1;
@@ -19,6 +23,17 @@ SELECT * FROM authors
 ORDER BY id;
 ```
 
+**MySQL and SQLite:**
+```sql
+-- name: GetAuthor :one
+SELECT * FROM authors
+WHERE id = ?;
+
+-- name: ListAuthors :many
+SELECT * FROM authors
+ORDER BY id;
+```
+
 A few new pieces of code are generated beyond the `Author` struct. An interface
 for the underlying database is generated. The `*sql.DB` and `*sql.Tx` types
 satisfy this interface.
diff --git a/docs/howto/update.md b/docs/howto/update.md
index 3abb99ba23..f96306d0f2 100644
--- a/docs/howto/update.md
+++ b/docs/howto/update.md
@@ -12,11 +12,20 @@ CREATE TABLE authors (
 If your query has a single parameter, your Go method will also have a single
 parameter.
 
+The parameter syntax varies by database engine:
+
+**PostgreSQL:**
 ```sql
 -- name: UpdateAuthorBios :exec
 UPDATE authors SET bio = $1;
 ```
 
+**MySQL and SQLite:**
+```sql
+-- name: UpdateAuthorBios :exec
+UPDATE authors SET bio = ?;
+```
+
 ```go
 package db
 
@@ -52,12 +61,22 @@ func (q *Queries) UpdateAuthorBios(ctx context.Context, bio string) error {
 If your query has more than one parameter, your Go method will accept a
 `Params` struct.
 
+**PostgreSQL:**
 ```sql
 -- name: UpdateAuthor :exec
 UPDATE authors SET bio = $2
 WHERE id = $1;
 ```
 
+**MySQL and SQLite:**
+```sql
+-- name: UpdateAuthor :exec
+UPDATE authors SET bio = ?
+WHERE id = ?;
+```
+
+Note: For MySQL and SQLite, parameters are bound in the order they appear in the query, regardless of the order in the function signature.
+
 ```go
 package db