Skip to content

Proxy

The GenDB proxy is a PostgreSQL wire protocol relay that sits between your application and your database. It intercepts GENDB SQL commands and uses temporary views to route queries to real or generated data per table.

What the Proxy Does

  • Byte-level relay — Standard SQL queries are forwarded as raw bytes with no parsing or modification
  • GENDB command interception — Queries starting with CALL gendb. are intercepted, parsed, and executed locally by the proxy
  • Per-table routing via temp views — return_generated creates a temporary view that overlays the real table; return_actual drops it to restore real data access

Starting the Proxy

gendb serve --port 5433

Connecting Through the Proxy

Connect to the proxy using any PostgreSQL client, with the same credentials as your real database:

psql -h localhost -p 5433 -U myuser mydb

From your application, change only the host and port in the connection string to point at the proxy.

Generating Data and Routing

Once connected through the proxy, use GENDB SQL commands:

-- Generate synthetic data
CALL gendb.generate_data(include => 'users', rows => 500);

-- Route queries for "users" to generated data
CALL gendb.return_generated(include => 'users');

-- Switch back to real data
CALL gendb.return_actual(include => 'users');

How Routing Works

The proxy uses PostgreSQL temporary views for per-table routing:

  • return_generated creates a CREATE OR REPLACE TEMP VIEW <table> AS SELECT * FROM <synthetic_schema>.<table>. Because temporary views take priority over base tables in PostgreSQL's name resolution, queries against that table name return generated data.
  • return_actual drops the temporary view with DROP VIEW IF EXISTS pg_temp.<table>, restoring normal resolution to the real table.

This approach means: - Routing is per-session — other connections are unaffected - Per-table control — each table can be independently toggled - No SQL parsing needed — PostgreSQL handles the routing natively

How Standard SQL Passes Through

The proxy does not parse standard SQL. When a query does not start with CALL gendb. (case-insensitive), the raw bytes are forwarded to the database and the response is relayed back. This means:

  • No SQL compatibility issues — any valid PostgreSQL query works
  • No performance overhead from SQL parsing
  • Transactions, prepared statements, and protocol features work as expected