@abloatai/ablo 0.30.2 → 0.31.0

package/docs/data-sources.md

@@ -1,31 +1,49 @@
 # Connect Your Database
 
-**Connect your database = Postgres logical replication.** That is the one way.
-Ablo reads your write-ahead log (WAL) and **never runs DDL, never owns your
-schema, and never migrates it**. Your application keeps writing to its own
-Postgres through its own backend, exactly as it does today; Ablo only tails the
-changes and fans the confirmed rows out to every connected human and agent. This
-is the same model ElectricSQL, PowerSync, and Zero use — a publication plus a
-replication slot. Ablo consumes the logical-replication stream; your application
-continues to own the write path.
+You write through Ablo, and Ablo writes to your Postgres. A call to
+`ablo.<model>.create / update / delete` enters Ablo's commit chokepoint — where
+claims, ordering, and idempotency are enforced — and Ablo applies the change to
+your database through a scoped role. Your rows live in your database, which stays
+the system of record. Ablo reads your write-ahead log (WAL) to confirm each write
+landed and to keep every connected human and agent current.
+
+Ablo writes your **rows**; it never touches your **schema**. It runs no DDL and no
+migrations — your migration tool stays in charge of the shape of your database.
+Ablo only writes rows into tables you already have, through a role scoped to
+exactly that.
+
+> **Just trying Ablo?** You don't need a database to start. Pass an `apiKey` only,
+> and Ablo keeps your rows in its own log so you can build the whole app today —
+> like Stripe test mode. For a sandbox you can throw away, point Ablo at a separate
+> or local Postgres. Connect your production database (below) when you're ready for
+> it to be the system of record.
+
+Connecting sets up two capabilities on your Postgres: **logical replication**, so
+Ablo can read and confirm, and a **scoped DML role**, so Ablo can write. `ablo
+connect` prints the exact SQL. `ablo connect --apply` runs it for you.
+
+## Connect in one command
 
-> **Just trying Ablo?** You don't need a database at all to start. The hosted
-> **sandbox** can host rows in Ablo's test plane — pass an `apiKey` only and omit
-> any database setup, like Stripe test mode. Connect your Postgres with logical
-> replication (below) when you're ready for it to be the system of record.
+```bash
+npx ablo connect --apply --url postgres://admin:...@host:5432/db
+```
 
-Your database stays the system of record. Ablo never becomes a second source of
-truth and never takes over operating your Postgres.
+Pass an admin connection string with `--url` and it creates the publication, the
+two scoped roles, and the grants, turns on logical decoding where it can, registers
+both scoped roles with Ablo, and proves the setup by reconnecting and reading back.
+The admin credential is used on this machine only and never persisted — nothing is
+written to your `.env`, which keeps holding only `ABLO_API_KEY`. Pass `--show-sql`
+to see every statement first, or drop `--apply` to print the SQL and run it
+yourself. Rotate the scoped passwords any time with `ablo connect --rotate`.
 
-## The five steps (mirrors Zero's install flow)
+The rest of this page is what that command sets up, step by step, for when you want
+to run it by hand or review exactly what changes.
 
-You run the setup once against your own database, then point Ablo at it. The CLI
-prints the exact SQL and validates it for you — you never hand-craft replication
-internals.
+## The setup, step by step
 
 ### 1. Enable logical decoding
 
