Merge remote-tracking branch 'origin/main' into ci/add-test-workflow

Author: EDsCODE

CLAUDE.md

@@ -18,10 +18,14 @@ PostgreSQL Client → TLS → Duckgres Server → DuckDB (per-user database)
 - **server/server.go**: Server struct, connection handling, graceful shutdown
 - **server/conn.go**: Client connection handling, query execution, COPY protocol
 - **server/protocol.go**: PostgreSQL wire protocol message encoding/decoding
-- **server/catalog.go**: pg_catalog compatibility (views, functions, query rewriting)
+- **server/catalog.go**: pg_catalog compatibility views and macros initialization
 - **server/types.go**: Type OID mapping between DuckDB and PostgreSQL
 - **server/ratelimit.go**: Rate limiting for brute-force protection
 - **server/tls.go**: Auto-generation of self-signed TLS certificates
+- **transpiler/**: AST-based SQL transpiler (PostgreSQL → DuckDB)
+  - `transpiler.go`: Main API, transform pipeline orchestration
+  - `config.go`: Configuration types (DuckLakeMode, ConvertPlaceholders)
+  - `transform/`: Individual transform implementations
 
 ## PostgreSQL Wire Protocol
 
@@ -41,22 +45,27 @@ The server implements the PostgreSQL v3 protocol:
 ### Extended Query Protocol
 Supports prepared statements (Parse/Bind/Execute) for parameterized queries and binary result formats.
 
-## pg_catalog Compatibility (server/catalog.go)
+## pg_catalog Compatibility
 
 psql and other clients expect PostgreSQL system catalogs. We provide compatibility by:
 
-1. **Creating views** in main schema that mirror pg_catalog tables:
+1. **Creating views** in main schema (server/catalog.go `initPgCatalog()`):
    - `pg_database`, `pg_class_full`, `pg_collation`, `pg_policy`, `pg_roles`
    - `pg_statistic_ext`, `pg_publication`, `pg_publication_rel`, `pg_inherits`, etc.
 
-2. **Creating macros** for PostgreSQL functions:
+2. **Creating macros** for PostgreSQL functions (server/catalog.go):
    - `pg_get_userbyid`, `pg_table_is_visible`, `format_type`, `pg_get_expr`
    - `obj_description`, `col_description`, `pg_get_indexdef`, etc.
 
-3. **Query rewriting** to replace PostgreSQL-specific syntax:
-   - `pg_catalog.pg_class` → `pg_class_full`
-   - `OPERATOR(pg_catalog.~)` → `~`
-   - `::pg_catalog.regtype` → `::VARCHAR`
+3. **AST-based SQL transpilation** (transpiler/ package):
+   The transpiler parses PostgreSQL SQL into an AST using pg_query_go (PostgreSQL's C parser),
+   applies transforms, and deparses back to DuckDB-compatible SQL. Transforms include:
+   - **PgCatalogTransform**: `pg_catalog.pg_class` → `pg_class_full`, strips schema prefix from functions
+   - **TypeCastTransform**: `::pg_catalog.regtype` → `::VARCHAR`
+   - **VersionTransform**: `version()` → PostgreSQL-compatible version string
+   - **SetShowTransform**: Converts SET/SHOW commands, marks ignored parameters
+   - **DDLTransform**: (DuckLake mode) Strips PRIMARY KEY, UNIQUE, REFERENCES, SERIAL types
+   - **PlaceholderTransform**: Counts $1, $2 parameters for prepared statements
 
 ## COPY Protocol (server/conn.go)
 
@@ -95,12 +104,17 @@ PGPASSWORD=postgres psql "host=127.0.0.1 port=35437 user=postgres sslmode=requir
 
 ### Adding a new pg_catalog view
 1. Add view creation SQL in `initPgCatalog()` in `catalog.go`
-2. Add regex pattern to rewrite `pg_catalog.viewname` to `viewname`
-3. Add the replacement in `rewritePgCatalogQuery()`
+2. If the view needs query rewriting (e.g., `pg_catalog.viewname` → `viewname`):
+   - Add mapping in `transpiler/transform/pgcatalog.go` in `pgCatalogViewMappings`
 
 ### Adding a new PostgreSQL function
 1. Add `CREATE MACRO` in the `functions` slice in `initPgCatalog()`
-2. Add function name to `pgCatalogFunctions` slice for query rewriting
+2. The transpiler automatically strips `pg_catalog.` prefix from function calls
+
+### Adding a new transform
+1. Create a new file in `transpiler/transform/` implementing the `Transform` interface
+2. Register the transform in `transpiler/transpiler.go` `New()` function
+3. Add tests in `transpiler/transpiler_test.go`
 
 ### Adding protocol support
 1. Add message type constant in `protocol.go`
@@ -110,6 +124,7 @@ PGPASSWORD=postgres psql "host=127.0.0.1 port=35437 user=postgres sslmode=requir
 ## Dependencies
 
 - `github.com/duckdb/duckdb-go/v2` - DuckDB Go driver
+- `github.com/pganalyze/pg_query_go/v6` - PostgreSQL SQL parser (CGO, uses libpg_query)
 - `gopkg.in/yaml.v3` - YAML config parsing
 
 ## Known Limitations