Postgres frontend/backend protocol for Flyology

Postgres, in native Ada.

Flyology Postgres provides typed, bounded client and server primitives over Flyology I/O.

Connect a client Browse the API
client.adb 
Client.Send_Query
  (Session,
   "select id, value from items",
   Timeout => 5.0);
Protocol 3.2Typed frontend and backend messages.
Postgres 18.4Interoperability tested in both directions.
Bounded streamsRows and COPY frames are never accumulated.

Two protocol directions

Build clients and protocol servers from the same wire model.

The protocol layer owns framing and typed messages. Client sessions and server sessions add explicit state, streaming, authentication, and cancellation behavior.

01 / CLIENT

Connect to Postgres

Ada task session Postgres
02 / SERVER

Speak to Postgres tools

psql session Ada handler

Protocol architecture

Every transition stays inspectable.

Startup, queries, COPY, recovery, and cancellation each have an explicit contract. Applications retain control without reimplementing frame validation.

Read the implementation guide
  1. 01

    Startup and authentication

    Trust, cleartext password, and SCRAM-SHA-256 are handled through the Postgres startup exchange.

  2. 02

    Typed wire messages

    Known protocol messages receive owned typed views. Unknown future tags retain their original bytes.

  3. 03

    Bounded streaming

    Simple queries, extended queries, and COPY return one event or frame per call, with no hidden result accumulator.

  4. 04

    Separate cancellation

    Backend cancellation credentials travel on the separate connection required by the Postgres protocol.

Current coverage

The high-value protocol paths, without an async language.

Calls remain ordinary synchronous Ada operations. On a lightweight task, Flyology suspends the task while its loop thread remains available.

  • Simple queriesTyped row descriptions, rows, completion, diagnostics, and readiness.
  • Extended queriesPrepared statements, portals, flush, sync, suspension, and recovery.
  • COPYBounded COPY IN, COPY OUT, and COPY BOTH streams.
  • AuthenticationTrust, cleartext password, and SCRAM-SHA-256.
  • TLSVerified client and server upgrades with encrypted cancellation.
  • Protocol serversApplication handlers with typed response helpers and cancellation tokens.

Boundaries

Concrete coverage, with limits attached.

TLS clients verify server certificate chains and DNS names, and servers can require encrypted startup. Client-certificate authentication and SCRAM channel binding remain explicit boundaries.

Review all current boundaries
ConcernContract
TLSStartup_TLS and Serve_TLS use PostgreSQL SSLRequest negotiation without plaintext fallback; encrypted cancellation is available separately. sslnegotiation=direct is not yet supported.
AuthenticationNo MD5, GSSAPI, SSPI, certificate auth, or SCRAM-SHA-256-PLUS.
MemoryRows and COPY frames are returned individually; callers own their buffering policy.
SchedulingContinuously readable COPY streams may need explicit Flyology fairness points.
The Flyology flight mark

Working examples

Exercise both ends of the wire.

psqlish is a compact Postgres client with verified TLS. pgish is a read-only Postgres-like server with configurable required TLS, virtual Flyology, and catalog tables. Use them together, or connect either side to real Postgres tooling.

Explore the examples

Open your first Postgres session.

Open the guide Search the protocol API