-Turn on logical WAL so Ablo can decode row changes:
+Turn on logical WAL so Ablo can decode row changes and confirm writes:
 
 ```sql
 ALTER SYSTEM SET wal_level = 'logical';
@@ -34,21 +52,20 @@ ALTER SYSTEM SET wal_level = 'logical';
 `wal_level` is **not reloadable** — you must **restart Postgres** for it to take
 effect. On Amazon RDS / Aurora you can't `ALTER SYSTEM`; set
 `rds.logical_replication = 1` in the instance's parameter group instead, then
-reboot.
+reboot. (`ablo connect --apply` attempts this for you and, where a managed
+provider refuses, hands you the one remaining step.)
 
-### 2. Run `ablo connect` to get the publication / slot / role SQL
+### 2. Run `ablo connect` for the publication and roles
 
 ```bash
 npx ablo connect
 ```
 
-`ablo connect` prints the exact, copy-pasteable setup SQL for **your** Postgres
-and nothing else — it does not ask for a connection-string flavor, an adapter, or
-a driver, because logical replication is how you connect. Run the printed SQL
-against your database (as a superuser / the DB owner). It does three things:
+`ablo connect` prints the exact, copy-pasteable setup SQL for **your** Postgres.
+Run it against your database as a superuser or the DB owner. It creates:
 
-- **A publication** naming the tables Ablo should read (`ablo_publication`, the
-  single canonical name the runtime subscribes to):
+- **A publication** naming the tables Ablo reads and confirms against
+  (`ablo_publication`, the single canonical name the runtime subscribes to):
 
   ```sql
   CREATE PUBLICATION "ablo_publication" FOR ALL TABLES;
@@ -56,22 +73,33 @@ against your database (as a superuser / the DB owner). It does three things:
 
   Scope it to a subset with `npx ablo connect --tables a,b,c`.
 
-- **A least-privilege replication role** — it can stream replication and `SELECT`,
-  nothing more. You choose the password; it never passes through Ablo's CLI or
-  servers:
+- **A replication role** — it streams the WAL and `SELECT`s, nothing more. This is
+  the role Ablo reads and confirms through. You choose the password; it never
+  passes through Ablo's CLI or servers:
 
   ```sql
   CREATE ROLE "ablo_replicator" WITH REPLICATION LOGIN PASSWORD '<password>';
   GRANT SELECT ON ALL TABLES IN SCHEMA public TO "ablo_replicator";
-  ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON TABLES TO "ablo_replicator";
   ```
 
-  Rename it with `--role <name>`. On Amazon RDS the `REPLICATION` attribute is
-  granted, not set directly: `GRANT rds_replication TO "ablo_replicator";`.
+  On Amazon RDS the `REPLICATION` attribute is granted, not set directly:
+  `GRANT rds_replication TO "ablo_replicator";`.
+
+- **A scoped writer role** — the role Ablo writes your rows through. It gets row
+  DML (`SELECT, INSERT, UPDATE, DELETE`) and the sync ledger, and nothing else: no
+  `REPLICATION`, no schema `CREATE`, `NOSUPERUSER NOBYPASSRLS`, row security on. It
+  can change rows in your tables; it cannot change your database:
+
+  ```sql
+  CREATE ROLE "ablo_writer" WITH LOGIN PASSWORD '<write-password>'
+    NOSUPERUSER NOBYPASSRLS NOCREATEDB NOCREATEROLE NOREPLICATION NOINHERIT;
+  GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA public TO "ablo_writer";
+  ```
+
+  Rename either role with `--role <name>` / `--write-role <name>`.
 
 The **replication slot** is created and owned by Ablo's runtime when it first
-subscribes with this role — you don't pre-create it. The publication and the role
-are the only objects the recipe asks you to create.
+subscribes — you don't pre-create it.
 
 ### 3. Validate with `ablo connect --check`
 
@@ -82,27 +110,40 @@ database is replication-ready:
 npx ablo connect --check
 ```
 
-This connects and checks the four invariants, printing a green checklist or the
-precise per-item fix:
+It checks the four invariants and prints a green checklist or the precise per-item
+fix:
 
 - `wal_level` is `logical`
 - the `ablo_publication` publication exists
-- the `DATABASE_URL` role has the `REPLICATION` attribute
+- the replication role has the `REPLICATION` attribute
 - every published table has a usable `REPLICA IDENTITY` (a primary key, or
   `REPLICA IDENTITY FULL`) so `UPDATE`/`DELETE` can replicate
 
+`--check` reads the two scoped roles from `ABLO_REPLICATION_DATABASE_URL` and
+`ABLO_WRITE_DATABASE_URL` (the `ABLO_`-namespaced names keep a replication-only
+credential from ever landing in the generic `DATABASE_URL` your ORM reads).
 Re-run it until every item is green.
 
-### 4. Point Ablo at the database with the replication role
+### 4. Register the two roles with Ablo
+
+`ablo connect --apply` already did this. If you ran the SQL by hand instead, hand
+Ablo both connection strings — the replication role it reads and confirms through,
+and the writer role it lands your rows through:
+
+```bash
+npx ablo connect --register
+```
+
+This is out of band and happens once. `--register` reads the two scoped connection
+strings from `ABLO_REPLICATION_DATABASE_URL` and `ABLO_WRITE_DATABASE_URL` and
+posts them to Ablo, which holds them encrypted and uses them to read and write your
+database. The role passwords are generated for you and never printed — rotate them
+any time with `ablo connect --rotate`. After this, Ablo does all the connecting.
 
-Give Ablo the connection string for the **replication role** you created — a
-`REPLICATION`-attributed role that streams the WAL and `SELECT`s, nothing more
-(not a read-only account; see the privilege note below). The same value `--check`
-validated:
+Your **app** holds only the API key — never a connection string:
 
 ```bash
 # .env — server runtime only, never the browser
