aesql — SQL CLI

ToolsCLIREPLExport/ImportArrow

Stable On by default · production-ready

What it is

aesql is the official command-line client for AetheriusDB. It speaks the database’s two high-performance wire protocols — the native Aether-Frame protocol (port 5679) and Apache Arrow Flight SQL (port 8815) — from a single binary, and it is a pure network client: no database engine is compiled in, so you can install it on a laptop or CI runner and talk to a remote server. (For the PostgreSQL wire protocol on port 5678, use psql itself — that is what pgwire is for.)

If you know psql, you already know most of aesql: the \d family, \timing, \x, output formats, history, tab-completion against the live catalog. On top of that it adds Aetherius-native commands — live observability dashboards, reactive-table watching, LISTEN/NOTIFY tailing, one-round-trip bulk ingest, cross-transport comparison — and a compressed, multi-level database export/import facility.

Why it matters

aesql is a pure network client — no engine compiled in — so it drops onto a laptop or a CI runner and talks to any remote server without carrying a database with it. If you know psql, it’s immediately familiar, and it adds the Aetherius-native commands (live dashboards, reactive-table watching, bulk ingest) that a generic SQL client can’t offer.

Install anywhere — a single small binary, no server dependency.
Familiar, then more — the psql muscle memory works; the native commands are a bonus, not a relearn.
Two protocols, one tool — native Aether-Frame and Arrow Flight SQL from the same client.

How fast it is

Bulk ingest is a one-round-trip operation and the native protocols are low-overhead, so scripted loads and interactive queries both stay snappy — tab-completion resolves against the live catalog rather than a cached copy.

Install

On a machine with Rust installed (no database checkout or server required):

# thin client (recommended for remote machines)
cargo install --git <repo-url> aesql --no-default-features

# or download a release tarball and run its installer
tar -xzf aesql-v<version>-<platform>.tar.gz
cd aesql-<version>-<platform> && ./aesql-install.sh     # → ~/.local/bin/aesql

aesql --version

The default (workspace) build additionally bundles the developer-tool subcommands fmt, lsp, and transmute; the thin build prints a reinstall hint if you invoke one.

Connect

aesql aetherius://db-host:5679/mydb            # native protocol
aesql 'aetherius+flight://db-host:8815'        # Arrow Flight SQL
aesql db-host                                  # native first, Flight fallback
aesql aetherius://TOKEN@db-host:5679           # static-token auth

URI forms: aetherius://[token@]host[:5679][/database] and aetherius+flight://[token@]host[:8815].
Bare host tries the native port first and falls back to Flight — --native-port N / --flight-port N override the defaults for non-standard deployments.
Tokens can also come from AETHERIUS_NATIVE_AUTH_TOKEN / AETHERIUS_FLIGHT_AUTH_TOKEN.
\transport native|flight|auto|<uri> hot-swaps the transport inside a session; \c <uri> re-homes it entirely.
On the native protocol, Ctrl-C during a query resets the connection and automatically reconnects, replaying your session SETs. On Flight, Ctrl-C cancels the stream and the connection survives.

The REPL

$ aesql aetherius://127.0.0.1:5679
Connected to aetheriusd 0.1.32 (native protocol v1) at 127.0.0.1:5679 [rows-binary,lz4,stream,tx,errors,pulse]
Type \? for help, \q to quit.
aesql=> SELECT id, name FROM customers ORDER BY id;
┌────┬───────┐
│ id ┆ name  │
╞════╪═══════╡
│ 1  ┆ alice │
└────┴───────┘
(1 row)

psql-parity commands

