@@ -18,10 +18,14 @@ PostgreSQL Client → TLS → Duckgres Server → DuckDB (per-user database)
1818- ** server/server.go** : Server struct, connection handling, graceful shutdown
1919- ** server/conn.go** : Client connection handling, query execution, COPY protocol
2020- ** server/protocol.go** : PostgreSQL wire protocol message encoding/decoding
21- - ** server/catalog.go** : pg_catalog compatibility ( views, functions, query rewriting)
21+ - ** server/catalog.go** : pg_catalog compatibility views and macros initialization
2222- ** server/types.go** : Type OID mapping between DuckDB and PostgreSQL
2323- ** server/ratelimit.go** : Rate limiting for brute-force protection
2424- ** server/tls.go** : Auto-generation of self-signed TLS certificates
25+ - ** transpiler/** : AST-based SQL transpiler (PostgreSQL → DuckDB)
26+ - ` transpiler.go ` : Main API, transform pipeline orchestration
27+ - ` config.go ` : Configuration types (DuckLakeMode, ConvertPlaceholders)
28+ - ` transform/ ` : Individual transform implementations
2529
2630## PostgreSQL Wire Protocol
2731
@@ -41,22 +45,27 @@ The server implements the PostgreSQL v3 protocol:
4145### Extended Query Protocol
4246Supports prepared statements (Parse/Bind/Execute) for parameterized queries and binary result formats.
4347
44- ## pg_catalog Compatibility (server/catalog.go)
48+ ## pg_catalog Compatibility
4549
4650psql and other clients expect PostgreSQL system catalogs. We provide compatibility by:
4751
48- 1 . ** Creating views** in main schema that mirror pg_catalog tables :
52+ 1 . ** Creating views** in main schema (server/catalog.go ` initPgCatalog() ` ) :
4953 - ` pg_database ` , ` pg_class_full ` , ` pg_collation ` , ` pg_policy ` , ` pg_roles `
5054 - ` pg_statistic_ext ` , ` pg_publication ` , ` pg_publication_rel ` , ` pg_inherits ` , etc.
5155
52- 2 . ** Creating macros** for PostgreSQL functions:
56+ 2 . ** Creating macros** for PostgreSQL functions (server/catalog.go) :
5357 - ` pg_get_userbyid ` , ` pg_table_is_visible ` , ` format_type ` , ` pg_get_expr `
5458 - ` obj_description ` , ` col_description ` , ` pg_get_indexdef ` , etc.
5559
56- 3 . ** Query rewriting** to replace PostgreSQL-specific syntax:
57- - ` pg_catalog.pg_class ` → ` pg_class_full `
58- - ` OPERATOR(pg_catalog.~) ` → ` ~ `
59- - ` ::pg_catalog.regtype ` → ` ::VARCHAR `
60+ 3 . ** AST-based SQL transpilation** (transpiler/ package):
61+ The transpiler parses PostgreSQL SQL into an AST using pg_query_go (PostgreSQL's C parser),
62+ applies transforms, and deparses back to DuckDB-compatible SQL. Transforms include:
63+ - ** PgCatalogTransform** : ` pg_catalog.pg_class ` → ` pg_class_full ` , strips schema prefix from functions
64+ - ** TypeCastTransform** : ` ::pg_catalog.regtype ` → ` ::VARCHAR `
65+ - ** VersionTransform** : ` version() ` → PostgreSQL-compatible version string
66+ - ** SetShowTransform** : Converts SET/SHOW commands, marks ignored parameters
67+ - ** DDLTransform** : (DuckLake mode) Strips PRIMARY KEY, UNIQUE, REFERENCES, SERIAL types
68+ - ** PlaceholderTransform** : Counts $1, $2 parameters for prepared statements
6069
6170## COPY Protocol (server/conn.go)
6271
@@ -95,12 +104,17 @@ PGPASSWORD=postgres psql "host=127.0.0.1 port=35437 user=postgres sslmode=requir
95104
96105### Adding a new pg_catalog view
971061 . Add view creation SQL in ` initPgCatalog() ` in ` catalog.go `
98- 2 . Add regex pattern to rewrite ` pg_catalog.viewname ` to ` viewname `
99- 3 . Add the replacement in ` rewritePgCatalogQuery() `
107+ 2 . If the view needs query rewriting (e.g., ` pg_catalog.viewname ` → ` viewname ` ):
108+ - Add mapping in ` transpiler/transform/pgcatalog.go ` in ` pgCatalogViewMappings `
100109
101110### Adding a new PostgreSQL function
1021111 . Add ` CREATE MACRO ` in the ` functions ` slice in ` initPgCatalog() `
103- 2 . Add function name to ` pgCatalogFunctions ` slice for query rewriting
112+ 2 . The transpiler automatically strips ` pg_catalog. ` prefix from function calls
113+
114+ ### Adding a new transform
115+ 1 . Create a new file in ` transpiler/transform/ ` implementing the ` Transform ` interface
116+ 2 . Register the transform in ` transpiler/transpiler.go ` ` New() ` function
117+ 3 . Add tests in ` transpiler/transpiler_test.go `
104118
105119### Adding protocol support
1061201 . 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
110124## Dependencies
111125
112126- ` github.com/duckdb/duckdb-go/v2 ` - DuckDB Go driver
127+ - ` github.com/pganalyze/pg_query_go/v6 ` - PostgreSQL SQL parser (CGO, uses libpg_query)
113128- ` gopkg.in/yaml.v3 ` - YAML config parsing
114129
115130## Known Limitations
0 commit comments