-DATABASE_URL=postgres://ablo_replicator:<password>@host:5432/db?sslmode=require
 ABLO_API_KEY=sk_live_...
 ```
 
@@ -116,28 +157,33 @@ export const ablo = Ablo({
 });
 ```
 
-You define an Ablo schema with `defineSchema`, `model`, and Zod. The Ablo schema
-describes **only your synced, collaborative models** — the rows Ablo coordinates
-and fans out in realtime. It is *not* your whole-database schema and does *not*
-replace your `schema.prisma` (or your Drizzle schema). Your auth, billing, and
-any other tables stay in your own ORM schema, owned by your own migrations.
-`ablo check` reflects this — it reports tables you didn't declare as "ignored /
-owned by you," which is exactly right.
+The Ablo schema describes **only your synced, collaborative models** — the rows
+Ablo coordinates and fans out in realtime. It is *not* your whole-database schema
+and does *not* replace your `schema.prisma` (or Drizzle schema). Your auth,
+billing, and other tables stay in your own ORM schema, owned by your own
+migrations. `ablo check` reflects this — it reports tables you didn't declare as
+"ignored / owned by you," which is exactly right.
 
-### 5. Writes go through your own backend
+### 5. Write through `ablo.<model>`
 
-Your application writes to its Postgres the way it always has — its own ORM, its
-own backend, its own transactions. Ablo does not intercept or proxy those writes.
-It observes them on the WAL and fans the confirmed rows out to connected clients.
-The read, claim, and coordination surface (`ablo.<model>`) layers on top:
+Every change goes through Ablo. The write enters the commit chokepoint, Ablo
+applies it to your Postgres through the writer role, and the WAL echo confirms it
+landed:
 
 ```ts
+// Enters the chokepoint (claims, ordering, idempotency), lands in your Postgres.
+await ablo.weatherReports.update('report_stockholm', { high: 21 });
+
+// Block until your database has it and the WAL echo confirms.
+await ablo.weatherReports.update('report_stockholm', { high: 21 }, { wait: 'confirmed' });
+
+// Reads are live off the same stream.
 const report = ablo.weatherReports.get('report_stockholm');
-const active = ablo.weatherReports.claim.state({ id: 'report_stockholm' });
 ```
 
-For the typed read/claim/write surface itself, see
-[Quickstart](./quickstart.md) and [Schema Contract](./schema-contract.md).
+A commit is accepted the moment Ablo takes it (`queued`); it becomes `confirmed`
+once the row appears on your WAL. See [Guarantees](./guarantees.md) for what each
+state means and when to wait.
 
 ## What Ablo touches in your database — the honest footprint
 
@@ -145,9 +191,10 @@ This is the complete list. Nothing else.
 
 | Object | What it is | Owned by |
 |---|---|---|
-| `ablo_publication` | A Postgres publication naming the tables Ablo reads. | You create it (step 2). |
+| `ablo_publication` | A publication naming the tables Ablo reads and confirms against. | You create it (step 2). |
+| `ablo_replicator` role | A `REPLICATION` + `SELECT` role Ablo reads and confirms through. | You create it (step 2). |
+| `ablo_writer` role | A scoped DML role Ablo writes your rows through — row DML + ledger, nothing more. | You create it (step 2). |
 | Replication slot | A logical slot Ablo subscribes through to track its WAL position. | Ablo's runtime creates it on first connect. |
