Aether-Sync (Native Protocol)

SecurityNative ProtocolBinaryLow Overhead

Stable On by default · production-ready

What it is

Aether-Sync is AetheriusDB’s native wire protocol — the one the official aetherius Python client speaks, on port 5679. Instead of converting every result into text and re-parsing it on the client, it returns typed binary results: an Int64 comes back as a Python int, not a string, with the lowest per-query overhead of the three protocols.

It supports the full set of client operations: typed binary results, transactions, prepared statements with parameter binding, streaming, connection pooling, and high-throughput bulk ingest.

Why it matters

• Typed results, no per-row text parse — values arrive already typed, so there is no JSON or text-to-value conversion step on the client.
• Lowest per-query overhead — the leanest path for application services that talk to the database directly.
• Full client feature set — transactions, prepared statements, streaming, pooling, and bulk ingest are all available over this protocol.

How you use it

pip install aetherius
# Or with Flight SQL + LZ4 support:
pip install 'aetherius[flight,lz4]'

import aetherius

with aetherius.connect("127.0.0.1", 5679) as conn:
    conn.execute("CREATE TABLE t (id BIGINT, name TEXT)")
    conn.execute("INSERT INTO t VALUES (1, 'alpha'), (2, 'beta')")

    # Typed binary results — Int64 comes back as a Python int, not str.
    result = conn.execute_binary("SELECT * FROM t ORDER BY id")
    for row in result.rows:
        print(row)            # (1, 'alpha') / (2, 'beta')

    # Transactions — rollback on exception, commit on clean exit.
    with conn.transaction():
        conn.execute("INSERT INTO t VALUES (3, 'gamma')")

    # Prepared statements with parameter binding.
    stmt = conn.prepare("SELECT * FROM t WHERE id = ?")
    print(stmt.execute([2]).rows)

With an auth token and a connection pool:

with aetherius.connect("db.example.com", 5679,
                       auth_token="my-bearer-token") as conn:
    ...

pool = aetherius.connect_pool("127.0.0.1", 5679, size=8)
with pool.acquire() as conn:
    conn.execute("SELECT 1")

Key concepts

Term	Meaning
Typed binary result	A result where each column arrives already typed, so the client does not parse text into values.
Prepared statement	A statement parsed once and re-executed with bound parameters.
Connection pool	A reusable set of connections (connect_pool) to avoid per-request connection setup.
Bulk ingest	A high-throughput path for loading large data sets through the native protocol.

Notes & caveats

Tip

For dataframe-first analytics, pair the native protocol for transactional work with Arrow Flight SQL for large columnar reads — both talk to the same engine and the same data.

Pick the right protocol for the client

The native protocol is the lowest-overhead option, but it requires the aetherius client. For Postgres tooling use the pgwire endpoint, and for dataframe pipelines use Flight SQL — see Wire Protocols.

Wire Protocols →

How the native protocol sits next to pgwire and Flight SQL.

Connect a Client →

Full connection recipes for every supported client.

Remote Connectivity Security →

TLS and auth tokens that secure native sessions.