fix(catalog): synthesize Postgres system columns (xmin, ctid, ...) (#3742)

Problem
-------
sqlc errored with "column does not exist" when a PostgreSQL query
referenced any of the six system columns (tableoid, xmin, cmin, xmax,
cmax, ctid) unless `database.managed: true` was configured. The 2023 fix
(#2871 / #1745) only added the columns inside the PostgreSQL analyzer,
which is initialized only when a live database is attached. Code-only
pipelines that build the catalog purely from schema files still hit the
same "column \"xmin\" does not exist" failure 17 months later (#3742).

Fix
---
Synthesize the six PostgreSQL system columns inside
`compiler.QueryCatalog.GetTable` whenever the engine is `postgresql`.
The catalog itself is left untouched (so MySQL/SQLite tables are not
polluted), and the synthesized columns are marked with a new
`Column.IsSystem` flag so `SELECT *` / `RETURNING *` expansion skips
them — matching PostgreSQL's own behavior. Explicit references like
`SELECT xmin, ctid FROM foo` and aliased forms like `a.xmin` resolve to
the correct types (oid/xid/cid -> pgtype.Uint32, tid -> pgtype.TID).

Changed files
-------------
- internal/compiler/query.go: add `Column.IsSystem`.
- internal/compiler/query_catalog.go: track engine on QueryCatalog;
  append `pgSystemColumns` in GetTable when engine == postgresql.
- internal/compiler/expand.go: skip IsSystem columns in `*` expansion.
- internal/compiler/output_columns.go: skip IsSystem columns in the
  output-columns `*` branch (mirror of expand.go).
- internal/endtoend/testdata/system_columns_3742/postgresql/pgx/v5/:
  new fixture exercising all six system columns, a table alias, and
  SELECT * (which must omit system columns). Golden files committed.

Tests
-----
- `go test ./internal/compiler/... ./internal/sql/... ./internal/engine/... ./internal/codegen/...` — all pass.
- `go test -run TestExamples ./internal/endtoend/` — passes.
- `go vet` + `gofmt -l` clean on touched files.

Local verification
------------------
Built `/tmp/sqlc-dev-3742` from this branch and ran it against the exact
schema + query in the issue. Before fix: `EXIT=1, column "xmin" does
not exist`. After fix: `EXIT=0`, generates `pgtype.Uint32` for xmin,
`pgtype.TID` for ctid. Confirmed `SELECT *` still expands to only the
user columns (id, name, bio) — system columns are not included.

What does NOT change
--------------------
- MySQL / SQLite catalogs are untouched.
- The managed-database analyzer path (#2871) is untouched and still
  works for users on `database.managed: true`.
- `SELECT *` continues to omit system columns (PG-compatible).
- The existing `select_system` endtoend fixture (managed-db) is left
  alone; the new fixture covers the non-managed code path.

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

Author: luongs3

internal/compiler/expand.go

@@ -138,6 +138,12 @@ func (c *Compiler) expandStmt(qc *QueryCatalog, raw *ast.RawStmt, node ast.Node)
 			tableName := c.quoteIdent(t.Rel.Name)
 			scopeName := c.quoteIdent(scope)
 			for _, column := range t.Columns {
+				// Skip PostgreSQL system columns (xmin, ctid, ...) when expanding *.
+				// This matches PostgreSQL's own behavior — they must be referenced
+				// explicitly. See issue #3742.
+				if column.IsSystem {
+					continue
+				}
 				cname := column.Name
 				if res.Name != nil {
 					cname = *res.Name

internal/compiler/output_columns.go

@@ -273,6 +273,11 @@ func (c *Compiler) outputColumns(qc *QueryCatalog, node ast.Node) ([]*Column, er
 						continue
 					}
 					for _, c := range t.Columns {
+						// Skip PostgreSQL system columns on SELECT * to match PG behavior.
+						// See issue #3742.
+						if c.IsSystem {
+							continue
+						}
 						cname := c.Name
 						if res.Name != nil {
 							cname = *res.Name

internal/compiler/query.go

@@ -39,6 +39,12 @@ type Column struct {
 
 	IsSqlcSlice bool // is this sqlc.slice()
 
+	// IsSystem indicates this is a PostgreSQL system column synthesized by
+	// QueryCatalog.GetTable (tableoid, xmin, cmin, xmax, cmax, ctid). System
+	// columns are excluded from SELECT * / RETURNING * expansion to match
+	// PostgreSQL's own behavior.
+	IsSystem bool
+
 	skipTableRequiredCheck bool
 }
 

internal/compiler/query_catalog.go

@@ -3,6 +3,7 @@ package compiler
 import (
 	"fmt"
 
+	"github.com/sqlc-dev/sqlc/internal/config"
 	"github.com/sqlc-dev/sqlc/internal/sql/ast"
 	"github.com/sqlc-dev/sqlc/internal/sql/catalog"
 	"github.com/sqlc-dev/sqlc/internal/sql/rewrite"
@@ -12,6 +13,7 @@ type QueryCatalog struct {
 	catalog *catalog.Catalog
 	ctes    map[string]*Table
 	embeds  rewrite.EmbedSet
+	engine  config.Engine
 }
 
 func (comp *Compiler) buildQueryCatalog(c *catalog.Catalog, node ast.Node, embeds rewrite.EmbedSet) (*QueryCatalog, error) {
@@ -28,7 +30,7 @@ func (comp *Compiler) buildQueryCatalog(c *catalog.Catalog, node ast.Node, embed
 	default:
 		with = nil
 	}
-	qc := &QueryCatalog{catalog: c, ctes: map[string]*Table{}, embeds: embeds}
+	qc := &QueryCatalog{catalog: c, ctes: map[string]*Table{}, embeds: embeds, engine: comp.conf.Engine}
 	if with != nil {
 		for _, item := range with.Ctes.Items {
 			if cte, ok := item.(*ast.CommonTableExpr); ok {
@@ -90,9 +92,43 @@ func (qc QueryCatalog) GetTable(rel *ast.TableName) (*Table, error) {
 	for _, c := range src.Columns {
 		cols = append(cols, ConvertColumn(rel, c))
 	}
+	// PostgreSQL exposes six system columns on every user table
+	// (tableoid, xmin, cmin, xmax, cmax, ctid). They are not part of the
+	// CREATE TABLE definition, so the catalog has no record of them — but
+	// queries are allowed to reference them by name. Synthesize them here
+	// so the compiler can resolve refs like `SELECT xmin, ctid FROM foo`.
+	// They are marked IsSystem so SELECT * / RETURNING * skip them, which
+	// matches PostgreSQL's own behavior. See issues #1745, #3742.
+	if qc.engine == config.EnginePostgreSQL {
+		cols = append(cols, pgSystemColumns(rel)...)
+	}
 	return &Table{Rel: rel, Columns: cols}, nil
 }
 
+// pgSystemColumns returns the six PostgreSQL system columns synthesized for
+// every user table. See https://www.postgresql.org/docs/current/ddl-system-columns.html
+func pgSystemColumns(rel *ast.TableName) []*Column {
+	mk := func(name, typ string) *Column {
+		t := &ast.TypeName{Name: typ}
+		return &Column{
+			Name:     name,
+			DataType: typ,
+			NotNull:  true,
+			Table:    rel,
+			Type:     t,
+			IsSystem: true,
+		}
+	}
+	return []*Column{
+		mk("tableoid", "oid"),
+		mk("xmin", "xid"),
+		mk("cmin", "cid"),
+		mk("xmax", "xid"),
+		mk("cmax", "cid"),
+		mk("ctid", "tid"),
+	}
+}
+
 func (qc QueryCatalog) GetFunc(rel *ast.FuncName) (*Function, error) {
 	funcs, err := qc.catalog.ListFuncsByName(rel)
 	if err != nil {

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

@@ -0,0 +1,8 @@
+-- name: GetSystemColumns :one
+SELECT xmin, cmin, xmax, cmax, ctid, tableoid FROM authors LIMIT 1;
+
+-- name: GetSystemColumnsAliased :one
+SELECT a.xmin, a.ctid FROM authors a LIMIT 1;
+
+-- name: SelectStar :many
+SELECT * FROM authors;

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

@@ -0,0 +1,5 @@
+CREATE TABLE authors (
+  id   BIGSERIAL PRIMARY KEY,
+  name text      NOT NULL,
+  bio  text
+);

internal/endtoend/testdata/system_columns_3742/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"
+    }
+  ]
+}