-| `ablo_replicator` role | A least-privilege `REPLICATION` + `SELECT` role. | You create it (step 2). |
 | `wal_level = logical` | A server setting that **requires a restart**. | You set it (step 1). |
 
 Operational reality you should know up front:
@@ -155,30 +202,26 @@ Operational reality you should know up front:
 - **`wal_level = logical` needs a restart.** It is a one-time, server-wide change
   and is not reloadable.
 - **A replication slot retains WAL.** While Ablo is connected, the slot holds the
-  WAL it hasn't yet acknowledged. If Ablo is disconnected for a long time, that
-  WAL accumulates and consumes disk. **Ablo monitors slot lag and WAL retention**
-  and surfaces it so you're never surprised by disk pressure; an abandoned slot is
-  dropped rather than left to grow unbounded.
-- **The role's privilege footprint is narrow and precise — not a "read-only"
-  account.** It carries the `REPLICATION` attribute, which lets it stream the WAL
-  and `SELECT`; it cannot `INSERT`/`UPDATE`/`DELETE`, run DDL, or own objects, and
-  the recipe never grants it more. (For a security review, state it that way — a
-  logical-replication role is a real privilege, just a tightly-scoped one — rather
-  than calling it "read-only", which a reviewer will correctly push back on.)
-
-What Ablo explicitly does **not** do:
-
-- It **never runs DDL** against your database.
-- It **never owns or migrates your schema** — your migration tool stays in charge.
-- It **never writes your rows** — writes are yours, through your backend.
+  WAL it hasn't yet acknowledged. If Ablo is disconnected for a long time, that WAL
+  accumulates and consumes disk. **Ablo monitors slot lag and WAL retention** and
+  surfaces it, so disk pressure never surprises you; an abandoned slot is dropped
+  rather than left to grow unbounded.
+- **The writer role changes rows, not your database.** It carries row DML plus the
+  sync ledger and nothing more — no `REPLICATION`, no DDL, no object ownership, and
+  it runs with row security on and `NOBYPASSRLS`. It is a real, tightly-scoped
+  privilege — describe it that way in a security review.
+
+Ablo runs **no DDL** and **owns no schema**: your migration tool stays in charge of
+the shape of your database, and Ablo writes only rows, only into tables you already
+have.
 
 ## What Ablo stores on its side
 
 Your schema *definition* (model names, fields, types — pushed with `ablo push`),
 your hashed API keys, a safe projection of the connection registration (host,
 database, schema — the connection string itself is sealed and never echoed back),
-the replication slot position, and the commit log that drives sync. Never your
-rows.
+the replication slot position, and the ordered transaction log that drives sync and
+coordination. Your rows live in your database.
 
 > **Postgres replication status: Preview.** Registration, readiness checks, and
 > the server replication fleet are implemented and boot-wired. Preview describes
@@ -186,6 +229,17 @@ rows.
 > [internal/postgres-replication.md](./internal/postgres-replication.md) for the
 > architecture and operational invariants.
 