Command	Does
`\q` `\?`	quit / full help
`\d [NAME]` `\dt` `\d+`	describe a table (real NOT NULL, `PRI`/`UNI` keys, defaults) / list tables
`\l` `\dn`	list databases / schemas
`\timing` `\x`	toggle timing / expanded output
`\pset format table\|csv\|json`	result format
`\set FETCH_COUNT N`	pager page size (default 10; `0` disables). Large results page interactively: `[Enter/Space]` next · `[a]` all · `[q]` quit, with the total row count in the status line
`\set NAME VALUE` … `:NAME`	client variables with interpolation
`\e` `\i FILE` `\o [FILE]` `\!`	editor / run script / tee output / shell
`\watch [SECS]`	re-run the last query on an interval
`\prepare NAME SQL` / `\execute NAME ARGS…`	server-side prepared statements (`$1…$N`)
`\conninfo`	transport, server version, negotiated capabilities

Multi-line editing, persistent history, syntax highlighting, and TAB-completion seeded from the live catalog (re-seeded after DDL) are on by default.

Aetherius-native commands

Command	Does
`\stats`	cluster stats, per-operator telemetry, adaptive-engine health metrics
`\cells`	WASM compute-cell fleet
`\horizon`	tiering status / growth / memory / alerts
`\graph`	visualize how tables relate and which join paths the engine has learned to optimize
`\branch list\|beacons\|use\|commit\|restore`	branch / beacon time-travel helpers
`\explain [analyze] SQL`	logical plan as an indented tree
`\listen CH` `\notify CH [MSG]` `\tail [MS]`	LISTEN/NOTIFY publish + live follow (native)
`\pulse TABLE [SECS]`	live-watch a table or matview with `+`/`−` change diff
`\ingest FILE INTO T` / `\copy T FROM FILE`	PULSE bulk CSV ingest — one round-trip (native)
`\export arrow\|csv\|json FILE [SQL]`	export a result set (Arrow IPC readable by pyarrow)
`\bench N SQL`	latency min/p50/p95/max + histogram
`\ab [SQL]`	run on both transports; compare results + latency
`\mode sql\|script\|dual`	query-language mode (native)

Export & import a database

aesql export / aesql import are the pg_dump/pg_restore of AetheriusDB. Bundles (.aexp) pack generated DDL plus per-table Arrow IPC columnar data into a single zstd-19 stream — ratio over speed, so bundles stay small even for wide tables.

# three scope levels
aesql export HOST --out db.aexp                       # 1. whole database
aesql export HOST --out sales.aexp --schema sales     # 2. one schema
aesql export HOST --out orders.aexp --table sales.orders   # 3. one object

# switches
aesql export HOST --out ddl.aexp  --no-data           # DDL only
aesql export HOST --out hot.aexp  --table orders \
      --data-query "SELECT * FROM orders WHERE qty > 1"
aesql export HOST --out q3.aexp \
      --horizon "2025-07-01 00:00:00..2025-10-01 00:00:00"

# restore (re-runnable; tolerates already-exists)
aesql import OTHER-HOST --in db.aexp [--no-data] [--skip-errors]

--no-data exports schema definitions only.
--data-query (table scope) replaces the data SELECT — export exactly the rows you want.
--horizon SINCE[..UNTIL] filters each table on its designated time column — the lowest-ordinal TIMESTAMP column, the same column the engine uses to skip data outside a time range. Tables without a time column export in full with a warning. Horizon filtering is always based on the table’s designated time column.
Reconstructed per table: columns, types, NOT NULL, DEFAULT, PRIMARY KEY/UNIQUE. Secondary indexes, materialized-view bodies, and sequences are not yet queryable from the catalog and are not carried.
The same engine powers Aether Studio’s “Database bundle” export button, so Studio downloads and CLI bundles are byte-compatible.

Scripting

Everything works headless — pipe SQL on stdin, or drive the subcommands from CI:

printf 'SELECT count(*) FROM orders;\n\q\n' | aesql aetherius://db:5679
aesql export db --out nightly.aexp && aesql import standby --in nightly.aexp

Connect a Client →

All three wire protocols and their drivers, side by side.

Aether Studio →

The visual workbench — its Database bundle export uses the same engine.

Native Ingestion →

The PULSE bulk path behind \ingest and \copy.

Observability →

The system.* views behind \stats, \cells, and \graph.