PostgreSQL Compatibility

AionDB speaks PostgreSQL wire protocol so existing tools can connect, but compatibility is implemented feature by feature. Treat v0.1 as PostgreSQL-facing, not PostgreSQL-complete.

What should work first

The priority surface is:

startup and simple query flow over pgwire;
common SQL DDL and DML paths;
transactions on implemented statements;
prepared statement paths used by common drivers;
basic type mapping for supported types;
command tags and result shapes that clients expect.

This priority list is intentionally practical. If a normal driver cannot connect, run a prepared query, report errors, and recover transaction state, broader SQL compatibility does not matter yet.

Quick compatibility smoke test

Run this with the client you care about:

SELECT 1;
CREATE TABLE compat_smoke (id INT PRIMARY KEY, body TEXT);
INSERT INTO compat_smoke VALUES (1, 'ok');
SELECT body FROM compat_smoke WHERE id = 1;
BEGIN;
INSERT INTO compat_smoke VALUES (2, 'rollback');
ROLLBACK;
SELECT COUNT(*) FROM compat_smoke;

Then repeat with a parameterized query through the driver. This catches more real compatibility issues than a manual SELECT 1 alone.

What needs explicit testing

Test your actual client stack before relying on compatibility:

extended protocol behavior;
named prepared statements and portals;
COPY behavior;
array, JSON, timestamp, numeric, and vector type mapping;
transaction error handling;
ORM-generated SQL;
driver-specific startup parameters.

Compatibility levels

Think about compatibility in layers:

Layer	What to test
Protocol	startup, simple query, parse, bind, execute, sync, error response
SQL syntax	DDL, DML, expressions, joins, transactions
Types	text and binary formats, casts, nulls, arrays, timestamps, vectors
Catalog	introspection queries used by tools and ORMs
Behavior	transaction state, error classes, command tags, row descriptions

AionDB can pass one layer while still failing another. A good report names the layer.

Driver behavior matrix

Track drivers in a table during evaluation:

Driver	Connect	Simple query	Prepared query	Transactions	Notes
`psql`	tested	tested	not enough	tested	baseline console
Application driver	not tested	not tested	not tested	not tested	fill during evaluation

Do not claim support for a driver until the application query path has been tested, not just connection startup.

Unsupported PostgreSQL features

PostgreSQL has a very large surface area. AionDB v0.1 does not claim full support for PostgreSQL extensions, every system catalog detail, every planner behavior, every procedural language feature, or every wire-protocol corner case.

Unsupported behavior should fail explicitly. Silent mismatch is a bug.

Catalog compatibility is documented in System Catalogs. SQLSTATE behavior is summarized in Error Reference.

Practical guidance

For a new driver or ORM:

Start with a connection smoke test.
Run simple DDL, INSERT, SELECT, UPDATE, DELETE, and transaction tests.
Add prepared statements.
Add the exact SQL generated by the framework.
Reduce every mismatch to a small SQL file and keep it in the compatibility suite.

Reporting mismatches

A useful compatibility report includes:

client library and version;
connection string without secrets;
server command;
whether the query used simple or extended protocol;
SQL text;
expected PostgreSQL behavior if known;
AionDB output or error.

If PostgreSQL and AionDB disagree, include the PostgreSQL result. That turns a vague compatibility problem into a concrete target.

Compatibility language

Use precise wording:

"speaks PostgreSQL wire protocol" when describing the connection surface;
"supports this PostgreSQL-compatible query" when a query is tested;
"not PostgreSQL-complete" when setting expectations;
"driver tested with these operations" when claiming driver compatibility.

Avoid broad claims unless there is a compatibility matrix behind them.