+## When your database can't grant replication
+
+Some managed databases won't grant a `REPLICATION` role. For those, Ablo connects
+through a **signed Data Source endpoint** instead: you expose one signed HTTP route
+built from your ORM (`prismaDataSource` / `drizzleDataSource`, with `ablo_outbox` /
+`ablo_idempotency` bookkeeping), and Ablo writes and confirms through it — same
+`ablo.<model>` surface, same commit chokepoint, same `queued` → `confirmed`
+lifecycle. It needs no replication setup, which is exactly why it's the fallback:
+reach for it only when logical replication isn't available, and prefer `ablo
+connect` everywhere else.
+
 ## Next steps
 
 - [Quickstart](./quickstart.md) — connect and write through `ablo.<model>`.
@@ -194,20 +248,3 @@ rows.
 - [Guarantees](./guarantees.md) — what confirmed writes and stale checks mean.
 - [Integration Guide](./integration-guide.md) — the full app, React, multiplayer,
   and agent path.
-
----
-
-## Legacy / not recommended
-
-> **Use logical replication instead** (top of this page). The shapes below
-> predate the single connect path. They are documented only so existing
-> integrations can be read and understood — do **not** reach for them when
-> connecting a new database. They are the seams that caused painful onboarding,
-> and `ablo connect` exists precisely to replace them.
-
-This older shape connected Ablo to a database by exposing a **signed Data Source
-endpoint** built from an ORM adapter (`prismaDataSource` / `drizzleDataSource`,
-with `ablo_outbox` / `ablo_idempotency` bookkeeping and a reverse-channel
-connector for VPCs). It required Ablo to proxy every write, and has been superseded
-by logical replication, where Ablo only reads your WAL. If you are maintaining one
-of these integrations, migrate it to `ablo connect` at the next opportunity.

package/docs/integration-guide.md

@@ -47,11 +47,12 @@ objects by hand.
 Every schema model is backed by **your own database**. The SDK call shape is the
 same everywhere.
 
-In this guide — an app that already owns its backend and database — keep
-`DATABASE_URL` inside your app and connect it out of band: run `npx ablo connect`
-for logical replication (Ablo tails your WAL), or expose a signed Data Source
-endpoint where Ablo coordinates each write and your app commits it to your
-Postgres. Either way, application and agent code hold only `ABLO_API_KEY` — the
+In this guide — an app that already owns its backend and database — keep the
+database credentials inside your server runtime and connect out of band: run `npx
+ablo connect` to set up logical replication and a scoped writer role, or expose a
+signed Data Source endpoint when your database can't grant replication. Either way,
+you write through `ablo.<model>`; Ablo lands each change in your Postgres and
+confirms it over the WAL. Application and agent code hold only `ABLO_API_KEY` — the
 client never sees a connection string. [Connect Your Database](./data-sources.md)
 is the single source of truth for both paths.
 

package/docs/quickstart.md

@@ -2,15 +2,16 @@
 
 Build with Ablo on **the Postgres you already have**. You declare a small Ablo
 schema for the models humans and agents edit together, connect Ablo to your
-database with **logical replication** (`ablo connect`), and coordinate every read
-and claim through `ablo.<model>`. Your database stays the system of record: your
-app keeps writing through its own backend, Ablo tails your write-ahead log (WAL),
-and the confirmed rows fan out to every connected client. Ablo **never runs DDL,
-owns, or migrates your schema**.
+database (`ablo connect`), and read and write every one of those models through
+`ablo.<model>`. You write through Ablo; it lands the change in your Postgres and
+confirms it by tailing your write-ahead log (WAL). Your rows live in your database,
+which stays the system of record. Ablo writes rows but **runs no DDL and owns no
+schema** — your migration tool stays in charge of the shape of your database.
 
-> No database yet? The hosted **sandbox** can host rows in Ablo's test plane —
-> pass an `apiKey` only and skip the database setup, like Stripe test mode — so
-> you can try Ablo before connecting your Postgres.
+> No database yet? Pass an `apiKey` only and Ablo keeps your rows in its own log,
+> so you can build the whole app today — like Stripe test mode. Point it at a
+> separate or local Postgres for a throwaway sandbox, or at your production
+> database when you're ready.
 
 ## 1. Install and initialize
 
@@ -97,32 +98,38 @@ collapses to the untyped client.
 
 ## 3. Connect your database with `ablo connect`
 
-Connecting a real database = Postgres logical replication, and `ablo connect` is
-the one way to set it up. Ablo **reads** your WAL and never runs DDL, owns, or
-migrates your schema — your app keeps writing through its own backend.
+`ablo connect` sets your database up so Ablo can write your rows (a scoped DML
+role) and read them back to confirm (logical replication). It writes rows through
+that role but runs no DDL and owns no schema — your migration tool stays in charge.
 
-```bash
-# 1. Enable logical decoding (then RESTART Postgres — wal_level is not reloadable)
-#    ALTER SYSTEM SET wal_level = 'logical';
-#    On RDS/Aurora: set rds.logical_replication = 1 in the parameter group, reboot.
-
-# 2. Print the exact publication + replication-role SQL for YOUR Postgres, run it:
-npx ablo connect
+You run `ablo connect` once, out of band — it provisions the roles and hands them
+to Ablo. From then on Ablo does the connecting; your app never opens a database
+connection.
 
