From da3eec68962d0cdc90e206a5f051be6fd55107c7 Mon Sep 17 00:00:00 2001
From: TastyHeadphones <76083688+TastyHeadphones@users.noreply.github.com>
Date: Sun, 27 Sep 2026 13:47:42 +0900
Subject: [PATCH] docs: clarify sqlx.In always uses ? placeholders

People on Postgres often try IN ($1) with In and hit bindVar count
errors. Spell out that In only understands ?, then Rebind for the driver.

Fixes #959
---
 README.md | 3 +++
 bind.go   | 9 +++++++--
 2 files changed, 10 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 5bfd231..e103dfd 100644
--- a/README.md
+++ b/README.md
@@ -18,6 +18,9 @@ In addition to the [godoc API documentation](http://godoc.org/github.com/jmoiron
 there is also some [user documentation](http://jmoiron.github.io/sqlx/) that
 explains how to use `database/sql` along with sqlx.
 
+`sqlx.In` always expands with `?` placeholders. Even on PostgreSQL, write
+`IN (?)` (not `IN ($1)`), then `db.Rebind` the query before running it.
+
 ## Recent Changes
 
 1.3.0:
diff --git a/bind.go b/bind.go
index e698039..4f66426 100644
--- a/bind.go
+++ b/bind.go
@@ -137,8 +137,13 @@ func asSliceForIn(i interface{}) (v reflect.Value, ok bool) {
 }
 
 // In expands slice values in args, returning the modified query string
-// and a new arg list that can be executed by a database. The `query` should
-// use the `?` bindVar.  The return value uses the `?` bindVar.
+// and a new arg list that can be executed by a database.
+//
+// The query must use the `?` bindVar (not `$1`, `@p1`, etc.), even when
+// targeting PostgreSQL or other drivers that normally use a different
+// placeholder style. In always returns a query that still uses `?`; call
+// db.Rebind on the result before Query/Exec so the placeholders match the
+// driver.
 func In(query string, args ...interface{}) (string, []interface{}, error) {
 	// argMeta stores reflect.Value and length for slices and
 	// the value itself for non-slice arguments