arn-db 0.0.0-stage → 0.2.0

package/GUIDE.md

@@ -0,0 +1,829 @@
+# arn-db guide
+
+Recipes organised by "I want to…". Every example runs against the test database
+in this repo (`db/init.sql`), and the outputs shown are the real results:
+`test/guide.test.ts` checks them on every test run.
+
+The example tables:
+
+```
+users        id, name, email, age, active, meta jsonb, settings json, tags text[], scores jsonb
+posts        id, user_id → users, reviewer_id → users, title, published      (user_N has N % 3 posts)
+comments     id, post_id → posts, author_id → users, body
+labels       id, name
+post_labels  post_id → posts, label_id → labels                              (posts ↔ labels)
+```
+
+Contents:
+[Setup](#setup) ·
+[Selecting](#selecting) ·
+[Filtering](#filtering) ·
+[Ordering and random](#ordering-and-random) ·
+[Related tables](#related-tables) ·
+[Searching across 3+ tables](#searching-across-3-tables) ·
+[Searching arrays](#searching-arrays) ·
+[Counting](#counting) ·
+[Aggregates and grouping](#aggregates-and-grouping) ·
+[Insert, update, delete](#insert-update-delete) ·
+[Changing jsonb and arrays](#changing-jsonb-and-arrays) ·
+[Upsert and find-or-create](#upsert-and-find-or-create) ·
+[Writing related rows](#writing-related-rows) ·
+[Transactions](#transactions) ·
+[Read replicas](#read-replicas) ·
+[Raw SQL fragments](#raw-sql-fragments) ·
+[Errors](#errors) ·
+[Not supported yet](#not-supported-yet)
+
+---
+
+## Setup
+
+Set two environment variables (in the app's `.env` or its container env):
+
+```
+ARN_DB_URL=https://your-api.example.com/v2/raw
+ARN_DB_KEY=<your API key>
+```
+
+Then import the ready-made `db` anywhere. It has everything: `db.from()`,
+`db.transaction()`, `db.ops.*` and `db.rel.*`.
+
+```ts
+import { db } from 'arn-db'
+
+await db.from('users').update({ scores: db.ops.append(4) }).eq('id', id)
+await db.from('posts').insert({ title, user_id, comments: db.rel.create([{ body, author_id }]) })
+```
+
+`db` reads the variables on its first query, not on import, so loading dotenv
+later in startup still works. If they aren't set yet, it loads `./.env` from the
+working directory first (Node 20.12+). Variables that are already set always win.
+A missing variable throws on that first query.
+
+Inside `transaction()` the same helpers are on `tx`: `tx.from()`, `tx.ref()`,
+`tx.ops.*`, `tx.rel.*`. (`import { ops, rel } from 'arn-db'` still works too.)
+
+For another key, another server, or other options, make your own client:
+
+```ts
+import { createClient } from 'arn-db'
+
+const reports = createClient(process.env.REPORTS_DB_URL!, process.env.REPORTS_DB_KEY!, { readFrom: 'replica' })
+```
+
+Every call resolves to the same shape and never throws:
+
+```ts
+const { data, error, count, status } = await db.from('users').select()
+if (error) {
+  // error.message, error.code, error.details
+}
+```
+
+Server-side only: requests are POSTs with an `apikey` header; the API refuses browsers.
+
+---
+
+## Selecting
+
+| I want | Write |
+|---|---|
+| all columns | `select()` or `select('*')` |
+| some columns | `select('id, name, email')` |
+| a column under another name | `select('id, fullName:name')` |
+| a value inside jsonb, as text | `select('city:meta->>city')` |
+| a value inside jsonb, keeping its type | `select('score:meta->score')` |
+| deeper inside jsonb | `select('zip:meta->address->>zip')` |
+| converted to a type | `select('score:meta->>score::int')` |
+
+```ts
+await db.from('users')
+  .select('name, city:meta->>city, zip:meta->address->>zip, score:meta->score')
+  .eq('name', 'user_7')
+  .single()
+// { name: 'user_7', city: 'Paris', zip: '1007', score: 7 }
+//                                   ^ ->> gives text   ^ -> keeps the number
+```
+
+**One row or many:**
+
+```ts
+.single()       // one object, or null if no row (never an error for 0 or many: it adds LIMIT 1)
+.limit(1)       // always an array: [ {...} ], or [] if no row
+.range(10, 19)  // rows 10..19 (0-based, inclusive)
+```
+
+`single()` can't be combined with `limit()` or `range()`. With several matches
+it returns the first one in your `order()`, so look rows up by a unique column
+(or add `order()`) when it matters which one you get.
+
+---
+
+## Filtering
+
+```ts
+.eq('active', true)               .neq('name', 'x')
+.gt('age', 30)  .gte('age', 30)   .lt('age', 30)  .lte('age', 30)
+.like('name', 'user\\_1%')        .ilike('email', '%@EXAMPLE.com')   // _ and % are wildcards
+.in('name', ['user_3', 'user_5'])
+.is('age', null)                  // also true / false
+.match({ active: true, age: 30 }) // several eq at once
+```
+
+Filters combine with AND (for OR and NOT see [groups](#or-not-and-groups)). Filters work on jsonb paths too:
+
+```ts
+.eq('meta->>city', 'Tokyo')              // text inside jsonb
+.eq('meta->vip', true)                   // keeps the JSON type
+.eq('meta->address->>zip', 1042)         // deeper
+.gte('meta->>score::int', 98)            // cast for number comparison
+```
+
+```ts
+await db.from('users').select('name, score:meta->>score::int')
+  .gte('meta->>score::int', 98).order('meta->>score::int')
+// [{ name: 'user_98', score: 98 }, { name: 'user_99', score: 99 }, { name: 'user_100', score: 100 }]
+```
+
+Without `::int`, `->>` compares as text, so `'9' > '10'`.
+
+### Comparing two columns, and the database time
+
+`db.col(name)` is another column of the same row; `db.now()` is the database
+server's `now()`. Both work with `eq`, `neq`, `gt`, `gte`, `lt` and `lte`, also inside groups.
+
+```ts
+.lt('age', db.col('meta->>limit::int'))                       // age < (meta->>limit)::int
+.lt(db.col('age').ifNull(0), db.col('meta->>limit::int'))     // COALESCE(age, 0) < ...
+.lt('age', db.col('meta->>limit::int').ifNull(100))           // ifNull on the right side
+.gte(db.col('age').ifNull(0), 5)                              // ifNull with a plain value
+
+.gt('created_at', db.now().minus('1 day'))                    // the last 24 hours
+.lte('sent_at', db.now().minus('1 hour'))
+.lt('expires_at', db.now().plus('30 minutes'))
+```
+
+- Intervals are one number and one unit: `second`, `minute`, `hour`, `day`, `week`,
+  `month` or `year` (plural is fine). One `plus()` or `minus()` per `db.now()`.
+- `db.col()` takes columns of the same table only (jsonb paths and casts are fine).
+- `db.now()` also works as a value: `update({ last_read_time: db.now() })`, or in
+  `insert()` when every row uses the same `db.now()`. The time comes from the
+  database, so app servers with different clocks agree.
+
+### OR, NOT and groups
+
+Chained filters are AND. `or()`, `and()` and `not()` take a callback that
+builds one grouped condition; groups nest as deep as you need.
+
+```ts
+// age > 60 OR city = 'Dhaka'
+.or((q) => q.gt('age', 60).eq('meta->>city', 'Dhaka'))
+
+// active AND (Tokyo OR Paris) AND age < 25
+.eq('active', true).or((q) => q.eq('meta->>city', 'Tokyo').eq('meta->>city', 'Paris')).lt('age', 25)
+
+// role = 'admin' OR (age >= 18 AND verified)
+.or((q) => q.eq('role', 'admin').and((q) => q.gte('age', 18).is('verified', true)))
+
+// NOT: a short form for one condition, a callback for several (joined with AND)
+.not('deleted_at', 'is', null)
+.not((q) => q.eq('active', true).gte('age', 40))                        // NOT (active AND age >= 40)
+.not((q) => q.or((q) => q.eq('meta->>city', 'Tokyo').eq('meta->>city', 'Berlin')))  // neither
+```
+
+- Inside `or()` the conditions are joined with OR; inside `and()` and `not()` with AND.
+- Every filter method works inside a group: jsonb paths, casts, `in`, `contains`, `match`, `filter`.
+- Groups work in `count()`, `update()`, `delete()` and transactions (`tx.ref()` too).
+- NULL is neither true nor false, as in Postgres: a row with a null `reviewer_id`
+  matches neither `.eq('reviewer_id', id)` nor `.not('reviewer_id', 'eq', id)`.
+  Add `.is('reviewer_id', null)` in an `or()` to keep those rows.
+- All conditions in one group must be on the same table. A group on
+  `posts.*` filters the related posts, like `.eq('posts.published', true)`
+  (add `!inner` to also drop parents without a match):
+
+```ts
+await db.from('users').select('name, posts!user_id(title)')
+  .or((q) => q.eq('posts.title', 'user_5_post_2').eq('posts.published', true))
+```
+
+Mixing tables in one group (`name = 'x' OR posts.published`) is an error for now.
+
+---
+
+## Ordering and random
+
+**Several orders:** chain them; they apply in the order written. Ascending is the default.
+
+```ts
+await db.from('users').select('name, active, age')
+  .in('name', ['user_4', 'user_8', 'user_12', 'user_54', 'user_58'])
+  .order('active', { ascending: false })  // 1st: active first
+  .order('age', { ascending: false })     // 2nd: then oldest
+  .order('name')                          // 3rd: then by name
+// [
+//   { name: 'user_58', active: true,  age: 26 },
+//   { name: 'user_54', active: true,  age: 22 },
+//   { name: 'user_12', active: false, age: 30 },
+//   { name: 'user_8',  active: false, age: 26 },
+//   { name: 'user_4',  active: false, age: 22 },
+// ]
+```
+
+Options: `{ ascending: false, nullsFirst: true }`. Columns can be jsonb paths: `.order('meta->>score::int')`.
+
+**Random:**
+
+```ts
+.random()                                    // shuffle everything
+.random().limit(5)                           // 5 random rows
+.order('active', { ascending: false }).random()  // active first, shuffled within each group
+```
+
+**Random pages:** plain `random()` reshuffles on every request, so page 2 can
+repeat page 1. Give a seed (e.g. a session id) for a stable order:
+
+```ts
+await db.from('posts').select().random({ seed: sessionId }).range(0, 9)    // page 1
+await db.from('posts').select().random({ seed: sessionId }).range(10, 19)  // page 2: no repeats, no gaps
+```
+
+Same seed gives the same order; another seed gives another shuffle.
+
+---
+
+## Related tables
+
+Write the related table's name in `select()`, with its columns in brackets.
+The table name becomes the key, or an alias if you give one.
+
+### Reading the select string
+
+```ts
+.select('name, posts!user_id!inner(title, labels(name))')
+```
+
+| Piece | Meaning |
+|---|---|
+| `name` | a column of the main table |
+| `posts(...)` | also bring rows from `posts`, under the key `posts` |
+| `!user_id` | which link: `posts` has two FKs to `users` (`user_id`, `reviewer_id`) |
+| `!inner` | only keep main rows that have a match (like INNER JOIN) |
+| `title` | a column of each post |
+| `labels(name)` | for each post, also bring its labels |
+| `author:users(...)` | an alias: the key is `author` instead of `users` |
+
+### Directions
+
+**Many-to-one** (post → its author): an object, or null.
+
+```ts
+await db.from('posts').select('title, author:users!user_id(name)').eq('title', 'user_5_post_1').single()
+// { title: 'user_5_post_1', author: { name: 'user_5' } }
+```
+
+**One-to-many** (user → their posts): an array, `[]` when none.
+
+```ts
+await db.from('users').select('name, posts!user_id(title)').eq('name', 'user_5')
+  .order('title', { referencedTable: 'posts' }).single()
+// { name: 'user_5', posts: [{ title: 'user_5_post_1' }, { title: 'user_5_post_2' }] }
+```
+
+**Many-to-many** (posts ↔ labels through `post_labels`): an array; the junction is found automatically.
+
+```ts
+await db.from('posts').select('title, labels(name)').eq('title', 'user_5_post_2')
+  .order('name', { referencedTable: 'labels' }).single()
+// { title: 'user_5_post_2', labels: [{ name: 'go' }, { name: 'node' }] }
+```
+
+**Nested, any depth:**
+
+```ts
+await db.from('users')
+  .select('name, posts!user_id(title, comments(body, author:users(name)), labels(name))')
+  .eq('name', 'user_5').order('title', { referencedTable: 'posts' }).single()
+// {
+//   name: 'user_5',
+//   posts: [
+//     { title: 'user_5_post_1',
+//       comments: [{ body: 'comment on user_5_post_1', author: { name: 'user_2' } }],
+//       labels: [{ name: 'sql' }] },
+//     { title: 'user_5_post_2', comments: [], labels: [{ name: 'go' }, { name: 'node' }] },
+//   ],
+// }
+```
+
+**All columns of a relation:** `select('*, posts!user_id(*)')`.
+
+**When do I need `!hint`?** Only when two tables have more than one link. If you
+forget, the error tells you the choices:
+`more than one relationship between "posts" and "users", use one of: users!reviewer_id, users!user_id`.
+
+**A table that points to itself** (`categories.parent_id -> categories`): the
+table name gives the children, the FK column gives the parent. The same keys
+work for `rel.*` writes (`categories: db.rel.create([...])`, `parent_id: db.rel.connect(id)`).
+
+```ts
+await db.from('categories').select('name, parent:parent_id(name), children:categories(name)').eq('name', 'go').single()
+// { name: 'go', parent: { name: 'tech' }, children: [{ name: 'generics' }] }
+```
+
+### Filtering, ordering and limiting inside a relation
+
+Use `relation.column` (the alias, if you gave one):
+
+```ts
+// filter the related rows only: every user is still returned
+await db.from('users').select('name, posts!user_id(title)')
+  .in('name', ['user_3', 'user_5']).eq('posts.published', false).order('name')
+// [{ name: 'user_3', posts: [] }, { name: 'user_5', posts: [{ title: 'user_5_post_2' }] }]
+
+// add !inner: users without a matching post are dropped too
+await db.from('users').select('name, posts!user_id!inner(title)')
+  .in('name', ['user_3', 'user_5']).eq('posts.published', false).order('name')
+// [{ name: 'user_5', posts: [{ title: 'user_5_post_2' }] }]
+
+// filter the main rows through a many-to-one relation (alias + !inner)
+await db.from('posts').select('title, author:users!user_id!inner(name)')
+  .eq('author.name', 'user_8').order('title')
+// [{ title: 'user_8_post_1', author: { name: 'user_8' } }, { title: 'user_8_post_2', author: { name: 'user_8' } }]
+```
+
+Order, limit and random inside a relation take `referencedTable`:
+
+```ts
+await db.from('users').select('name, posts!user_id(title)').eq('name', 'user_5')
+  .order('title', { ascending: false, referencedTable: 'posts' })
+  .limit(1, { referencedTable: 'posts' })
+  .single()
+// { name: 'user_5', posts: [{ title: 'user_5_post_2' }] }   newest-titled post only
+
+.random({ referencedTable: 'posts' }).limit(3, { referencedTable: 'posts' })  // 3 random posts per user
+```
+
+Deeper levels use dots: `.eq('posts.comments.body', 'x')`, `{ referencedTable: 'posts.comments' }`.
+
+---
+
+## Searching across 3+ tables
+
+Chain: `users` (1) ← `posts` (2) ← `comments` (3). Search comments for `user_5_post`:
+
+**A) Start from the table you search, go up to the parents.** Simplest.
+
+```ts
+await db.from('comments')
+  .select('body, post:posts(title, author:users!user_id(name))')
+  .ilike('body', '%user_5_post%')
+// [{ body: 'comment on user_5_post_1', post: { title: 'user_5_post_1', author: { name: 'user_5' } } }]
+```
+
+**B) Start from the top; show only what matched.** `!inner` at each level.
+
+```ts
+await db.from('users')
+  .select('name, posts!user_id!inner(title, comments!inner(body))')
+  .ilike('posts.comments.body', '%user_5_post%')
+// [{ name: 'user_5', posts: [{ title: 'user_5_post_1', comments: [{ body: 'comment on user_5_post_1' }] }] }]
+```
+
+**C) Find with a deep search, but show everything for the rows found.** Embed
+the same relation twice: one alias only for searching, one for showing.
+
+```ts
+await db.from('users')
+  .select('name, match:posts!user_id!inner(comments!inner(id)), posts!user_id(title, comments(body))')
+  .ilike('match.comments.body', '%user_5_post%')
+  .order('title', { referencedTable: 'posts' })
+// [{
+//   name: 'user_5',
+//   match: [ ... ],   // only used for the search; ignore it
+//   posts: [
+//     { title: 'user_5_post_1', comments: [{ body: 'comment on user_5_post_1' }] },
+//     { title: 'user_5_post_2', comments: [] },   // not matching, still shown
+//   ],
+// }]
+```
+
+| I want | Use |
+|---|---|
+| the matching deep rows, with their parents | A |
+| parents, showing only what matched | B |
+| parents found by a deep search, with all their data | C |
+
+---
+
+## Searching arrays
+
+Works on jsonb/json arrays (any element type) and Postgres arrays like `text[]`.
+For a column holding `["one", "two"]`:
+
+```ts
+.overlaps('scores', ['one', 'three'])            // has ANY of them         -> match
+.contains('scores', ['one', 'two'])              // has ALL of them         -> match
+.containedBy('scores', ['one', 'two', 'three'])  // has nothing else        -> match
+.eq('scores', ['one', 'two'])                    // exactly, same order     -> match
+.overlaps('meta->tags', ['red'])                 // an array inside a jsonb object
+```
+
+jsonb objects: `.contains('meta', { city: 'Dhaka', vip: true })` finds rows whose
+`meta` has those keys and values.
+
+---
+
+## Counting
+
+```ts
+const { data } = await db.from('users').count()                      // data: 100
+const { data } = await db.from('users').eq('active', true).count()   // data: 75
+
+// Supabase form: no rows, count only
+const { data, count } = await db.from('users').select('*', { count: 'exact', head: true }).eq('active', false)
+// data: null, count: 25
+
+// rows and the total together (for "page 1 of N")
+const { data, count } = await db.from('posts').select('*', { count: 'exact' }).range(0, 9)
+
+// per related row
+await db.from('users').select('name, posts!user_id(count)').in('name', ['user_3', 'user_5']).order('name')
+// [{ name: 'user_3', posts: [{ count: 0 }] }, { name: 'user_5', posts: [{ count: 2 }] }]
+```
+
+Filters on relations apply: `.eq('posts.published', true)` counts only published posts.
+
+## Aggregates and grouping
+
+One value over the matching rows; `data` is the value, or `null` when no rows match:
+
+```ts
+const { data: newest } = await db.from('posts').eq('user_id', id).max('created_at')
+await db.from('users').like('name', 'user\\_%').min('age')
+await db.from('users').sum('age')
+await db.from('users').avg('age')
+await db.from('users').count({ distinct: 'name' })   // count(DISTINCT name)
+```
+
+These take filters (and `.replica()`), and work as transaction steps.
+
+Per group, in `select()`: `count()`, `sum(col)`, `avg(col)`, `min(col)`, `max(col)`,
+`count(distinct col)`, each with an optional `name:` alias. Every plain column in the select must be in `groupBy()`,
+and `order()` can sort by an aggregate's name:
+
+```ts
+await db.from('users')
+  .select('team:meta->>team, n:count(), total:sum(age), oldest:max(age)', { count: 'exact' })
+  .groupBy('meta->>team')
+  .order('total', { ascending: false })
+// with the four users test/merge.test.ts adds (teams red: ages 10, 30; blue: 20, null):
+// data: [{ team: 'red', n: 2, total: 40, oldest: 30 }, { team: 'blue', n: 2, total: 20, oldest: 20 }]
+// count: 2 (groups)
+
+await db.from('users').select('count(), max(age)')        // [{ count: 100, max: ... }]: one row, no groupBy
+await db.from('posts').select('user_id').distinct()       // SELECT DISTINCT
+```
+
+Aggregates, `groupBy()` and `distinct()` don't combine with related tables in the
+same select. For `HAVING`, use `.having(db.raw('count(*) >= ?', [2]))` (see
+[Raw SQL fragments](#raw-sql-fragments)).
+
+---
+
+## Insert, update, delete
+
+Writes follow Postgres: every matching row is written. Add `.returning()` to get
+the written rows back, like SQL `RETURNING`.
+
+```ts
+await db.from('users').insert({ name, email })                    // data: null, count: 1
+await db.from('users').insert({ name, email }).returning()         // data: [{ id, name, email, ... }]
+await db.from('users').insert([row1, row2]).returning('id')        // data: [{ id }, { id }]
+
+await db.from('users').update({ name: 'New' }).eq('active', false)                     // count: rows changed
+await db.from('users').update({ age: db.ops.increment() }).eq('id', id).returning('age')  // [{ age: 31 }]
+
+await db.from('posts').delete().eq('user_id', id).returning('id')  // every deleted row
+```
+
+- `returning()` is **always an array**: one row is `[row]`, none is `[]`. It takes `'*'`
+  (the default) or column names; related tables are read with a normal `select()` afterwards.
+- Without `returning()`, `data` is `null` and `count` is the number of rows written
+  (Postgres' `INSERT 0 2` / `UPDATE 3` / `DELETE 1`).
+- `update()` and `delete()` need at least one filter, so a mistake can't change the whole table.
+- Writes take filters on their own table only. `select()`, `single()`, `order()`, `random()`,
+  `limit()` and `range()` are for reads.
+- `id`, `created_at`, `updated_at` come from the database; `updated_at` changes on every update.
+
+---
+
+## Changing jsonb and arrays
+
+Atomic: the change happens inside Postgres, so two requests at once don't overwrite each other.
+
+| Before | Update | After |
+|---|---|---|
+| `[1,2,3]` | `{ scores: db.ops.append(4) }` | `[1,2,3,4]` |
+| `[1,2,3]` | `{ scores: db.ops.append(4, 5) }` | `[1,2,3,4,5]` |
+| `[1,2,3]` | `{ scores: db.ops.append([4, 5]) }` | `[1,2,3,[4,5]]` (one element) |
+| `[1,2,3]` | `{ scores: db.ops.prepend(0) }` | `[0,1,2,3]` |
+| `[1,2,3]` | `{ scores: db.ops.remove(2) }` | `[1,3]` (every 2 removed) |
+| `[1,2,3]` | `{ scores: db.ops.set(9).at(0) }` | `[9,2,3]` |
+| `[1,2,3]` | `{ scores: db.ops.unset().at(0) }` | `[2,3]` |
+| `[1,2,3]` | `{ scores: [7, 8] }` | `[7,8]` (full replace) |
+| `{a:1}` | `{ meta: db.ops.merge({ b: 2 }) }` | `{a:1,b:2}` |
+| `{a:1}` | `{ meta: { b: 2 } }` | `{b:2}` (full replace) |
+| `{tags:['x']}` | `{ meta: db.ops.append('y').at('tags') }` | `{tags:['x','y']}` |
+| `{n:1}` | `{ meta: db.ops.increment(5).at('n') }` | `{n:6}` |
+| `{a:1,b:2}` | `{ meta: db.ops.unset().at('b') }` | `{a:1}` |
+
+Also:
+- **Postgres arrays** (`text[]`): `db.ops.append`, `db.ops.prepend`, `db.ops.remove`.
+- **Numbers**: `{ age: db.ops.increment() }`, `db.ops.increment(-1)`.
+- **Combining:** `update({ name: 'x', age: db.ops.increment(), scores: db.ops.append(4) })` changes all three in one statement.
+
+---
+
+## Upsert and find-or-create
+
+One row or many (up to 5,000 per call). `onConflict` columns need a unique constraint (default: the primary key).
+
+```ts
+// insert, or UPDATE the existing row with these values
+await db.from('users').upsert({ email, name }, { onConflict: 'email' }).returning()
+
+// find-or-create: insert, or return the existing row UNCHANGED
+const { data } = await db.from('users')
+  .upsert({ email, name }, { onConflict: 'email', ignoreDuplicates: true })
+  .returning('id')
+data[0].id  // returning() is always an array
+```
+
+Safe when many requests run at once: they all get the same row, with no duplicates and no errors.
+Unlike Supabase, `ignoreDuplicates` returns the existing row, so transaction steps can use it.
+
+### Choosing what changes: `merge`
+
+Without `merge`, an existing row gets every column you send (except the conflict key).
+With `merge`, only the listed columns change and the rest keep their stored value:
+
+| `merge` value | Existing row's column becomes |
+|---|---|
+| `'set'` | the incoming value |
+| `'add'` | stored + incoming (NULL counts as 0) |
+| `'append'` / `'prepend'` | stored and incoming jsonb or Postgres arrays joined |
+| `db.ops.increment(1)`, `db.ops.merge({...})`, ... | the operator applied to the stored value |
+
+```ts
+// counters per post, 2,000 rows at a time
+await db.from('posts_stats').upsert(batch, {
+  onConflict: 'post_id',
+  merge: { views: 'add', likes: 'add', last_viewer_email: 'set', last_viewer_id: 'set' },
+})
+
+// a new row is inserted as sent; an existing one gets name set and age + 1
+await db.from('users').upsert({ email, name, age: 0 }, { onConflict: 'email', merge: { name: 'set', age: db.ops.increment(1) } })
+
+merge: ['name', 'email']   // shorthand: 'set' for each
+```
+
+- Each conflict key may appear once per call; two rows with the same key are an error
+  (`upsert: rows 0 and 2 have the same email ["a"]; ...`). Combine them first.
+- A column with `'set'`, `'add'`, `'append'` or `'prepend'` must be in the rows; an
+  operator doesn't need to be.
+- For "set this only when ...", add an `update()` step with that filter in the same
+  transaction:
+
+```ts
+await db.transaction((tx) => [
+  tx.from('clients').upsert(row, { onConflict: 'user_name', merge: { subject: 'set', total_code_leads: tx.ops.increment(1) } }),
+  tx.from('clients').update({ total_sent: 100 }).eq('user_name', row.user_name).not('shared_email', 'is', null),
+])
+```
+
+---
+
+## Writing related rows
+
+Put `rel.*` under the related table's name (with `!hint` when needed). The whole
+`insert()`/`update()` runs in one transaction: if anything fails, nothing is saved.
+
+```ts
+await db.from('posts').insert({
+  title: 'Hello',
+  user_id: userId,
+  comments: db.rel.create([{ body: 'first', author_id: userId }]), // post_id filled in for you
+  labels: db.rel.connect([labelId]),                               // adds the post_labels row
+}).returning('id')
+
+await db.from('posts').update({
+  title: 'New title',
+  labels: db.rel.set([labelA, labelB]),                        // exactly these labels
+  comments: db.rel.update({ id: commentId }, { body: 'edited' }),
+}).eq('id', postId)
+```
+
+| | one-to-many (`comments`) | many-to-many (`labels`) | many-to-one (`'users!user_id'`) |
+|---|---|---|---|
+| `db.rel.create(rows)` | add children | create + link | create, set the FK |
+| `db.rel.upsert(row, { onConflict })` | add or update a child | upsert + link | upsert, set the FK |
+| `db.rel.connectOrCreate(row, { onConflict })` | find or create, move here | find or create + link | find or create, set the FK |
+| `db.rel.connect(keys)` | move children here | link | set the FK |
+| `db.rel.disconnect(keys)` | set child FK to null | unlink | set the FK to null |
+| `db.rel.set(keys)` | exactly these children | exactly these links | — |
+| `db.rel.update(match, values)` | update matching children | update matching linked rows | — |
+| `db.rel.delete(match?)` | delete matching children | delete matching linked rows | — |
+
+Created rows can contain `rel.*` themselves (any depth). `connect` with a key that
+doesn't exist fails and rolls everything back.
+
+---
+
+## Transactions
+
+Several steps, one transaction: all are saved, or none.
+
+**Named steps (an object).** The keys name the steps and become the keys of `data`:
+
+```ts
+const { data, error } = await db.transaction((tx) => ({
+  user: tx.from('users').upsert({ email, name }, { onConflict: 'email', ignoreDuplicates: true }).returning('id'),
+  post: tx.from('posts').upsert({ user_id: tx.ref('user.id'), title }, { onConflict: 'user_id,title', ignoreDuplicates: true }).returning('id'),
+  link: tx.from('post_labels').upsert({ post_id: tx.ref('post.id'), label_id }, { ignoreDuplicates: true }),
+  total: tx.from('posts').eq('user_id', tx.ref('user.id')).count(),
+}))
+data.user[0].id // found or created
+data.link       // null (no returning())
+data.total      // a number
+```
+
+**Array form,** naming steps with `.as()`; `data` is an array in the same order:
+
+```ts
+await db.transaction((tx) => [
+  tx.from('posts').insert({ title, user_id }).returning('id').as('post'),
+  tx.from('comments').update({ body: 'x' }).eq('post_id', tx.ref('post.id')),
+])
+```
+
+Rules:
+- Steps run top to bottom; `tx.ref('name.column')` reads an earlier step's row, in values or filters.
+  A step that returned one row (or `.single()`) is read as `name.column`; with several rows,
+  pick one: `tx.ref('posts.0.id')`.
+- Any step can be select, insert, upsert, update, delete or count, with `ops.*` and `rel.*`.
+- Return the steps; don't `await` them inside the callback.
+- Step names are words without dots. Number-like keys (`'1'`) are rejected because JavaScript reorders them.
+- On failure: `error.step` (0-based) and `error.stepName` say which step failed; every step is rolled back.
+
+---
+
+## Read replicas
+
+When the API server has read replicas (`REPLICA_URLS`), reads can use them.
+Reads use the primary unless you ask: a replica can be a moment behind, so a
+row you just wrote may not be there yet.
+
+```ts
+// one query
+await db.from('posts').select('title').eq('published', true).replica()
+
+// every read by default; primary() for a read that must see your own write
+const db = createClient(url, key, { readFrom: 'replica' })
+await db.from('users').insert({ name, email })
+await db.from('users').select().eq('email', email).primary()
+```
+
+- Only reads (`select()`, `count()`) use a replica. Writes and every step of
+  `transaction()` run on the primary; `.replica()` on them is an error.
+- Without a healthy replica (none configured, down, or behind by more than
+  `REPLICA_MAX_LAG`) the read runs on the primary instead, with no error. A read
+  that fails because the replica went away is retried on the primary.
+- With several replicas, each read goes to the one with the fewest busy connections.
+- The `X-Served-By` response header says who answered: `primary` or `replica-1`, `replica-2`, ...
+
+---
+
+## Raw SQL fragments
+
+When the builder has no method for it, `db.raw(sql, bindings?)` adds one SQL
+expression to the query (same as `import { raw }`, and `tx.raw` in
+transactions). It is knex's `whereRaw` / `orderByRaw` / `havingRaw` /
+`knex.raw`: a piece of a query, never a whole statement. `test/raw.test.ts`
+checks these against the test database.
+
+```ts
+const n = db.raw('substring(name from 6)::int')   // user_42 -> 42
+
+// where(): AND (<fragment>)
+await db.from('users').select('name').where(db.raw('substring(name from 6)::int <= ?', [3])).order('name')
+// [{ name: 'user_1' }, { name: 'user_2' }, { name: 'user_3' }]
+
+// inside or() / and() / not() it is one condition of the group
+await db.from('users').select('name')
+  .or((q) => q.where(db.raw('substring(name from 6)::int = ?', [1])).eq('name', 'user_2'))
+// user_1, user_2
+
+// array binding: = any(?)
+await db.from('users').select('name').where(db.raw('lower(trim(email)) = any(?)', [['user_1@example.com', 'user_7@example.com']]))
+
+// jsonb ? operator: \? (written '\\?' in JS) is a literal ?
+await db.from('users').where(db.raw('meta \\? ?', ['vip'])).count()          // 100
+
+// order()
+await db.from('users').select('name').order(n, { ascending: false }).limit(3)
+// user_100, user_99, user_98
+
+// select(): extra arguments are raw columns, each needs .as(name); options go last
+await db.from('users').select('name', db.raw('char_length(name)').as('name_len')).eq('name', 'user_42').single()
+// { name: 'user_42', name_len: 7 }
+
+// having(), with groupBy()
+await db.from('posts').select('user_id, n:count()').groupBy('user_id').having(db.raw('count(*) >= ?', [2]))
+// 33 groups, each n: 2
+```
+
+As values in `insert()` / `update()` / `upsert()` rows, and in upsert `merge`,
+where `excluded.col` is the incoming value and `table.col` the stored one:
+
+```ts
+await db.from('users').update({ age: db.raw('age + ?', [5]) }).eq('email', email).returning('age')   // 10 -> [{ age: 15 }]
+
+await db.from('users').upsert({ email, name: 'second', age: 5 }, {
+  onConflict: 'email',
+  merge: { age: db.raw('CASE WHEN excluded.age IS NOT NULL AND users.age IS NOT NULL THEN users.age + excluded.age ELSE ? END', [100]) },
+})
+// stored age 10 -> 15; name stays (only merge columns change); with age: null -> 100
+```
+
+Rules:
+
+- Each `?` is one binding, passed as a query parameter, so values are never
+  pasted into the SQL. The count must match `bindings`, else a 400 error
+  (`raw fragment: 2 placeholders but 1 binding`). Strings, numbers, booleans and
+  `null` pass through; an array becomes a Postgres array (cast it if needed:
+  `?::text[]`); an object becomes jsonb (`?::jsonb`). A `?` inside `'quoted
+  text'` is not a binding.
+- `\?` (in a JS string: `'\\?'`) is a literal `?`, for the jsonb `?` operator.
+- Fragments see the main table only: its columns, plain or qualified with the
+  table's name (`users.age`, `"users".age`), and `excluded.col` in `merge`.
+  Related tables are not visible, and `order(raw)` with `referencedTable` is an error.
+- The API key must be allowed to use raw fragments. Otherwise every request
+  (or transaction) that contains one gets 403, code `RAW_NOT_ALLOWED`.
+- The server rejects with 400, code `RAW_FRAGMENT`: `;`, `--` and `/*`
+  comments, dollar quoting (`$$`), the keywords `select`, `insert`, `update`,
+  `delete`, `with`, `union`, `into`, `copy`, `grant`, `drop`, `alter`,
+  `create`, `truncate`, `execute`, `do`, `call` outside quoted text, an empty
+  fragment or one over 2,000 characters, and more than 100 bindings.
+  Functions, `CASE WHEN`, casts, `interval '1 hour'`, operators, `count(*)`
+  and `excluded.x` are fine.
+- In the client, `raw()` throws when `sql` is not a non-empty string or
+  `bindings` not an array. `select()` with a raw column lacking `.as()`, and
+  `where()` / `having()` with something other than `raw()`, resolve to `{ error }`
+  without sending.
+
+Moving from knex:
+
+| knex | arn-db |
+|---|---|
+| `.whereRaw(sql, b)`, `.andWhereRaw(sql, b)` | `.where(db.raw(sql, b))` |
+| `.orWhereRaw(sql, b)` | `.or((q) => q.eq(...).where(db.raw(sql, b)))` |
+| `.orderByRaw(sql, b)` | `.order(db.raw(sql, b), { ascending, nullsFirst })` |
+| `.select('id', knex.raw('char_length(title) as n'))` | `.select('id', db.raw('char_length(title)').as('n'))` |
+| `{ total: knex.raw('total + ?', [1]) }` | `{ total: db.raw('total + ?', [1]) }` |
+| `.onConflict('email').merge({ total: knex.raw('…') })` | `.upsert(rows, { onConflict: 'email', merge: { total: db.raw('…') } })` |
+| `.havingRaw(sql, b)` | `.having(db.raw(sql, b))` |
+
+---
+
+## Errors
+
+`error` has `message`, and usually `code` and `details`:
+
+| `code` | Meaning | Example |
+|---|---|---|
+| `23505` | duplicate value in a unique column | email already used |
+| `23503` | foreign key: the referenced row doesn't exist | `db.rel.connect(unknownId)` |
+| `23502` | a required (NOT NULL) column is missing | insert without `body` |
+| `22P02` | value has the wrong format | `.eq('id', 'abc')` on a uuid |
+| `42703` | column doesn't exist | `select('nope')` → `column _t0.nope does not exist` (`_t0` is the main table) |
+| `42P10` | `onConflict` columns have no unique constraint | `upsert(…, { onConflict: 'title' })` |
+| `RAW_FRAGMENT` | (400) a `db.raw()` fragment the server refuses | `db.raw('1; drop table x')` |
+| `RAW_NOT_ALLOWED` | (403) the API key may not use raw fragments | |
+| `401` | missing or wrong API key | |
+| `403` | request came from a browser | |
+
+Only setup mistakes throw: `createClient()` without a key, `db.raw()` without a
+SQL string, and `db`'s first query when `ARN_DB_URL` or `ARN_DB_KEY` is missing.
+
+Errors without a code are checks done before the database runs anything, for
+example: `more than one relationship between "posts" and "users", use one of: users!reviewer_id, users!user_id`.
+
+---
+
+## Not supported yet
+
+- Sorting main rows by a related table's column (e.g. posts by author name). Sorting *inside* a relation works.
+- OR across tables in one group (e.g. `name = 'x' OR posts.published`): each `or()` group is on one table.
+- Full-text search and calling Postgres functions (`rpc`) as methods. Column
+  functions like `lower(trim(email))` and `having` work through
+  [raw fragments](#raw-sql-fragments).
+- `db.col()` across tables, and as a value in `insert()` / `update()`.