Edge Sync
What it is
Section titled “What it is”The edge runtime is a compact build of AetheriusDB that runs locally — in a browser or on a device — and answers full AetheriusDB SQL without leaving the machine. It keeps its own local replica of your data. When the network is available, the edge replica exchanges a compact set of changes with the central cluster and merges them automatically, with no manual conflict resolution.
This is “local-first” in the strict sense: your app is never blocked on a network round-trip to read or write. Reads come from the local replica; writes commit locally and stream up in the background. Multiple offline clients can edit the same data, and the merge is conflict-free by construction.
Why it matters
Section titled “Why it matters”Apps that need instant interactivity, that tolerate flaky networks, or that must keep working offline have traditionally needed a separate local store plus a hand-built sync layer. Edge Sync collapses both into one engine that speaks the same SQL on both sides.
- 0 ms reads — queries never leave the device.
- Works offline — local writes commit immediately and sync when the network returns.
- Conflict-free merges — concurrent edits combine deterministically, not by ad-hoc rules.
- One SQL, two sides — the schema and queries are identical on the edge and in the cluster.
flowchart LR classDef a fill:#1f2640,stroke:#7c5cff,color:#e8eaf0 classDef b fill:#1f2640,stroke:#00d4ff,color:#e8eaf0 classDef g fill:#1f2640,stroke:#4ade80,color:#4ade80 UI[Application]:::a --> E[Edge replica<br/>local storage]:::b E --> L[Local query<br/>0 ms]:::g E -. periodic sync .-> S[Cluster]:::a S -. merged updates .-> E
How you use it
Section titled “How you use it”Open a local handle to the edge runtime, run the same SQL you would run against the cluster, and let the runtime handle the sync. The example below shows a TypeScript app issuing reads and writes that survive an offline window.
// Open the local edge database — same SQL surface as the cluster.import { openEdge } from "@aetherius/edge";
const db = await openEdge({ schema: "app_v3", cluster_url: "aether://cluster.example.com:8967/app_db", sync_policy: "continuous", // or "manual" conflict_rule: "last-writer-wins"});
// Reads are instant — no network round-trip.const tasks = await db.query("SELECT id, title FROM tasks WHERE done = false");
// Writes commit locally first; the runtime queues them for upload.await db.exec("INSERT INTO tasks(id, title) VALUES ($1, $2)", [taskId, title]);
// Inspect sync state at any time.const status = db.syncStatus(); // { pending: 4, last_sync: ..., online: true }When the network returns, the runtime exchanges a compact diff with the cluster. The cluster merges using the configured conflict rule and streams the resulting state back to every connected edge replica.
Key concepts
Section titled “Key concepts”| Term | Meaning |
|---|---|
| Edge replica | A local build of the engine that runs in the browser or on-device. |
| Local-first | The app reads and writes the local replica; sync happens in the background. |
| Conflict-free merge | Concurrent edits combine deterministically when replicas reconnect. |
| Sync policy | When the runtime exchanges changes — continuous, periodic, or manual. |
| Conflict rule | How concurrent writes are resolved — last-writer-wins or a custom commutative rule. |