docs: canonical PostgreSQL compatibility matrix (#762)

* docs: add canonical PostgreSQL compatibility matrix

Add docs/postgres-compatibility.md: a single, feature-by-feature record of
which PostgreSQL functionality Duckgres supports and which tests prove it,
with specific test citations (file.go::TestName) per row.

Consolidates coverage info previously smeared across README.md,
tests/integration/README.md, and TODO.md. Each row carries a status
(Covered / Partial / Implemented-untested / Unsupported / Out-of-scope) and
links to the differential, unit, or client-compat test that exercises it.

Surfaces the real gaps, notably: cursors (DECLARE/FETCH/MOVE) are implemented
in server/conn_cursor.go but have no happy-path test, and the differential
RETURNING / COPY TO STDOUT skips are stale.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* docs: consolidate README compatibility tables into the canonical matrix

Shrink README's "SQL Client Compatibility" section to a short summary plus a
link to docs/postgres-compatibility.md, and relocate the detailed
pg_catalog / information_schema / functions / startup-parameter reference
tables into that doc as Appendix A so there is one source of truth.

Fix verified-stale entries during the move:
- current_schema(), pg_settings, pg_proc were labelled "Missing" though they
  work via DuckDB's native pg_catalog (no Duckgres wrapper) -> "Native (DuckDB)"
- pg_roles is a minimal one-row view, not an empty stub
- clarify pg_stat_activity (static view empty; live data injected at query time)

The advertised server_version (15.0) is left as-is: it matches the code
(server/catalog.go, server/conn.go) and is an intentional emulation choice.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

Author: bill-ph

README.md

@@ -761,101 +761,9 @@ Since DuckDB's isolation is strictly stronger than PostgreSQL's default, applica
 
 ## SQL Client Compatibility
 
-Duckgres implements a subset of PostgreSQL's system catalog to satisfy introspection queries from common SQL clients, ORMs, and BI tools. The tables below document current coverage.
-
-### pg_catalog Views
-
-| View | Status | Notes |
-|------|--------|-------|
-| `pg_class` | Implemented | `pg_class_full` wrapper adding `relforcerowsecurity`; DuckLake variant sources from `duckdb_tables()`/`duckdb_views()` |
-| `pg_namespace` | Implemented | Maps `main` → `public`; DuckLake variant derives from `duckdb_tables()`/`duckdb_views()` |
-| `pg_attribute` | Implemented | Maps DuckDB internal type OIDs to PG OIDs via `duckdb_columns()` JOIN; fixes `atttypmod` for NUMERIC |
-| `pg_type` | Implemented | Fixes NULLs + adds synthetic entries for missing OIDs (json, jsonb, bpchar, text, record, array types) |
-| `pg_database` | Implemented | Hardcoded: postgres, template0, template1, testdb |
-| `pg_stat_user_tables` | Implemented | Uses `reltuples` from pg_class; zeros for scan/tuple stats |
-| `pg_roles` | Stub (empty) | Single hardcoded `duckdb` superuser |
-| `pg_constraint` | Stub (empty) | |
-| `pg_enum` | Stub (empty) | |
-| `pg_collation` | Stub (empty) | |
-| `pg_policy` | Stub (empty) | |
-| `pg_inherits` | Stub (empty) | |
-| `pg_statistic_ext` | Stub (empty) | |
-| `pg_publication` | Stub (empty) | |
-| `pg_publication_rel` | Stub (empty) | |
-| `pg_publication_tables` | Stub (empty) | |
-| `pg_rules` | Stub (empty) | |
-| `pg_matviews` | Stub (empty) | |
-| `pg_partitioned_table` | Stub (empty) | |
-| `pg_stat_activity` | Stub (empty) | Intercepted at query time for live data |
-| `pg_statio_user_tables` | Stub (empty) | |
-| `pg_stat_statements` | Stub (empty) | |
-| `pg_indexes` | Stub (empty) | |
-| `pg_settings` | Missing | `current_setting()` macro handles `server_version` and `server_encoding` only |
-| `pg_proc` | Missing | DuckDB has native `pg_catalog.pg_proc` but no wrapper |
-| `pg_description` | Missing | Handled via `obj_description()`/`col_description()` macros returning NULL |
-| `pg_depend` | Missing | |
-| `pg_am` | Missing | |
-| `pg_attrdef` | Missing | |
-| `pg_tablespace` | Missing | |
-
-### information_schema Views
-
-| View | Status | Notes |
-|------|--------|-------|
-| `tables` | Implemented | Filters internal views, normalizes `main` → `public` |
-| `columns` | Implemented | DuckDB → PG type name normalization, optional metadata overlay |
-| `schemata` | Implemented | Adds synthetic entries for `pg_catalog`, `information_schema`, `pg_toast` |
-| `views` | Implemented | Filters internal views |
-| `key_column_usage` | Missing | Used by ORMs for relationship discovery |
-| `table_constraints` | Missing | Used by ORMs for relationship discovery |
-| `referential_constraints` | Missing | Used by ORMs for FK introspection |
-
-### Functions & Macros
-
-| Function | Status | Notes |
-|----------|--------|-------|
-| `format_type(oid, int)` | Implemented | Comprehensive OID → name mapping |
-| `pg_get_expr(text, oid)` | Implemented | Returns NULL |
-| `pg_get_indexdef(oid)` | Implemented | Returns empty string |
-| `pg_get_constraintdef(oid)` | Implemented | Returns empty string |
-| `pg_get_serial_sequence(text, text)` | Implemented | Returns NULL |
-| `pg_table_is_visible(oid)` | Implemented | Always true |
-| `pg_get_userbyid(oid)` | Implemented | Maps OID 10 → `postgres`, 6171 → `pg_database_owner` |
-| `obj_description(oid, text)` | Implemented | Returns NULL |
-| `col_description(oid, int)` | Implemented | Returns NULL |
-| `shobj_description(oid, text)` | Implemented | Returns NULL |
-| `has_table_privilege(text, text)` | Implemented | Always true |
-| `has_schema_privilege(text, text)` | Implemented | Always true |
-| `pg_encoding_to_char(int)` | Implemented | Always `UTF8` |
-| `version()` | Implemented | Returns PG 15.0 compatible string |
-| `current_setting(text)` | Implemented | Handles `server_version` and `server_encoding` |
-| `pg_is_in_recovery()` | Implemented | Always false |
-| `pg_backend_pid()` | Implemented | Returns 0 |
-| `pg_size_pretty(bigint)` | Implemented | Full human-readable formatting |
-| `pg_total_relation_size(oid)` | Implemented | Returns 0 |
-| `pg_relation_size(oid)` | Implemented | Returns 0 |
-| `pg_table_size(oid)` | Implemented | Returns 0 |
-| `pg_indexes_size(oid)` | Implemented | Returns 0 |
-| `pg_database_size(text)` | Implemented | Returns 0 |
-| `quote_ident(text)` | Implemented | |
-| `quote_literal(text)` | Implemented | |
-| `quote_nullable(text)` | Implemented | |
-| `txid_current()` | Implemented | Epoch-based pseudo ID |
-| `current_schema()` | Missing | |
-| `current_schemas(bool)` | Missing | |
-
-### Startup Parameters
-
-| Parameter | Value |
-|-----------|-------|
-| `server_version` | `15.0 (Duckgres)` |
-| `server_encoding` | `UTF8` |
-| `client_encoding` | `UTF8` |
-| `DateStyle` | `ISO, MDY` |
-| `TimeZone` | `UTC` |
-| `integer_datetimes` | `on` |
-| `standard_conforming_strings` | `on` |
-| `IntervalStyle` | Missing |
+Duckgres implements a subset of PostgreSQL's system catalog to satisfy introspection queries from common SQL clients, ORMs, and BI tools — enough for psql, pgAdmin, DBeaver, Metabase, Grafana, Superset, Tableau, Fivetran, Airbyte, dbt, and the standard drivers (psycopg, pgx, JDBC, node-postgres, tokio-postgres, SQLAlchemy) to connect and introspect.
+
+The full, authoritative breakdown — every PostgreSQL feature with its support status and the specific test that proves it, plus the per-object `pg_catalog`/`information_schema`/function/startup-parameter reference — lives in **[docs/postgres-compatibility.md](docs/postgres-compatibility.md)**. That document is the single source of truth; update it in the same PR as any PostgreSQL-visible behavior change.
 
 ## Dependencies