fix(compiler): scope-aware column resolution in subqueries (#4251)

When resolving an unqualified column reference inside a subquery, sqlc's
analyzer matched against every table in scope across the whole query,
producing a spurious "column reference ... is ambiguous" error for
queries that real PostgreSQL resolves unambiguously via lexical scope.

Example from the issue:

    SELECT * FROM t1 WHERE id IN (
        SELECT t1_id FROM t2 WHERE id = $1
    );

Real Postgres binds the outer "id" to t1.id and the inner "id" to
t2.id by lexical scope. sqlc was flattening every FROM-clause RangeVar
in the whole query into one search list and triggering "ambiguous" on
the inner id.

Two small changes:

* internal/compiler/find_params.go — when paramSearch.Visit enters a
  SelectStmt whose FROM clause has exactly one RangeVar, capture it as
  the current scope (paramSearch.rangeVar). The walker propagates this
  through the returned visitor, so ParamRefs encountered in the same
  SelectStmt's WHERE/GROUP/etc. inherit the inner scope. The
  exactly-one guard ensures we don't silently pick a winner when the
  FROM clause is genuinely multi-table at the same level — those cases
  must keep iterating every table so true ambiguity (e.g.
  "SELECT t1.id FROM t1, t2 WHERE id = $1") still errors.

* internal/compiler/resolve.go — when resolving an unqualified column,
  if no alias is given but ref.rv points to an in-scope table that
  actually contains the column, narrow the search to that table only.
  If the column is absent from the inner table, fall back to the full
  search list so correlated-subquery references to an outer column
  continue to work.

Tests:

* internal/compiler/resolve_test.go — new unit test covering
  narrowToInnermostScope across nil-rv, column-in-inner-scope (narrow),
  column-absent (fall back), and unknown-table (fall back).

* internal/endtoend/testdata/subquery_scope_4251/ — end-to-end fixture
  reproducing the exact query from the issue under postgresql/pgx/v5;
  generated code asserted against the golden files.

Verified locally:

* /tmp/repro4251 generate now returns EXIT=0 (was EXIT=1 with
  'relation "id" ambiguous').
* SELECT t1.id FROM t1, t2 WHERE id = $1 still correctly errors with
  'ambiguous'.
* Correlated subquery
  (SELECT SUM(total) FROM orders WHERE customer_id = c.id) still
  resolves cleanly.
* go test ./internal/compiler/... ./internal/sql/... ./internal/engine/...
  passes; gofmt -l and go vet clean.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: Nguyễn Phúc Lương

internal/compiler/find_params.go

@@ -146,6 +146,18 @@ func (p paramSearch) Visit(node ast.Node) astutils.Visitor {
 		if n.LimitOffset != nil {
 			p.limitOffset = n.LimitOffset
 		}
+		// Capture this SELECT's FROM-clause scope so that ParamRefs encountered
+		// while walking deeper into this subtree (WHERE, GROUP BY, etc.) can be
+		// resolved against the innermost in-scope table. Only narrow when the
+		// FROM clause is unambiguous on its own — a single RangeVar with no
+		// JOINs or subselects mixed in. Otherwise leave the scope alone so the
+		// resolver still iterates every in-scope table and detects genuine
+		// ambiguity (e.g. SELECT id FROM t1, t2 WHERE id = $1). See issue #4251.
+		if n.FromClause != nil && len(n.FromClause.Items) == 1 {
+			if rv, ok := n.FromClause.Items[0].(*ast.RangeVar); ok && rv != nil && rv.Relname != nil {
+				p.rangeVar = rv
+			}
+		}
 
 	case *ast.TypeCast:
 		p.parent = node

internal/compiler/resolve.go

@@ -215,6 +215,8 @@ func (comp *Compiler) resolveCatalogRefs(qc *QueryCatalog, rvs []*ast.RangeVar,
 							}
 						}
 					}
+				} else if scoped := narrowToInnermostScope(tables, typeMap, c.DefaultSchema, ref.rv, key); scoped != nil {
+					search = scoped
 				}
 
 				var found int
@@ -581,6 +583,8 @@ func (comp *Compiler) resolveCatalogRefs(qc *QueryCatalog, rvs []*ast.RangeVar,
 							}
 						}
 					}
+				} else if scoped := narrowToInnermostScope(tables, typeMap, c.DefaultSchema, ref.rv, key); scoped != nil {
+					search = scoped
 				}
 
 				for _, table := range search {
@@ -636,3 +640,48 @@ func (comp *Compiler) resolveCatalogRefs(qc *QueryCatalog, rvs []*ast.RangeVar,
 	}
 	return a, nil
 }
