@supabase/lite 0.9.0 → 0.9.1-next.1

package/docs/compatibility.mdx

@@ -0,0 +1,115 @@
+---
+title: "Compatibility"
+description: "Capability-level support matrix for the Data API, Auth, Storage, RLS, Realtime, and Edge Functions across SQLite, PGlite, and Postgres."
+---
+
+import { Aside } from '@astrojs/starlight/components';
+
+Compatibility is measured against the `@supabase/supabase-js` surface: does code written for Supabase keep working when pointed at Supabase Lite. Direct Postgres wire-protocol access (`psql`, raw SQL clients) is not a target.
+
+<Aside type="note">
+This page is a capability-level rollup. The authoritative, per-method matrix ships in-package as `STATUS.md` (with effort/blocker detail in `FEATURES.md`) and updates every `npm install`. If you need an exact count for a specific method, check that file rather than this page.
+</Aside>
+
+## The backend axis
+
+Supabase Lite runs on two families of database backend, and support differs between them:
+
+- **SQLite** (`bun:sqlite`, `node:sqlite`, SQLite WASM, Cloudflare D1/DO): the primary, zero-dependency path. Most gaps below are SQLite-specific platform limits (no range types, no stored procedures, no native full-text ranking).
+- **PGlite / Postgres**: run the same Data API and Auth implementation against a real Postgres engine. Many features that are partial or unsupported on SQLite work natively here, since RLS, `rpc()`, ranges, and regex all fall back to real Postgres behavior.
+
+Switching backends is a config change (`driver = "pglite"` or `"postgres"` in `config.toml`), not a code change. See [Database backends](/database/backends) for setup.
+
+## Data API (PostgREST)
+
+CRUD, filtering, embedding, and RLS over your tables. This is the most complete surface: **53/74** `supabase-js` query-builder methods on SQLite, **72/74** on Postgres/PGlite.
+
+| Capability | SQLite | PGlite | Postgres | Coverage |
+|---|:---:|:---:|:---:|---|
+| Core CRUD (select/insert/update/delete/upsert) | ✅ | ✅ | ✅ | 6/6 on all backends |
+| Comparison filters (eq, gt, in, is, …) | ✅ | ✅ | ✅ | 10/10 on all backends |
+| Pattern matching (like/ilike + quantified) | ✅ | ✅ | ✅ | 6/6 on all backends |
+| Resource embedding (FK joins, `!inner`, spreads, nested, aggregates) | ✅ | ✅ | ✅ | 5/5 on all backends |
+| RLS enforcement | ✅ | ✅ | ✅ | App-layer rewrite on SQLite, native on Postgres/PGlite |
+| Array/JSON containment (`contains`, `containedBy`, `overlaps`) | ⚠️ | ✅ | ✅ | Scalar arrays + shallow objects only on SQLite |
+| Full-text search (fts/plfts/phfts/wfts) | ⚠️ | ✅ | ✅ | LIKE-based lexeme approximation on SQLite, not FTS5/tsvector |
+| Regex (`regexMatch`/`regexIMatch`) | ⚠️ | ✅ | ✅ | Simple anchored/literal patterns only on SQLite |
+| `schema()` (multi-schema) | ⚠️ | ✅ | ✅ | On `sqlite-postgres`, schema-qualified DDL is flattened into one namespace and `schema()`/`Accept-Profile` routing resolves, but there's no real namespace isolation; the bare `sqlite` driver has no schema handling |
+| Advanced postgres features (`rangeGt`, `rpc()`, `eq(any)`, …) | ❌ | ✅ | ✅ | No range types in SQLite. `geojson()` and `rollback()` are the only gaps on Postgres/PGlite. |
+| **Total** | **53/74** | **72/74** | **72/74** |  |
+
+## Auth (GoTrue)
+
+Email/password, OTP, sessions, RLS auth context, and OAuth sign-in with `github`/`google` are solid. Admin API, manual identity linking, other OAuth providers, and MFA are the main gaps, and behave the same regardless of database backend (Auth doesn't have a SQLite/Postgres split the way the Data API does). One exception: on the Cloudflare D1 backend, multi-statement Auth transaction spans (OAuth callback/token writes, email-change and other OTP verification) run best-effort without a wrapping transaction (D1 has no callback transaction API); single-statement guards still prevent auth-code/state reuse. All other backends, including Durable Objects, are fully transactional.
+
+| Capability | SQLite | PGlite | Postgres | Coverage |
+|---|:---:|:---:|:---:|---|
+| Email + password sign-up/sign-in | ✅ | ✅ | ✅ | |
+| Magic link / email OTP | ✅ | ✅ | ✅ | signup, magiclink, recovery, email_change, reauthentication |
+| JWT issuance, refresh rotation, sessions | ✅ | ✅ | ✅ | |
+| Password recovery / resend / reauthenticate | ✅ | ✅ | ✅ | |
+| RLS auth context (`auth.uid()`, `auth.role()`, `auth.jwt()`) | ✅ | ✅ | ✅ | Shared with the Data API |
+| API keys (`sb_publishable_*`/`sb_secret_*`) | ✅ | ✅ | ✅ | Enforced on `/rest/v1`/`/auth/v1` when configured; legacy JWT-as-apikey not supported |
+| OAuth / social sign-in | ⚠️ | ⚠️ | ⚠️ | `github`/`google` only; PKCE + implicit flows, automatic account linking. Other providers (incl. Apple) planned |
+| Anonymous sign-in | 🔄 | 🔄 | 🔄 | Planned |
+| Identity linking | ⚠️ | ⚠️ | ⚠️ | Automatic linking on OAuth sign-in works; manual `linkIdentity`/`unlinkIdentity` planned |
+| Admin user API | 🔄 | 🔄 | 🔄 | Planned |
+| MFA / TOTP / WebAuthn | ⚫ | ⚫ | ⚫ | Not planned |
+| **Total** | **13/63** | **13/63** | **13/63** | 13 backend endpoints implemented; 10 additional `supabase-js` methods are client-side only (N/A) |
+
+See [Auth overview](/auth/overview) and [Not supported](/auth/not-supported) for the full breakdown.
+
+## Storage
+
+Gated behind `EXPERIMENTAL_STORAGE`. CRUD, public buckets, signed URLs, and image transforms are done; role-based access control is the main gap.
+
+| Capability | SQLite | PGlite | Postgres | Coverage |
+|---|:---:|:---:|:---:|---|
+| Bucket CRUD | ✅ | ✅ | ✅ | |
+| Object CRUD (upload/download/list/move/copy/remove/info) | ✅ | ✅ | ✅ | |
+| Signed URLs (download, batch, upload) | ✅ | ✅ | ✅ | |
+| Image transforms (Sharp, Cloudflare) | ✅ | ✅ | ✅ | |
+| Storage backends (filesystem, S3-compatible) | ✅ | ✅ | ✅ | |
+| Role-based access (service_role/anon/authenticated gating) | ⚠️ | ⚠️ | ⚠️ | API keys now resolve roles for route-level checks; no per-object RLS yet |
+| RLS policies on storage objects | 🔄 | 🔄 | 🔄 | Planned |
+| **Total** | **20/20 methods** | **20/20 methods** | **20/20 methods** | Access control and `/status` health endpoint pending |
+
+See [Storage overview](/storage/overview) and [Storage limitations](/storage/limitations).
+
+## Row Level Security (RLS)
+
+RLS works across all backends but is enforced differently: SQLite rewrites the PostgREST query AST at the application layer, while PGlite/Postgres use native Postgres RLS.
+
+| Feature | SQLite | PGlite | Postgres |
+|---|:---:|:---:|:---:|
+| `ENABLE ROW LEVEL SECURITY`, `USING`, `WITH CHECK` | ✅ | ✅ | ✅ |
+| Permissive / restrictive policies, `FOR` command targeting, `TO role` | ✅ | ✅ | ✅ |
+| `auth.uid()` / `auth.jwt()` in policies | ✅ | ✅ | ✅ |
+| Subquery `WITH CHECK` on INSERT | ❌ | ✅ | ✅ |
+| `DEFAULT auth.uid()` on columns | ❌ | ✅ | ✅ |
+| Standalone `DROP POLICY` / `ALTER POLICY` | ✅ | ✅ | ✅ |
+
+See [Database: RLS](/database/rls) for the enforcement model and workarounds.
+
+## Realtime and Edge Functions
+
+Both are planned but not started: config schemas exist, no runtime yet.
+
+| Product | SQLite | PGlite | Postgres |
+|---|:---:|:---:|:---:|
+| Realtime | 🔄 | 🔄 | 🔄 |
+| Edge Functions | 🔄 | 🔄 | 🔄 |
+
+See [Realtime](/other/realtime) and [Edge Functions](/other/edge-functions) for the planned design.
+
+## Legend
+
+| Icon | Meaning |
+|---|---|
+| ✅ | Supported end-to-end |
+| ⚠️ | Partial, works with caveats |
+| 🔄 | Planned, not built yet |
+| ❌ | Not feasible on this path |
+| ⚫ | Not applicable |
+
+For the full Supabase feature list this compatibility matrix is measured against, see the [Supabase docs](https://supabase.com/docs).

package/docs/database/backends.mdx

@@ -0,0 +1,118 @@
+---
+title: "Backends"
+description: "SQLite drivers vs PGlite/Postgres: how Supabase Lite picks a database, and how to switch."
+---
+
+import { Tabs, TabItem } from '@astrojs/starlight/components';
+
+
+Supabase Lite runs on one of two database families. Which one you're on determines which parts of the Data API, RLS, and schema translation are fully available versus partial or missing. Every other page in this section links back here for "switch backend to get X."
+
+## The two families
+
+Two independent choices are in play. The **SQLite runtime binding** is auto-selected based on where your code runs; the **`driver`** value in `config.toml` picks how your schema DDL is interpreted.
+
+**SQLite backends** run in-process with zero external dependencies. The binding is automatic:
+
+| Runtime | SQLite binding | Selection |
+|---|---|---|
+| Bun | `bun:sqlite` | Automatic |
+| Node.js ≥ 22 | `node:sqlite` | Automatic |
+| Browser | `@sqlite.org/sqlite-wasm` | Automatic |
+| Cloudflare Workers + Durable Objects | workerd / D1 SQLite | `@supabase/lite/workerd` |
+
+On top of the binding, the `driver` value selects the DDL dialect:
+
+- **`sqlite-postgres` (the default)**: you write Postgres DDL in `schemas/*.sql` and Supabase Lite deparses it to SQLite. This is what `lite init` scaffolds, and what every "SQLite path" note in these docs assumes. It doubles as a compatibility check for moving to a real Postgres backend later, since your schema is authored as Postgres.
+- **`sqlite`**: you write raw SQLite DDL yourself, with no translation. This is a niche choice: reach for it only if you specifically want to hand-write SQLite and skip the Postgres layer. Postgres-only features that depend on the translator, including RLS policy parsing, are not available on this bare path.
+
+**Postgres backends** run real Postgres semantics, either embedded or networked:
+
+| Backend | `driver` | Notes |
+|---|---|---|
+| PGlite | `pglite` | In-process WASM Postgres. No separate server. |
+| Postgres | `postgres` | Remote/local Postgres over the `postgres` node driver. |
+
+## The trade-off
+
+**SQLite** is fast, has no external process to run, and works identically in Node, Bun, the browser, and Cloudflare Workers. The cost: no arrays, no range types, no regex engine, and no stored-procedure model. Concretely, on SQLite: `rpc()` doesn't work, range operators (`rangeGt`, etc.) and quantified comparisons (`eq(any)`, etc.) aren't implemented, `textSearch()` is a LIKE-based lexeme approximation rather than real FTS5/tsvector ranking, `regexMatch`/`regexIMatch` only handle simple anchored patterns, and columns can't default to `auth.uid()`. See [Data API divergences](/database/data-api) for the complete list.
+
+**PGlite and Postgres** run your schema as real Postgres. `rpc()`, range types, regex (`~`/`~*`), quantified comparisons, full-text search, and `DEFAULT auth.uid()` on columns all work exactly as they would on hosted Supabase. RLS is enforced natively by Postgres rather than emulated at the application layer. The cost is a slightly heavier runtime (PGlite ships a WASM Postgres build; Postgres requires a running server).
+
+
+## Selecting a backend
+
+Set `driver` and `url` under `[db]` in `supabase/config.toml`:
+
+<Tabs>
+<TabItem label="sqlite-postgres (default)">
+    ```toml
+    [db]
+    driver = "sqlite-postgres"
+    url = "file:./supabase/.temp/data.db"
+    ```
+  </TabItem>
+  <TabItem label="sqlite (raw DDL)">
+    ```toml
+    [db]
+    driver = "sqlite"
+    url = "file:./supabase/.temp/data.db"
+    ```
+  </TabItem>
+  <TabItem label="PGlite">
+    ```toml
+    [db]
+    driver = "pglite"
+    url = "file:./supabase/.temp/data"
+    ```
+  </TabItem>
+<TabItem label="Postgres">
+    ```toml
+    [db]
+    driver = "postgres"
+    url = "postgres://user:password@localhost:5432/postgres"
+    ```
+  </TabItem>
+</Tabs>
+
+`lite init --pglite` scaffolds a project preconfigured for PGlite instead of the default `sqlite-postgres`. Programmatically, pass the driver at connection time:
+
+```ts
+import { createConnection } from "@supabase/lite/sqlite"; // picks the SQLite driver per runtime
+// or
+import { createConnection } from "@supabase/lite/pglite";
+import { createConnection } from "@supabase/lite/postgres";
+```
+
+Postgres connections run with `TimeZone=UTC` by default so `timestamptz` rendering is deterministic regardless of the host's timezone. Override via the `postgresOptions.connection.TimeZone` connection option if you need a different session timezone.
+
+## libsql / Turso
+
+libsql is another SQLite binding, so the same SQLite feature set and [Data API divergences](/database/data-api) apply. Unlike the built-in bindings it is not auto-selected and has no `config.toml` `driver`: you construct the connection in code and pass it to `App`, the same connection-object pattern as [Cloudflare D1](/integrations/frameworks#cloudflare-workers). What it adds on top of local SQLite is remote and replicated databases:
+
+- **Local file / in-memory** — `url: "file:./data.db"` or `":memory:"`.
+- **Remote (Turso)** — a `libsql://` URL plus an `authToken`.
+- **Embedded replica** — a local `url` kept in sync from a `syncUrl` primary.
+
+```ts
+import { App } from "@supabase/lite";
+import { createLibsqlConnection } from "@supabase/lite/libsql";
+
+const connection = await createLibsqlConnection({
+  url: process.env.TURSO_DATABASE_URL,     // file:… | :memory: | libsql://…
+  authToken: process.env.TURSO_AUTH_TOKEN, // remote only
+  ddlDialect: "postgres",                  // or "sqlite" (see families above)
+});
+const app = new App({ connection });
+```
+
+`@libsql/client` is an optional peer dependency; install it alongside Supabase Lite. Every libsql client option (`authToken`, `syncUrl`, `encryptionKey`, `intMode`, …) is accepted on the config. Read more on [embedded usage](/integrations/embedded) and [official docs](https://docs.turso.tech).
+
+## Where this shows up elsewhere
+
+- [Data API divergences](/database/data-api): the exact filter/method gaps on SQLite, all resolved by switching backend.
+- [Row Level Security](/database/rls): SQLite enforces RLS in the application layer; PGlite/Postgres use native Postgres RLS.
+- [Postgres → SQLite translation](/database/postgres-sqlite-translation): only relevant on the SQLite path; PGlite/Postgres run your DDL unmodified.
+- [Functions & triggers](/database/functions-triggers): SQLite supports a PL/pgSQL trigger subset; PGlite/Postgres run full PL/pgSQL.
+
+For the underlying Supabase database concepts (connection pooling, extensions, the Postgres engine Supabase runs in production), see the [Supabase Database overview](https://supabase.com/docs/guides/database/overview).

package/docs/database/data-api.mdx

@@ -0,0 +1,90 @@
+---
+title: "Data API divergences"
+description: "Where the PostgREST-compatible Data API and supabase-js diverge on SQLite, and the workarounds."
+---
+import { Aside } from '@astrojs/starlight/components';
+
+Supabase Lite's Data API mirrors PostgREST closely enough that `@supabase/supabase-js` works unchanged for supported methods. This page lists what's unsupported, partial, and fully working, specifically on the SQLite path. Everything here works fully on PGlite and Postgres; see [Backends](/database/backends) to switch.
+
+For the base concepts (query builder chaining, the REST API shape, response formats), see the [Data API guide](https://supabase.com/docs/guides/api) and the [supabase-js reference](https://supabase.com/docs/reference/javascript/select).
+
+## Not supported on SQLite
+
+<Aside type="caution">
+These throw, no-op, or silently return wrong results on SQLite. Switch to `pglite` or `postgres` in `supabase/config.toml` to use them as-is, or apply the workaround below.
+</Aside>
+
+### `rpc()`
+
+Postgres RPC depends on stored procedures (`CREATE FUNCTION ... LANGUAGE sql/plpgsql`). SQLite has no stored-procedure model. Supabase Lite doesn't introduce a parallel JS-function registry to fake it.
+
+**Workaround**, in order of preference:
+1. Express the logic as a SQL view or trigger in `schemas/schema.sql`.
+2. Switch the driver to `pglite` or `postgres`: `rpc()` works there natively.
+3. Run a regular server endpoint (Hono, Express, a Next.js route handler, or Vite middleware) and call it directly from the client.
+
+### Embedded dotted-path filters
+
+`.eq('rel.col', value)` (filtering an embedded resource by one of its own columns) is not rewritten into the embedded subquery on SQLite. Results come back unfiltered or error.
+
+```ts
+// Not supported on SQLite:
+await client.from("trips").select("*, days(*)").eq("days.city", "Paris");
+
+// Workaround: pre-resolve matching ids, then filter the parent by FK column.
+const { data: days } = await client.from("days").select("trip_id").eq("city", "Paris");
+await client.from("trips").select("*, days(*)").in("id", days.map(d => d.trip_id));
+```
+
+### Range operators
+
+`rangeGt`, `rangeGte`, `rangeLt`, `rangeLte`, `rangeAdjacent`: SQLite has no range types, so there's nothing to compile these to. No workaround short of modeling the range as two columns and writing the comparison manually, or switching backends.
+
+### Quantified comparison operators
+
+`eq(any)` / `eq(all)`, `neq(any)` / `neq(all)`, and the `gt`/`gte`/`lt`/`lte` equivalents. Postgres compiles `col=eq(any).{1,2,3}` to `col = ANY(ARRAY[...])`; SQLite has no array type and no quantified form on scalars. Not implemented: use `.in()` for the `eq(any)` case, or switch backends for the general form.
+
+## Partial on SQLite
+
+### `schema()`
+
+Real Postgres multi-schema isn't available on SQLite, but it's not a flat no. On the `sqlite-postgres` driver, schema-qualified DDL is flattened into one physical namespace while PostgREST still records which schema each table came from, so `schema()` (the `Accept-Profile` header) routes correctly. There's no namespace isolation, and the bare `sqlite` driver has no schema handling at all. See [Schemas](/database/schemas).
+
+
+### `contains()` / `containedBy()` / `overlaps()`
+
+Scalar arrays and shallow objects with scalar values work (`tags=cs.{a,b}`, `meta=cs.{"theme":"dark"}`), matched via `json_each`/`json_extract`. What doesn't work: arrays of objects (`[{a:1}] @> [{a:1}]`) and nested objects in the filter value (`data=cs.{"user":{"id":1}}`), because `json_extract` returns the sub-value as JSON text, which doesn't compare equal to the JS-object bind. `cd`/`ov` also currently require array inputs.
+
+### `textSearch()` (all variants: `fts`, `plfts`, `phfts`, `wfts`)
+
+SQLite has no FTS5-backed tsvector equivalent wired up here. What runs instead is a LIKE-based lexeme approximation: the query is split into terms and matched with `LIKE`, not real ranking or stemming. Phrase (`plfts`) and websearch (`wfts`) variants are parsed into the same lexeme approximation. Language/dictionary variants and computed-column FTS are limited. Good enough for basic "contains these words" search; not a substitute for Postgres full-text search.
+
+### `regexMatch()` / `regexIMatch()`
+
+Only simple anchored or literal patterns translate: `^foo`, `bar$`, `^exact$`, plain substrings. These become SQLite `GLOB` (case-sensitive) or `LIKE` (case-insensitive). Character classes, quantifiers, and alternation are not supported: the pattern either matches the simple-case translator or it doesn't get evaluated correctly.
+
+### `explain()`
+
+Returns the compiled SQL via `application/vnd.pgrst.plan` on both SQLite and Postgres, but real query-plan output (row estimates, actual timing) isn't surfaced on either dialect yet.
+
+## Fully works (all backends)
+
+- All CRUD: `from`, `select`, `insert`, `update`, `delete`, `upsert`, with `RETURNING`.
+- All comparison filters: `eq`, `neq`, `gt`, `gte`, `lt`, `lte`, `in`, `notIn`, `is`, `isDistinct`.
+- All pattern-matching filters: `like`, `ilike`, `likeAllOf`, `likeAnyOf`, `ilikeAllOf`, `ilikeAnyOf`.
+- Advanced filters: `match`, `or`, `not`, `filter`.
+- Transforms: `order`, `limit`, `range`, `single`, `maybeSingle`.
+- Resource embedding: foreign-key joins (auto-resolved from introspection), `!inner`, spreads (`...`), nested multi-level embeds, and aggregates (`count`, `sum`, `avg`, `min`, `max`).
+- Response/utility methods: `csv()`, `abortSignal()`, `setHeader()`, `throwOnError()`, `maxAffected()`.
+
+`geojson()` is not implemented on either backend (requires SpatiaLite or PostGIS, not wired up). `rollback()` is a PostgREST-specific method not implemented on either backend. `returns()` and `overrideTypes()` are TypeScript-only and need no backend support.
+
+<Aside type="note">
+Custom media handlers, computed columns backed by PG function metadata, and `SET LOCAL role` / JWT-driven role switching are known gaps that show up in the upstream PostgREST spec suite rather than the `supabase-js` surface. See the skip breakdown in the package's `STATUS.md`.
+</Aside>
+
+## See also
+
+- [Backends](/database/backends): how to switch driver to get full parity for anything listed above.
+- [Row Level Security](/database/rls): filter-adjacent, but its own set of SQLite caveats.
+- [Compatibility](/compatibility): capability rollup across all services.

package/docs/database/functions-triggers.mdx

@@ -0,0 +1,93 @@
+---
+title: "Functions & triggers"
+description: "The PL/pgSQL trigger subset supported on SQLite, and what runs unmodified on Postgres backends."
+---
+
+import { Aside } from '@astrojs/starlight/components';
+
+
+Supabase database functions and triggers are ordinary Postgres features: `CREATE FUNCTION ... LANGUAGE plpgsql` plus `CREATE TRIGGER`. On the SQLite path, Supabase Lite doesn't run PL/pgSQL: it translates a supported subset of trigger function bodies into inline SQLite `CREATE TRIGGER` statements at DDL-translation time. On PGlite/Postgres, full PL/pgSQL runs unmodified. See the [Supabase database functions guide](https://supabase.com/docs/guides/database/functions) and [triggers guide](https://supabase.com/docs/guides/database/postgres/triggers) for the base concepts.
+
+<Aside type="caution">
+Only **trigger functions** (`RETURNS TRIGGER`) are translated on SQLite. Standalone/non-trigger functions and `rpc()` calls into them are not supported there. See [Data API divergences](/database/data-api#not-supported-on-sqlite).
+</Aside>
+
+## How it works
+
+Postgres trigger functions are parsed and stored in a registry. When the corresponding `CREATE TRIGGER` statement is reached, the function body is inlined directly into a SQLite `CREATE TRIGGER`. `SECURITY DEFINER` is silently ignored (SQLite has no privilege model to apply it to).
+
+## Supported statement subset (SQLite)
+
+| Statement | Example | SQLite translation |
+|---|---|---|
+| `NEW.col = expr` | `NEW.updated_at = now()` | `UPDATE table SET updated_at = datetime('now') WHERE rowid = NEW.rowid` |
+| `NEW.col := expr` | `NEW.name := upper(NEW.name)` | Same as above |
+| `INSERT INTO ...` | `INSERT INTO profiles (id) VALUES (NEW.id)` | Passed through inside the trigger body |
+| `UPDATE ...` / `DELETE ...` | Any DML | Passed through inside the trigger body |
+| `RETURN NEW` / `RETURN OLD` | Required in Postgres | Not emitted, implicit in SQLite |
+
+Multiple `NEW.col = expr` assignments in the same function are merged into a single `UPDATE ... SET` statement.
+
+**Trigger options supported:** `BEFORE`/`AFTER` timing, `INSERT`/`UPDATE`/`DELETE` events and combinations, `UPDATE OF col1, col2`, `FOR EACH ROW`.
+
+## Not supported on SQLite
+
+These throw a descriptive error rather than silently dropping:
+
+- `DECLARE` (variable declarations)
+- `IF` / `ELSIF` / `ELSE`
+- `LOOP` (and other iteration constructs)
+- `RAISE`
+- `PERFORM`
+- `SELECT INTO`
+- `EXECUTE`
+- Local variables in general
+- Non-trigger (standalone) functions
+
+If your trigger body needs any of these, either restructure it into the supported subset (see the recipes below), or switch to a Postgres backend where full PL/pgSQL runs. See [Backends](/database/backends).
+
+## Recipes
+
+### `updated_at` timestamp via trigger
+
+```sql
+create or replace function set_updated_at() returns trigger language plpgsql as $$
+begin
+  new.updated_at = now();
+  return new;
+end;
+$$;
+
+create trigger set_<thing>_updated_at
+before update on <thing>
+for each row execute function set_updated_at();
+```
+
+The translator inlines `NEW.updated_at = now()` into a SQLite `UPDATE ... SET updated_at = datetime('now')` trigger body.
+
+### Profile row on signup (`handle_new_user`)
+
+```sql
+create or replace function handle_new_user() returns trigger language plpgsql as $$
+begin
+  insert into public.profiles (id, email) values (new.id, new.email);
+  return new;
+end;
+$$;
+
+create trigger on_auth_user_created
+after insert on auth.users
+for each row execute function handle_new_user();
+```
+
+Supported on all backends: the function body is a single `INSERT`, which passes through unmodified on SQLite and runs as ordinary PL/pgSQL on PGlite/Postgres.
+
+## On Postgres backends
+
+PGlite and Postgres run the trigger function bodies exactly as written. `DECLARE`, `IF`/`ELSIF`/`ELSE`, `LOOP`, `RAISE`, `PERFORM`, `SELECT INTO`, `EXECUTE`, and standalone functions all work with no restrictions, since it's real PL/pgSQL executed by real Postgres.
+
+## See also
+
+- [Postgres → SQLite translation](/database/postgres-sqlite-translation): the broader DDL translation mechanism triggers are part of.
+- [Data API divergences](/database/data-api): why `rpc()` (calling standalone functions from the client) isn't available on SQLite.
+- [Backends](/database/backends): switch to `pglite`/`postgres` for full PL/pgSQL support.

package/docs/database/migrations.mdx

@@ -0,0 +1,93 @@
+---
+title: "Migrations"
+description: "lite migration and lite db commands, the declarative diff flow, and how they differ from supabase db."
+---
+
+import { Tabs, TabItem } from '@astrojs/starlight/components';
+
+Supabase Lite supports both declarative schemas (`supabase/schemas/*.sql`) and imperative migrations (`supabase/migrations/*.sql`), the same two workflows Supabase supports. Migration files use the same filename format as the Supabase CLI (`<14-digit-timestamp>_<name>.sql`) and the same history table (`supabase_migrations.schema_migrations`), so migration files are portable between the two. See the [Supabase migrations guide](https://supabase.com/docs/guides/deployment/database-migrations) for the base concepts.
+
+## Commands
+
+<Tabs>
+  <TabItem label="migration group">
+    | Command | Description |
+    |---|---|
+    | `lite migration new <name>` | Create an empty migration file in `supabase/migrations/` |
+    | `lite migration up` | Apply pending migrations (`--dry-run` lists without applying) |
+    | `lite migration list` | Show applied vs pending migrations |
+
+    `migration down`, `migration repair`, `migration squash`, and `migration fetch` are not registered (🔄 planned).
+  </TabItem>
+  <TabItem label="db group">
+    | Command | Description |
+    |---|---|
+    | `lite db diff` | `--local` semantics; `-f <name>` emits a pg-DDL migration from the declarative schema diff |
+    | `lite db query "<sql>"` | Run a SQL statement against the local DB (renamed from top-level `exec`; supports `--remote`, `--config`) |
+    | `lite db translate "<sql>"` | Translate Postgres SQL to the backend dialect (arg or stdin); pipe into `lite db query` to apply |
+    | `lite db schema` | `[lite]`-only: print current DB schema; `--diff` compares vs `schemas/*.sql`, `--sql` prints raw `CREATE` statements |
+    | `lite db reset` | Drop everything, replay migrations, run seed. Does **not** apply declarative `schema_paths`. |
+
+    `db push`, `db pull`, `db dump`, `db lint`, `db advisors`, and `db start` are not registered.
+  </TabItem>
+</Tabs>
+
+```bash
+lite migration new add_users        # supabase/migrations/<ts>_add_users.sql
+# ... edit the file ...
+lite migration up                    # apply pending migrations
+lite migration list                  # show applied vs pending
+lite db diff -f tweak                # diff schemas/ against applied migrations, emit a new pg-DDL migration
+lite migration up                    # apply the newly emitted migration
+lite db reset                        # drop everything, replay migrations, run seed
+cat supabase/seed.sql | lite db translate | lite db query   # translate + run ad-hoc SQL
+```
+
+## The declarative diff flow
+
+1. Edit `supabase/schemas/schema.sql` (or the files listed in `[db.migrations].schema_paths`).
+2. Run `lite db diff -f <name>` to compare the live database against the declarative files.
+3. Supabase Lite emits a new migration file under `supabase/migrations/` containing the Postgres DDL needed to close the gap — occasionally more than one, see below.
+4. `lite migration up` applies it (or `lite dev` applies pending migrations automatically on boot, then re-runs the declarative diff).
+
+### When a diff emits more than one file
+
+A new enum value is unusable until the transaction that added it commits, and each migration file is applied in its own transaction. So exactly two shapes split into `<name>_1.sql`, `<name>_2.sql`, … — a split numbers every file, so there is no unsuffixed file in the set:
+
+- **Adding an enum value and using it in the same diff** — e.g. adding `'archived'` to a status enum and a column defaulting to `'archived'`. The `ALTER TYPE` goes in the first file, everything that uses the new value in the second.
+- **Adding more than one value to the same enum in one diff** — one file per added value. Each statement is anchored on the previous value (`ADD VALUE 'c' AFTER 'b'`), so it references a value that isn't visible until the transaction that added it commits.
+
+Unrelated changes in the same diff do not cause a split: they are ordered ahead of the `ALTER TYPE` and stay in the first file. Nothing else splits — multi-column type changes, added constraints, and view rebuilds all apply in a single transaction.
+
+Migrations and declarative schemas coexist: `lite dev` and the Vite plugin apply pending migrations on boot, then run the declarative diff against `schemas/*.sql`. RLS policies authored directly in migration files are picked up at request time, same as policies from the declarative schema.
+
+Destructive deltas (dropped columns/tables, incompatible type changes) aren't auto-emitted: `lite db diff` errors on data-loss rather than generating a lossy migration, and you author those by hand, matching how Supabase's own declarative diff behaves.
+
+## Which DDL dialect to write
+
+- On `sqlite-postgres`, `pglite`, and `postgres` drivers: write raw Postgres DDL in `supabase/migrations/*.sql`. The runtime translates it on the fly; see [Postgres → SQLite translation](/database/postgres-sqlite-translation).
+- On the bare `sqlite` driver: write SQLite DDL directly in `supabase/sqlite-migrations/*.sql` instead. No translation happens on this path.
+
+## How this differs from `supabase db`
+
+Supabase Lite's CLI aligns to the upstream `supabase` CLI's command shape (currently tracking v2.98.2), but several `db` subcommands aren't registered because they depend on infrastructure Supabase Lite doesn't have (a separate Postgres container, a linked hosted project with a dashboard, `pg_dump`):
+
+| Upstream command | Status in Supabase Lite |
+|---|---|
+| `db push` | Not registered; use `lite cloud deploy` instead |
+| `db pull` | Not registered |
+| `db dump` | Not registered |
+| `db lint` | Not registered |
+| `db advisors` | Not registered |
+| `db start` | Not applicable: Supabase Lite is in-process, no separate DB container to start |
+| `migration down` / `repair` / `squash` / `fetch` | Not registered (planned) |
+
+`config push` (pushing `config.toml` to a linked project) is folded into `lite cloud deploy` rather than split out as its own `config` group, until that's worth separating.
+
+See [CLI overview](/cli/overview) for the full command reference, including the `cloud` group that replaces some of the management-API surface upstream `supabase` exposes.
+
+## See also
+
+- [Declarative schemas](/database/schemas): what to write in `supabase/schemas/*.sql`.
+- [Postgres → SQLite translation](/database/postgres-sqlite-translation): the DDL translation mechanism migrations rely on.
+- [CLI overview](/cli/overview): the full `lite` command reference.

package/docs/database/overview.mdx

@@ -0,0 +1,66 @@
+---
+title: "Database overview"
+description: "How Supabase Lite's Postgres-shaped Data API maps onto SQLite, PGlite, and Postgres."
+---
+
+import { Aside, Card, CardGrid } from '@astrojs/starlight/components';
+
+
+Supabase Lite ships a PostgREST-compatible Data API in front of whichever database backend you configure. You write Postgres DDL and call `@supabase/supabase-js` exactly as you would against Supabase; the divergence is in what each backend can execute underneath.
+
+Two dimensions matter for every feature on this page:
+
+- **Which backend you're on.** SQLite (via `bun:sqlite`, `node:sqlite`, `@sqlite.org/sqlite-wasm`, or Cloudflare D1/DO) is the default, zero-dependency path. PGlite and Postgres are full-parity alternatives selected in `supabase/config.toml`. See [Backends](/database/backends).
+- **Which capability you're using.** Core CRUD, comparison/pattern filters, resource embedding, transforms, and RLS all work the same on every backend. `rpc()`, range types, quantified comparisons, real full-text search, and regex are Postgres/PGlite-only.
+
+<Aside type="note">
+Counts and per-method status live in the package's own `STATUS.md` and update on every `npm install`. This page and its siblings describe the shape of the divergence, not exact totals. See [Compatibility](/compatibility) for the rollup.
+</Aside>
+
+## What holds across every backend
+
+- Full CRUD (`select`, `insert`, `update`, `delete`, `upsert`) with `RETURNING`.
+- All comparison filters (`eq`, `neq`, `gt`, `gte`, `lt`, `lte`, `in`, `notIn`, `is`, `isDistinct`) and all pattern-matching filters (`like`, `ilike`, and their quantified `AllOf`/`AnyOf` forms).
+- Resource embedding: foreign-key joins, `!inner`, spreads, nested embeds, and aggregates (`count`, `sum`, `avg`, `min`, `max`).
+- Transforms: `order`, `limit`, `range`, `single`, `maybeSingle`.
+- Row Level Security: default-deny, `USING`/`WITH CHECK`, permissive/restrictive policies, per-command targeting, role targeting, `auth.uid()`/`auth.jwt()`.
+
+## Where it splits by backend
+
+SQLite has no arrays, ranges, regex engine, or stored-procedure model, so a handful of `supabase-js` methods either don't exist there or run in a reduced form: `rpc()`, embedded dotted-path filters, range operators, quantified comparisons, real full-text search, and regex matching. See [Data API divergences](/database/data-api) for the full list and workarounds.
+
+Schema authoring, migrations, and RLS enforcement also have SQLite-specific mechanics worth knowing before you hit them in production:
+
+- [Postgres → SQLite translation](/database/postgres-sqlite-translation): how DDL gets rewritten, which column defaults are honored, and the exact error you'll see for unsupported `CHECK`/`DEFAULT` functions.
+- [Row Level Security](/database/rls): works on every backend, but SQLite enforces it at the application layer with specific gaps (`WITH CHECK` subqueries, `DEFAULT auth.uid()`).
+- [Declarative schemas](/database/schemas) and [migrations](/database/migrations): the same `supabase/schemas/*.sql` and `supabase/migrations/*.sql` workflow as Supabase, with SQLite's single-namespace constraint.
+- [Functions & triggers](/database/functions-triggers): a supported subset of PL/pgSQL trigger bodies on SQLite; full PL/pgSQL on Postgres backends.
+
+For the parts of Supabase's database story that behave identically here (the general architecture, product terminology, and Postgres fundamentals), see the [Supabase Database overview](https://supabase.com/docs/guides/database/overview). This site only documents where Supabase Lite diverges.
+
+<CardGrid>
+  <Card title="Backends">
+    SQLite drivers vs PGlite/Postgres: how to pick, how to switch. [Read more →](/database/backends/)
+  </Card>
+  <Card title="Data API divergences">
+    What's unsupported, partial, and fully working on SQLite vs Postgres. [Read more →](/database/data-api/)
+  </Card>
+  <Card title="Row Level Security">
+    Enforcement model per backend and SQLite-specific caveats. [Read more →](/database/rls/)
+  </Card>
+  <Card title="Declarative schemas">
+    Writing Postgres DDL in `supabase/schemas/*.sql`. [Read more →](/database/schemas/)
+  </Card>
+  <Card title="Migrations">
+    `lite migration` / `lite db` commands vs upstream `supabase db`. [Read more →](/database/migrations/)
+  </Card>
+  <Card title="Functions & triggers">
+    The PL/pgSQL trigger subset supported on SQLite. [Read more →](/database/functions-triggers/)
+  </Card>
+  <Card title="Postgres → SQLite translation">
+    The DDL translation mechanism, defaults, and CHECK constraint rules. [Read more →](/database/postgres-sqlite-translation/)
+  </Card>
+  <Card title="Compatibility">
+    Full capability rollup across services. [Read more →](/compatibility/)
+  </Card>
+</CardGrid>