Connect a Client

ClientsPythonJDBCArrow

AetheriusDB exposes three wire protocols at the same time. They all talk to the same engine over the same data — pick the one that fits your ecosystem.

Pick a protocol

Protocol	Port	Best for	Driver
Native (Aether-Sync)	5679	Lowest-overhead Python jobs	pip install aetherius
PostgreSQL pgwire	5678	psql, Tableau, SQLAlchemy — anything that speaks Postgres	psycopg, asyncpg, SQLAlchemy
Apache Arrow Flight SQL	8815	Pyarrow, Polars, Spark, dbt — dataframe-first clients	adbc-driver-flightsql

Prefer a terminal? The official aesql CLI speaks both the native protocol and Flight SQL from one binary — a psql-style REPL plus compressed database export/import (aesql export / aesql import).

Python · native client

The native client has the lowest per-query overhead and supports typed binary results, transactions, prepared statements, streaming, and bulk ingest.

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 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 authentication 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")

PostgreSQL · psycopg / any pgwire client

AetheriusDB speaks the PostgreSQL wire protocol on port 5678 by default, so existing tools work unchanged.

Verify the port first. The daemon’s pgwire port is whatever --port was given at launch (some installs use 5680, e.g. because macOS already binds 5678 to its rrac service). The native Aether-Sync listener is a separate port (--native-port, default 5679) and does not answer the Postgres handshake — pointing a psql/psycopg client at it hangs. Confirm you have the right port with:

psql -h 127.0.0.1 -p <port> -U aether -d aetherius -c "SELECT version();"

It should print an AetheriusDB <version> banner (e.g. AetheriusDB 0.1.17). The database self-identifies as AetheriusDB — SELECT version() no longer impersonates PostgreSQL. (SHOW server_version still returns 15.0 (AetheriusDB <version>): libpq/psycopg/JDBC parse the leading 15.0 token to gate protocol features, so the build is appended as a suffix.)

import psycopg

with psycopg.connect(host="127.0.0.1", port=5678,
                     user="aether", dbname="aetherius", password="") as conn:
    with conn.cursor() as cur:
        cur.execute("SELECT 1")
        print(cur.fetchone())

psql -h 127.0.0.1 -p 5678 -U aether -d aether

asyncpg and SQLAlchemy

Both connect over the same pgwire endpoint. asyncpg drives the extended (binary) protocol; SQLAlchemy uses the standard postgresql+psycopg / postgresql+asyncpg dialects — the engine returns a PostgreSQL 15.0 (AetheriusDB …) version token so ORM dialect-detection works.

import asyncio, asyncpg

async def main():
    conn = await asyncpg.connect(host="127.0.0.1", port=5678,
                                 user="aether", database="aetherius")
    print(await conn.fetch("SELECT id, name FROM t ORDER BY id"))
    await conn.close()

asyncio.run(main())

from sqlalchemy import create_engine, text

engine = create_engine("postgresql+psycopg://aether@127.0.0.1:5678/aetherius")
with engine.connect() as conn:
    print(conn.execute(text("SELECT 1")).all())

Two pgwire limits worth knowing

• SAVEPOINT / RELEASE SAVEPOINT are accepted but are no-ops — they exist so ORM session machinery doesn’t error, but there is no real partial rollback to a savepoint. Top-level BEGIN / COMMIT / ROLLBACK are fully honoured, and once a statement fails inside a transaction the rest are rejected until you ROLLBACK (Postgres aborted-transaction semantics).
• Fine-grained SQLSTATEs are surfaced on the native protocol, not over pgwire. A foreign-key or unique violation reaches a pgwire client as a generic error whose message names the violated constraint (e.g. “violates foreign key constraint …”); the specific codes (23503 / 23505) are delivered on the native client.

Selecting a database

A connection is bound to one database. pgwire clients pass it as the standard dbname (psql -d, database= in a driver, /dbname in a URL); the native client passes it in the connection handshake. Inside a session you can switch, and create or drop databases, with ordinary statements:

SHOW DATABASES;             -- list databases
CREATE DATABASE analytics;  -- disk-first; recovers on restart
USE analytics;              -- switch the session's active database
SELECT current_database();  -- confirm the active database
DROP DATABASE analytics;    -- (cannot drop the default or the active database)

Apache Arrow Flight SQL · pyarrow / ADBC

For dataframe-first workloads, the Flight SQL endpoint returns typed Arrow batches directly — no JSON, no per-row Python overhead.

import aetherius

with aetherius.connect_flight("127.0.0.1", 8815) as conn:
    with conn.cursor() as cur:
        cur.execute("SELECT 1 AS x, 'hi' AS y")
        table = cur.fetch_arrow_table()   # pyarrow.Table
        df = table.to_pandas()
        print(df)

JDBC / JVM clients

Use the standard PostgreSQL JDBC driver against the pgwire endpoint:

jdbc:postgresql://localhost:5678/aetherius?user=aether&password=

Which protocol when?

If you’re…	Use
Writing a small Python service straight to the DB	Native
Migrating a Postgres workload	pgwire
Building a notebook / dataframe pipeline	Flight SQL
Using Tableau, Metabase, Grafana, dbt-postgres	pgwire
Using Polars, Spark, Dremio, anything ADBC-aware	Flight SQL
Doing bulk ingest of large CSVs	Native (Pulse)

Quickstart →

SQL + vectors + WASM in one walkthrough.

Tools & Clients →

The REPL, Studio GUI, and client libraries.

Security & Access →

Auth tokens and connectivity security.