+
+// narrowToInnermostScope returns a single-element search slice when the
+// parameter reference (ref.rv) points to a known table that actually
+// contains the column being resolved. It implements the lexical-scope rule
+// real PostgreSQL applies inside subqueries: an unqualified column reference
+// is bound to the innermost FROM-clause table that defines it. If the
+// innermost scope is unknown (rv nil) or the column is not present there
+// (correlated-subquery referring to an outer column), it returns nil so the
+// caller falls back to the full table list. See issue #4251.
+func narrowToInnermostScope(
+	tables []*ast.TableName,
+	typeMap map[string]map[string]map[string]*catalog.Column,
+	defaultSchema string,
+	rv *ast.RangeVar,
+	column string,
+) []*ast.TableName {
+	if rv == nil || rv.Relname == nil {
+		return nil
+	}
+	innerName := *rv.Relname
+	innerSchema := ""
+	if rv.Schemaname != nil {
+		innerSchema = *rv.Schemaname
+	}
+	lookupSchema := innerSchema
+	if lookupSchema == "" {
+		lookupSchema = defaultSchema
+	}
+	// Only narrow if the column actually exists in the innermost scope.
+	// Falling back to the full search preserves correlated-subquery
+	// behavior (e.g. an inner WHERE referring to an outer column).
+	if _, ok := typeMap[lookupSchema][innerName][column]; !ok {
+		return nil
+	}
+	for _, t := range tables {
+		tSchema := t.Schema
+		if tSchema == "" {
+			tSchema = defaultSchema
+		}
+		if t.Name == innerName && tSchema == lookupSchema {
+			return []*ast.TableName{t}
+		}
+	}
+	return nil
+}

internal/compiler/resolve_test.go

@@ -0,0 +1,71 @@
+package compiler
+
+import (
+	"testing"
+
+	"github.com/sqlc-dev/sqlc/internal/sql/ast"
+	"github.com/sqlc-dev/sqlc/internal/sql/catalog"
+)
+
+// TestNarrowToInnermostScope covers the lexical-scope rule used by the
+// resolver to disambiguate column references that live inside subqueries.
+// See issue #4251.
+func TestNarrowToInnermostScope(t *testing.T) {
+	t.Parallel()
+
+	str := func(s string) *string { return &s }
+	tables := []*ast.TableName{
+		{Name: "t1"},
+		{Name: "t2"},
+	}
+	typeMap := map[string]map[string]map[string]*catalog.Column{
+		"public": {
+			"t1": {"id": {Name: "id"}},
+			"t2": {"id": {Name: "id"}, "t1_id": {Name: "t1_id"}},
+		},
+	}
+
+	t.Run("nil_rv_returns_nil", func(t *testing.T) {
+		got := narrowToInnermostScope(tables, typeMap, "public", nil, "id")
+		if got != nil {
+			t.Fatalf("expected nil (no narrowing) got %v", got)
+		}
+	})
+
+	t.Run("nil_relname_returns_nil", func(t *testing.T) {
+		got := narrowToInnermostScope(tables, typeMap, "public", &ast.RangeVar{}, "id")
+		if got != nil {
+			t.Fatalf("expected nil (no narrowing) got %v", got)
+		}
+	})
+
+	t.Run("column_in_inner_scope_narrows_to_inner_table", func(t *testing.T) {
+		// The repro shape: ParamRef in inner SELECT (rv=t2) resolving column "id".
+		// id exists in t2 -> narrow search to [t2] so the outer t1.id doesn't
+		// trigger a spurious "ambiguous" error.
+		rv := &ast.RangeVar{Relname: str("t2")}
+		got := narrowToInnermostScope(tables, typeMap, "public", rv, "id")
+		if len(got) != 1 || got[0].Name != "t2" {
+			t.Fatalf("expected narrow to [t2], got %v", got)
+		}
+	})
+
+	t.Run("column_absent_from_inner_falls_back_to_full_scope", func(t *testing.T) {
+		// Correlated-subquery shape: inner SELECT (rv=t2) references an outer
+		// column not present in t2. Returning nil tells the caller to keep the
+		// full tables list, which lets the outer-scope match win.
+		rv := &ast.RangeVar{Relname: str("t2")}
+		got := narrowToInnermostScope(tables, typeMap, "public", rv, "not_a_t2_column")
+		if got != nil {
+			t.Fatalf("expected nil (fall back to all tables), got %v", got)
+		}
+	})
+
+	t.Run("rv_points_to_unknown_table_falls_back", func(t *testing.T) {
+		rv := &ast.RangeVar{Relname: str("nonexistent")}
+		got := narrowToInnermostScope(tables, typeMap, "public", rv, "id")
+		if got != nil {
+			t.Fatalf("expected nil (fall back), got %v", got)
+		}
+	})
+}

internal/endtoend/testdata/subquery_scope_4251/postgresql/pgx/v5/go/db.go

@@ -0,0 +1,10 @@
+-- name: GetT1FromT2 :many
+-- Unqualified `id` inside the subquery must bind to t2.id (innermost
+-- FROM-clause scope), not be flagged as ambiguous against t1.id. See
+-- issue #4251.
+SELECT id FROM t1
+WHERE id IN (
+    SELECT t1_id
+    FROM t2
+    WHERE id = $1
+);

internal/endtoend/testdata/subquery_scope_4251/postgresql/pgx/v5/go/models.go

@@ -0,0 +1,8 @@
+CREATE TABLE t1 (
+    id UUID PRIMARY KEY
+);
+
+CREATE TABLE t2 (
+    id    UUID,
+    t1_id UUID REFERENCES t1(id) ON DELETE CASCADE
+);

internal/endtoend/testdata/subquery_scope_4251/postgresql/pgx/v5/go/query.sql.go

@@ -0,0 +1,13 @@
+{
+  "version": "1",
+  "packages": [
+    {
+      "path": "go",
+      "engine": "postgresql",
+      "sql_package": "pgx/v5",
+      "name": "querytest",
+      "schema": "schema.sql",
+      "queries": "query.sql"
+    }
+  ]
+}