-# 3. Put the replication role's connection string in DATABASE_URL, then validate:
-npx ablo connect --check
+```bash
+# Point it at an admin connection once — it does the whole ceremony: creates the
+# roles + publication, turns on logical decoding where it can, registers both
+# scoped roles with Ablo, and proves it by reading back. Nothing lands in your .env.
+npx ablo connect --apply --url postgres://admin:...@host:5432/db
+
+# ...or print the SQL and run it yourself, then register:
+#   npx ablo connect            # prints the publication + two scoped roles
+#   npx ablo connect --check    # validates the database is ready
+#   npx ablo connect --register # hands the two scoped roles to Ablo
 ```
 
-`ablo connect` prints the copy-pasteable SQL (a publication named
-`ablo_publication` and a least-privilege `ablo_replicator` role with
-`REPLICATION` + `SELECT`, password you choose). `ablo connect --check` connects to
-`DATABASE_URL` and verifies `wal_level=logical`, the publication, the role's
-`REPLICATION` attribute, and that every published table has a usable
-`REPLICA IDENTITY` — a green checklist or the precise fix per item.
+`ablo connect --apply` generates two roles and their passwords — an
+`ablo_replicator` role (`REPLICATION` + `SELECT`, for reads and confirmation) and
+an `ablo_writer` role (scoped row DML, for writes) — and registers both connection
+strings with Ablo's control plane, encrypted. Ablo's runtime uses them to read and
+write your database. The admin credential you pass to `--url` is used on this
+machine only and never persisted. The role passwords are generated for you and
+never printed — rotate them any time with `ablo connect --rotate`.
+
+Your **app** holds only the API key — never a connection string:
 
 ```bash
 # .env — server runtime only, never the browser
-DATABASE_URL=postgres://ablo_replicator:<password>@host:5432/db?sslmode=require
 ABLO_API_KEY=sk_test_...
 ```
 
@@ -137,9 +144,9 @@ export const ablo = Ablo({
 });
 ```
 
-The full setup, the honest footprint (publication + slot + `REPLICATION` role +
-the `wal_level` restart + slot/WAL retention Ablo monitors), and the Preview
-status of the WAL runtime are in [Connect Your Database](./data-sources.md).
+The full setup, the honest footprint (publication + slot + the `REPLICATION` and
+writer roles + the `wal_level` restart + slot/WAL retention Ablo monitors), and the
+Preview status are in [Connect Your Database](./data-sources.md).
 
 ## 4. Push the schema, then map it to tables
 

package/docs/schema-contract.md

@@ -102,11 +102,13 @@ the fresh row. Reads stay open; only acting on the row serializes.
 
 ## Storage boundary
 
-Every schema model is backed by your own database. There are three start states,
-all covered in [Connect Your Database](./data-sources.md) (the single source of
-truth): the sandbox (`apiKey` only, no database), logical replication set up with
-`npx ablo connect` (Ablo tails your WAL), or a signed Data Source endpoint where
-your app keeps the database credential and commits each write itself.
+Every schema model is backed by your own database, and you write to it through
+`ablo.<model>`. There are three start states, all covered in [Connect Your
+Database](./data-sources.md) (the single source of truth): the sandbox (`apiKey`
+only, no database — Ablo keeps your rows in its own log), `npx ablo connect` (a
+scoped writer role plus logical replication, so Ablo writes your rows and confirms
+them over the WAL), or a signed Data Source endpoint when your database can't grant
+replication.
 
 Your database connects out of band, so the client holds only `ABLO_API_KEY` —
 never a connection string. Browser code goes through `<AbloProvider>` or a scoped

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abloatai/ablo",
-  "version": "0.30.2",
+  "version": "0.31.0",
   "description": "The Collaboration Layer For AI Agents",
   "license": "Apache-2.0",
   "type": "module",