@supabase/lite 0.9.0 → 0.9.1-next.2

package/docs/database/postgres-sqlite-translation.mdx

@@ -0,0 +1,130 @@
+---
+title: "Postgres → SQLite translation"
+description: "How Supabase Lite auto-translates Postgres DDL to SQLite, and the exact errors you'll see when something isn't supported."
+---
+
+import { Aside } from '@astrojs/starlight/components';
+
+On the SQLite path, every SQL schema you write in `supabase/schemas/*.sql` or `supabase/migrations/*.sql` is Postgres DDL. Supabase Lite's translator (an extension of the Postgres deparser) rewrites it to SQLite on the fly at migration time: 1:1-compatible syntax passes through unchanged, constructs with a SQLite equivalent get rewritten (`SERIAL` → `INTEGER PRIMARY KEY AUTOINCREMENT`, `NOW()` → `datetime('now')`), Postgres-only decorators and privilege metadata (storage parameters, locking clauses, grants, `OWNER TO`) are silently dropped, and constructs with no SQLite counterpart (`LATERAL` joins, table inheritance, function grants) throw a descriptive error at translation time. This page is the reference for debugging translation-time surprises. It does not apply to PGlite/Postgres: those run your DDL as real Postgres, unmodified.
+
+The full auto-generated 74-entry compatibility table ships in the package at `app/POSTGRES-SQLITE-COMPAT.md`. This page covers the parts you're most likely to hit: extensions, type mapping, column defaults, and `CHECK` constraint functions.
+
+## Example translation
+
+```sql
+-- Postgres DDL
+CREATE TABLE users (
+   id         SERIAL PRIMARY KEY,
+   email      VARCHAR(255) UNIQUE NOT NULL,
+   is_active  BOOLEAN DEFAULT true,
+   tags       TEXT[],
+   metadata   JSONB,
+   created_at TIMESTAMP DEFAULT NOW()
+);
+```
+
+```sql
+-- Translated to SQLite
+CREATE TABLE users (
+   id         INTEGER PRIMARY KEY AUTOINCREMENT,
+   email      TEXT UNIQUE NOT NULL CHECK (length(email) <= 255),
+   is_active  INTEGER DEFAULT true CHECK (is_active IN (0, 1)),
+   tags       TEXT CHECK (tags IS NULL OR (json_valid(tags) AND json_type(tags) = 'array')),
+   metadata   TEXT CHECK (metadata IS NULL OR json_valid(metadata)),
+   created_at TEXT DEFAULT (datetime('now')) CHECK (created_at IS NULL OR datetime(created_at) IS NOT NULL)
+) STRICT;
+```
+
+## Extensions
+
+On SQLite, `CREATE EXTENSION` is accepted only for `plpgsql`, `pgcrypto`, and `uuid-ossp`, and those declarations are removed from the translated DDL. The `plpgsql` declaration supports `pg_dump` schema prologues; PL/pgSQL support remains limited to [trigger functions that the translator can inline](/database/functions-triggers/). The UUID declarations support `gen_random_uuid()` and `uuid_generate_v4()` defaults, but no other extension APIs are provided. Creation modifiers such as `IF NOT EXISTS`, `WITH SCHEMA`, `VERSION`, and `CASCADE` are accepted for those three exact names; quoted names are case-sensitive.
+
+`ALTER EXTENSION <accepted-name> SET SCHEMA ...` and `DROP EXTENSION` containing only accepted names are also removed so declarative `db diff` migrations can reconcile extension metadata. Every other create, update, member change, schema move, or drop fails during translation before the migration executes. PGlite and PostgreSQL run extension statements natively instead; see [Supabase's extension guide](https://supabase.com/docs/guides/database/extensions) for the native behavior.
+
+## Type mapping
+
+| Postgres type / syntax | SQLite storage | Notes |
+|---|---|---|
+| `int2`, `smallint`, `int4`, `integer`, `int`, `int8`, `bigint` | `INTEGER` | |
+| `serial`, `bigserial`, `smallserial` (and `serial2`/`4`/`8`) | `INTEGER` | Primary keys become `INTEGER PRIMARY KEY AUTOINCREMENT` |
+| `float4`, `real`, `float8`, `double precision` | `REAL` | |
+| `numeric`, `decimal` | `REAL` | Precision/scale emits a portable `CHECK` |
+| `text`, `varchar(n)`, `char(n)`, `bpchar` | `TEXT` | Length-constrained forms emit `length(...) <= n` |
+| `name` | `TEXT` | 63-character length check |
+| `bytea` | `BLOB` | |
+| `bool`, `boolean` | `INTEGER` | `0`/`1` with `CHECK (... IN (0, 1))` |
+| `date` | `TEXT` | `date(...) IS NOT NULL` validation |
+| `time`, `timetz` | `TEXT` | `time(...) IS NOT NULL` validation |
+| `timestamp`, `timestamptz` | `TEXT` | `datetime(...) IS NOT NULL` validation |
+| `interval` | `TEXT` | Stored as text; interval arithmetic is not emulated |
+| `json`, `jsonb` | `TEXT` | `json_valid(...)` check |
+| `uuid` | `TEXT` | Validates shape, normalizes to lowercase |
+| `inet` | `TEXT` | Validates IPv4/IPv6 with optional CIDR prefix |
+| `CREATE TYPE ... AS ENUM` | `TEXT` | `CHECK (... IN (...))` of allowed values |
+| `<type>[]` / `_type` arrays | `TEXT` | JSON array storage |
+
+**Not supported at all:** `oid`, `xid`, `xid8`, `cid`, `money`, `citext`, `cidr`, `macaddr`, `macaddr8`, `bit`/`bit varying`/`varbit`, geometric types (`point`, `line`, `lseg`, `box`, `path`, `polygon`, `circle`), `xml`, text-search types (`tsvector`, `tsquery`), range and multirange types, `reg*` catalog reference types, and internal/pseudo/handler types.
+
+<Aside type="note">
+On the Postgres path, columns typed as a domain with a `CAST(<domain> AS json)` (PostgREST "data representations") render through that cast on read and `RETURNING`. On SQLite, the known representation types (`color`, `unixtz`, `isodate`, `monetary`, `bytea_b64`) are handled by built-in field shims instead. See the full domain-formatting notes in the package's `STATUS.md` under "Translated Field Types" if you're using custom domains.
+</Aside>
+
+## Column defaults
+
+Only constant expressions and a small allow-list of functions are honored in `DEFAULT` clauses. Everything else fails at translation time.
+
+**Honored:**
+
+| Default expression | SQLite emission |
+|---|---|
+| Literals (`'pending'`, `true`, `0`, `NULL`) | As-is (booleans map to `0`/`1`) |
+| `gen_random_uuid()`, `uuid_generate_v4()` | Inline `randomblob`-based UUID expression (RFC 4122 v4 shape) |
+| `now()`, `current_timestamp` | `datetime('now')` |
+| `current_date` | `date('now')` |
+| `current_time` | `time('now')` |
+| `random()` | `random()` |
+
+**Not honored**: fails with `Function call "<name>" not supported`:
+
+- `auth.uid()`, `auth.role()`, `auth.email()`, `auth.jwt()`: these read JWT claims and have no SQLite equivalent as a column default. (They *do* work inside RLS `USING`/`WITH CHECK`, where they're rewritten on the AST instead of evaluated as a scalar default; see [Row Level Security](/database/rls).)
+- `nextval(...)`, `currval(...)`: sequences aren't modeled on SQLite.
+- `clock_timestamp()`, `statement_timestamp()`, `txid_current()`, and other volatile catalog functions.
+- Any user-defined function, or any function not in the allow-list above.
+
+**Workaround for `default auth.uid()`:** drop the default, pass `user_id` from the client on insert, and enforce ownership with a `WITH CHECK` policy instead:
+
+```sql
+-- Instead of:
+user_id uuid not null default auth.uid() references auth.users (id),
+
+-- Use:
+user_id uuid not null references auth.users (id),
+-- and rely on a WITH CHECK policy to bind the row to the caller.
+```
+
+This limitation is SQLite-only. On PGlite/Postgres, `auth.uid()` works as a column default natively: the function is bootstrapped as part of connection setup.
+
+## CHECK constraint functions
+
+`CHECK (...)` expressions are passed to SQLite as-is and evaluated by SQLite itself at write time. Only functions SQLite recognizes as valid are allowed. Postgres-only scalars commonly reached for in `CHECK` are rejected by the translator with the same `Function call "<name>" not supported` error:
+
+- `trim`, `btrim`, `ltrim`, `rtrim`: use a literal/operator comparison instead, or move the validation to the app layer.
+- `length` (on text): SQLite has `length()`, but the translator currently rejects it specifically inside `CHECK`.
+- `lower`, `upper`: same story, these work in `WHERE` but not currently inside `CHECK`.
+- Any custom function or extension scalar (`regexp_replace`, etc.).
+
+**Workaround:** keep `CHECK` constraints to literal/operator comparisons (`col <> ''` is fine, `length(col) > 0` is not) and validate richer rules in the app layer or via an RLS `WITH CHECK` predicate.
+
+On the PGlite/Postgres path, all of these functions work exactly as they do in upstream Postgres, since `CHECK` constraints run as real Postgres expressions there.
+
+## SQLite version floor
+
+Introspection (the schema snapshot query that runs on every request) uses `ORDER BY` inside an aggregate (`json_group_array(x ORDER BY y)`), which requires **SQLite 3.44.0 or newer**. Below that, every `select`/`insert`/`update`/`delete` fails with `near "ORDER": syntax error`, not just migrations. `node:sqlite`, `bun:sqlite`, and the Cloudflare workerd target all meet this floor on current releases; the one historical hazard is Bun 1.1.x, which shipped SQLite 3.43.2 (below the floor) before Bun 1.3.x moved to 3.51.0.
+
+## See also
+
+- [Row Level Security](/database/rls): how `CREATE POLICY` and `ENABLE ROW LEVEL SECURITY` DDL are extracted rather than emitted as SQLite DDL.
+- [Functions & triggers](/database/functions-triggers): the trigger-function-body translation this page's DDL translator feeds into.
+- [Backends](/database/backends): none of this applies on PGlite/Postgres, your DDL runs unmodified there.
+- [Supabase declarative schemas](https://supabase.com/docs/guides/local-development/declarative-database-schemas): the upstream workflow this DDL is authored for before translation.
+- [Postgres data types](https://www.postgresql.org/docs/current/datatype.html): the upstream reference for every type mapped above.

package/docs/database/rls.mdx

@@ -0,0 +1,161 @@
+---
+title: "Row Level Security"
+description: "RLS works on every Supabase Lite backend; SQLite enforces it at the application layer with specific caveats."
+---
+
+import { Aside } from '@astrojs/starlight/components';
+
+Row Level Security works the same way you'd expect from Supabase on every backend: default-deny when RLS is enabled with no matching policies, `USING`/`WITH CHECK` clauses, `PERMISSIVE`/`RESTRICTIVE` combination rules, per-command policy targeting (`FOR SELECT/INSERT/UPDATE/DELETE/ALL`), role targeting (`TO anon, authenticated, PUBLIC`), and the `auth.uid()`/`auth.jwt()` placeholders. If you already know Postgres RLS, none of that behavior needs re-explaining here: see the [Supabase RLS guide](https://supabase.com/docs/guides/database/postgres/row-level-security) for the concepts.
+
+What differs is *how* it's enforced, and a handful of SQLite-specific gaps.
+
+## Enforcement model
+
+- **SQLite:** policies are extracted from the Postgres DDL during translation and enforced at the application layer by rewriting the PostgREST AST before query execution. `USING` conditions merge into the query's `WHERE` clause; `WITH CHECK` conditions are evaluated in-memory against the proposed INSERT/UPDATE values.
+- **PGlite / Postgres:** native Postgres RLS. Each request runs inside a transaction with `SET LOCAL role` and `set_config('request.jwt.claim.sub', ...)`, so the database enforces policies directly, identical to hosted Supabase.
+
+`auth.role()` resolves from the JWT `role` claim (defaulting to `"anon"` if missing, matching PostgREST). `auth.uid()` resolves to the JWT `sub` claim. `auth.jwt()` exposes the full payload. These placeholders are supported in policy expressions on both dialects.
+
+On `sqlite-postgres`, runtime metadata is persisted to the disposable cache file `supabase/.temp/.runtime-metadata-cache.json`. `lite start` accepts only migration-derived entries and trusts only the ordered SQL recorded in `supabase_migrations.schema_migrations`; migration files and `schemas/*.sql` are never startup inputs. Missing, corrupt, old, stale, or tampered caches rebuild automatically from applied history, including the complete RLS table/policy lifecycle. A rename carries RLS and policies to the new table name; dropping a table removes them, even if a table with the same name is created later.
+
+Rebuilds also replay the physical migrations in memory and compare their raw SQLite structure with the live database. Invalid/null recorded statements or out-of-band structural changes stop startup with a `lite db reset` hint. Introspection only proves equality and never generates policies. `lite dev` and the Vite plugin instead recompute metadata from the declarative schema they apply; use exactly one backend process per project, and capture declarative changes in migrations before switching to `lite start`.
+
+<Aside type="caution">
+While [admin mode](/running#admin-mode) is on (the default for loopback `lite dev`, `lite start`, and Vite dev listeners), requests that carry no credential at all run as `service_role` and skip RLS entirely. To exercise your policies, send an `apikey`:
+
+```bash
+# anon
+curl -H "apikey: $PUBLISHABLE_KEY" 127.0.0.1:54321/rest/v1/notes
+# authenticated — the apikey is required IN ADDITION to the user JWT
+curl -H "apikey: $PUBLISHABLE_KEY" -H "Authorization: Bearer $USER_JWT" \
+  127.0.0.1:54321/rest/v1/notes
+```
+
+Neither request is ever elevated, so both behave exactly as they will in production. A bearer token alone (no `apikey`) is rejected with 401 before RLS is reached — opaque keys are only sourced from `apikey`, matching upstream. Or start with `--no-admin`.
+</Aside>
+
+<Aside>
+Every RLS behavior listed as supported here is regression-tested against both SQLite and PGlite in the package's test suite, so a silent SQLite-only bypass would fail CI rather than ship quietly.
+</Aside>
+
+## SQLite-specific caveats
+
+<Aside type="caution">
+These four apply to the SQLite path only. None of them apply on PGlite/Postgres: RLS there is native Postgres RLS with no emulation gaps.
+</Aside>
+
+### No `DEFAULT auth.uid()` on columns
+
+SQLite can't evaluate `auth.uid()` as a column default (it's a JWT-bound function, not a SQLite builtin). Drop the default, pass `user_id` from the client on insert, and let `WITH CHECK` enforce ownership server-side:
+
+```sql
+-- Instead of:
+user_id uuid not null default auth.uid() references auth.users (id),
+
+-- Use:
+user_id uuid not null references auth.users (id),
+-- and rely on a WITH CHECK policy to bind the row to the caller.
+```
+
+```ts
+const { data: { session } } = await supabase.auth.getSession();
+await supabase.from("<thing>").insert({
+  user_id: session.user.id,
+  // ...
+});
+```
+
+### Subquery `WITH CHECK` on `INSERT` throws
+
+`WITH CHECK` expressions containing subqueries (`user_id IN (SELECT ...)`, `EXISTS (...)`) can't be evaluated in-memory, so SQLite throws rather than silently passing or failing. This is the classic "child belongs to a parent owned by the caller" pattern:
+
+```sql
+-- Fails on SQLite (subquery in WITH CHECK):
+create policy milestones_insert_own on public.milestones
+  for insert to authenticated
+  with check (
+    exists (
+      select 1 from public.goals
+      where goals.id = milestones.goal_id
+        and goals.user_id = auth.uid()
+    )
+  );
+```
+
+**Workaround:** denormalize the authorizing column onto the child table and compare directly:
+
+```sql
+create policy milestones_insert_own on public.milestones
+  for insert to authenticated
+  with check (auth.uid() = user_id);
+```
+
+This also matches [Supabase's own performance recommendation](https://supabase.com/docs/guides/database/postgres/row-level-security#tips): subquery policies execute per row even on real Postgres.
+
+### `UPSERT` applies `INSERT` policies only
+
+Postgres applies `UPDATE` policies on conflict resolution during an upsert. Supabase Lite applies the `INSERT WITH CHECK` policy to all upsert rows regardless of outcome, because conflict resolution is unknown at the point the policy has to be evaluated.
+
+### `FORCE ROW LEVEL SECURITY` is accepted and ignored
+
+`ALTER TABLE ... FORCE ROW LEVEL SECURITY` (and `NO FORCE`) is parsed and then ignored. On Postgres it only controls whether the table owner is subject to the table's policies; Supabase Lite has no table-owner exemption to begin with, so there is nothing to toggle. As on Postgres, `FORCE` alone does not enable RLS: only `ENABLE ROW LEVEL SECURITY` does, and only `DISABLE ROW LEVEL SECURITY` turns it back off. Policies may exist while RLS is disabled or has never been enabled; they remain stored but inert until RLS is enabled.
+
+### `RETURNING` isn't checked against the `SELECT` policy
+
+Postgres errors if a `RETURNING` clause would expose a row not visible under the table's `SELECT` policy. Supabase Lite doesn't check this on SQLite; `RETURNING` returns whatever the mutation touched.
+
+## `DROP POLICY` / `ALTER POLICY`
+
+Standalone `DROP POLICY [IF EXISTS]` and `ALTER POLICY` are handled during RLS collection rather than emitted as SQLite DDL, so they work on the SQLite path too, in both imperative migrations and declarative schemas:
+
+- `DROP POLICY [IF EXISTS] <name> ON <table>` (schema-qualified names included) removes the policy from the collected RLS registry.
+- `ALTER POLICY` updates the `TO` / `USING` / `WITH CHECK` clauses. The command type (`SELECT`/`INSERT`/…) and the `PERMISSIVE`/`RESTRICTIVE` flag can't be changed by `ALTER POLICY`, matching Postgres.
+- `ALTER POLICY ... RENAME TO <new_name>` renames the policy in place.
+
+```sql
+alter policy "select own" on todos using (auth.uid() = user_id and archived = false);
+alter policy "select own" on todos rename to "select own todos";
+drop policy if exists "select own todos" on todos;
+```
+
+Both statements replay in order alongside every other RLS-affecting statement collected from your migrations and `schemas/*.sql`, so editing or removing a `CREATE POLICY` directly in a declarative schema file still works exactly as before. Dropping or altering a policy that doesn't exist errors, same as Postgres. On PGlite/Postgres these statements run natively and always have.
+
+## Per-user multi-tenant recipe
+
+The most common shape, "each user sees only their own rows," works identically on SQLite, PGlite, and Postgres:
+
+```sql
+create table <thing> (
+  id uuid primary key default gen_random_uuid(),
+  user_id uuid not null references auth.users(id) on delete cascade,
+  -- domain columns
+  created_at timestamptz not null default now()
+);
+
+alter table <thing> enable row level security;
+
+create policy "select own" on <thing> for select to authenticated using (auth.uid() = user_id);
+create policy "insert own" on <thing> for insert to authenticated with check (auth.uid() = user_id);
+create policy "update own" on <thing> for update to authenticated using (auth.uid() = user_id) with check (auth.uid() = user_id);
+create policy "delete own" on <thing> for delete to authenticated using (auth.uid() = user_id);
+```
+
+The client supplies `user_id` on insert since SQLite has no `DEFAULT auth.uid()`:
+
+```ts
+const { data: { session } } = await supabase.auth.getSession();
+await supabase.from("<thing>").insert({
+  user_id: session.user.id,
+  // ...
+});
+```
+
+## PGlite / Postgres auto-setup
+
+When any table has `ENABLE ROW LEVEL SECURITY`, Supabase Lite automatically creates the `anon`, `authenticated`, and `service_role` roles if they're missing (`service_role` gets `BYPASSRLS`) and grants default privileges on all tables and sequences in the relevant schemas. No manual `CREATE ROLE` or `GRANT` statements needed.
+
+## See also
+
+- [Backends](/database/backends): switching drivers moves you from application-layer RLS emulation to native Postgres RLS.
+- [Postgres → SQLite translation](/database/postgres-sqlite-translation): how `CREATE POLICY` and `ENABLE ROW LEVEL SECURITY` DDL gets parsed and extracted.
+- [Supabase RLS guide](https://supabase.com/docs/guides/database/postgres/row-level-security): the base concepts this page assumes.

package/docs/database/schemas.mdx

@@ -0,0 +1,58 @@
+---
+title: "Declarative schemas"
+description: "Writing Postgres DDL in supabase/schemas/*.sql, and how it maps onto SQLite's single-namespace model."
+---
+
+Supabase Lite supports Supabase's declarative schema workflow: write Postgres DDL in `supabase/schemas/*.sql`, and the tooling diffs it against the live database to produce migrations. This page covers what's identical and what changes because the SQLite path has no real schema/namespace concept. For the base declarative-schema workflow, see the [Supabase declarative schemas guide](https://supabase.com/docs/guides/local-development/declarative-database-schemas).
+
+## Writing schemas
+
+Write plain Postgres DDL:
+
+```sql
+-- supabase/schemas/schema.sql
+create table todos (
+  id uuid primary key default gen_random_uuid(),
+  user_id uuid not null references auth.users(id) on delete cascade,
+  title text not null,
+  done boolean default false,
+  created_at timestamptz not null default now()
+);
+
+alter table todos enable row level security;
+
+create policy "select own" on todos for select to authenticated using (auth.uid() = user_id);
+create policy "insert own" on todos for insert to authenticated with check (auth.uid() = user_id);
+```
+
+Point `config.toml` at the file(s):
+
+```toml
+[db.migrations]
+schema_paths = ["./schemas/schema.sql"]
+```
+
+`lite dev` and the Vite plugin watch `schemas/*.sql` and re-apply on change. `lite db diff` compares the live DB against these files and emits a migration for the delta.
+
+## SQLite is single-schema
+
+Postgres supports `CREATE SCHEMA` and cross-schema references (`billing.invoices`, `SET search_path`) with real namespace isolation. SQLite has no schema concept: every object lives in one flat namespace. What you get on the SQLite path depends on which driver you're using:
+
+- On `sqlite-postgres` (the default for declarative Postgres DDL), `CREATE SCHEMA` and schema-qualified tables are accepted but flattened into a single physical namespace. PostgREST records the schema each table came from, so `schema()` / the `Accept-Profile` header routes to the right tables. There's no true isolation, though: two schemas with a same-named table collide once the prefix is stripped.
+- On the bare `sqlite` driver (raw SQLite DDL, no translation), there's no schema handling at all. Everything is `public`.
+
+Either way, this is not real Postgres multi-schema. `auth.users`, `storage.objects`, and other system-schema tables are handled internally by Supabase Lite; you don't need to (and can't) create competing user-defined schemas with the same names. The protected `auth` and `storage` schemas are not exposed through the Data API by default. `storage` can be added explicitly to `api.schemas` when direct metadata endpoints are intentional; `auth` should remain private.
+
+See [Postgres → SQLite translation](/database/postgres-sqlite-translation) for the full list of DDL constructs that don't survive the SQLite path.
+
+On PGlite and Postgres, multiple schemas and `schema()` work exactly as they do on hosted Supabase. See [Backends](/database/backends).
+
+## What else changes on SQLite
+
+DDL you write here goes through the same translator described in [Postgres → SQLite translation](/database/postgres-sqlite-translation): types get mapped (`SERIAL` → `INTEGER PRIMARY KEY AUTOINCREMENT`, `JSONB` → `TEXT` with a `json_valid()` check, and so on), column defaults are restricted to a small allow-list, and RLS statements are extracted rather than emitted as SQLite DDL (see [Row Level Security](/database/rls)). Postgres-only constructs with no SQLite equivalent, such as `LATERAL` joins, table inheritance, and range types, throw a descriptive error at translation time rather than silently dropping.
+
+## See also
+
+- [Migrations](/database/migrations): how the declarative diff turns `schemas/*.sql` changes into an applied migration.
+- [Postgres → SQLite translation](/database/postgres-sqlite-translation): the type-mapping and defaults reference.
+- [Backends](/database/backends): schemas and `schema()` work unmodified on PGlite/Postgres.

package/docs/index.mdx

@@ -0,0 +1,49 @@
+---
+title: "Introduction"
+description: "What Supabase Lite is, what's supported today, and how it relates to hosted Supabase."
+---
+
+import { Aside, Card, CardGrid } from '@astrojs/starlight/components';
+import banner from '../../../../.github/assets/banner.png';
+
+![Supabase Lite banner](/banner.png)
+
+Supabase Lite (`@supabase/lite`) is a lightweight, TypeScript-native reimplementation of Supabase features while being database agnostic and mainly focused on SQLite. It ships a PostgREST-compatible Data API and a GoTrue-compatible Auth API, so `@supabase/supabase-js` works unchanged against it for the methods it supports. 
+
+SQLite is the primary database (`bun:sqlite`, `node:sqlite`, SQLite WASM, Cloudflare D1/DO), with PGlite and Postgres available as alternative backends. Everything runs in one process: no Docker, no separate database container. You write Postgres DDL in `supabase/schemas/*.sql`, and on the SQLite path it gets translated on the fly. Once your project outgrows SQLite, you can seamlessly upgrade to Supabase.
+
+Supabase Lite supplements Supabase rather than replacing it. It implements roughly 60% of the most-used `supabase-js` surface, the subset most useful for fast prototyping, with a clear upgrade path to hosted or self-hosted Supabase when a project outgrows it.
+
+<Aside type="caution">
+Supabase Lite is pre-1.0 / alpha. APIs, config shape, and the on-disk format may change between releases. Not for production use yet.
+</Aside>
+
+## Scope at a glance
+
+| Product | Status | Notes |
+|---|---|---|
+| Data API | Supported | 53/74 `supabase-js` query-builder methods on SQLite, 72/74 on Postgres/PGlite. Core CRUD, filters, embedding, and RLS all work. See [Compatibility](/compatibility). |
+| Auth | Partial | 13 backend endpoints implemented (email/password, OTP, sessions, password recovery, OAuth sign-in for `github`/`google`). Other OAuth providers, anonymous sign-in, manual identity linking, admin API, and MFA are planned. See [Auth overview](/auth/overview). |
+| Storage | Experimental | 20/20 `supabase-js` methods implemented, gated behind `EXPERIMENTAL_STORAGE`. Role-based access and RLS on storage objects are still pending. See [Storage overview](/storage/overview). |
+| Realtime | Not yet | Config schema exists; no WebSocket server or channels yet. See [Realtime](/other/realtime). |
+| Edge Functions | Not yet | Config schema exists; no runtime or `/functions/v1` routes yet. See [Edge Functions](/other/edge-functions). |
+
+Compatibility is measured against the `@supabase/supabase-js` surface, not raw Postgres wire-protocol access. Direct SQL clients, `psql`, and third-party Postgres tooling are not a target.
+
+<Aside type="note">
+These are capability-level rollups. The package installed in your project ships an exact, per-method matrix in `STATUS.md` (and a companion `FEATURES.md` with effort/blocker notes for gaps) that updates every time you run `npm install`. Treat that file as the source of truth for exact counts.
+</Aside>
+
+For the concepts Supabase Lite implements unchanged from upstream (the general Supabase architecture, product list, and terminology), see the [Supabase docs](https://supabase.com/docs) and the [architecture guide](https://supabase.com/docs/guides/getting-started/architecture). This site only documents where Supabase Lite diverges.
+
+<CardGrid>
+  <Card title="Quickstart">
+    Install, scaffold a project, and run your first query. [Read more →](/quickstart/)
+  </Card>
+  <Card title="Compatibility">
+    Capability-level support matrix across SQLite, PGlite, and Postgres. [Read more →](/compatibility/)
+  </Card>
+  <Card title="Database">
+    Backends, the Data API, RLS, schemas, and migrations. [Read more →](/database/overview/)
+  </Card>
+</CardGrid>

package/docs/integrations/embedded.mdx

@@ -0,0 +1,100 @@
+---
+title: "Embedded / programmatic"
+description: "Use the App class directly in Bun, Node, browser, or edge runtimes, without the CLI."
+---
+
+import { Tabs, TabItem } from '@astrojs/starlight/components';
+
+Supabase Lite has no required CLI dependency at runtime. The `App` class is a Web-API-compliant request handler (`app.fetch`) you can construct directly in Bun, Node, the browser, or an edge runtime, and either call in-process or serve over HTTP yourself.
+
+## Constructing an App
+
+```ts
+import { App } from "@supabase/lite";
+import { createConnection } from "@supabase/lite/sqlite";
+
+const connection = await createConnection({ url: "file:./data.db" });
+const app = new App({ connection, auth: { enabled: true } });
+
+// optionally apply schema on boot
+const schema = await Bun.file("./schema.sql").text();
+await app.connection.createMigrator(schema).migrate();
+
+export default app; // app.fetch handles requests
+```
+
+`App` takes a config object whose required field is `connection` (a `Connection` or a `Promise<Connection>`, useful when the connection itself needs an async setup step, as with Cloudflare's `getPlatformProxy`). The rest of the config is the same schema `config.toml` validates against (`auth`, `db`, `api`, `studio`, ...), plus an `options` object for `server` and `drivers` overrides. The `README.md` shipped in the package documents the full config shape.
+
+## Two ways to use it
+
+<Tabs>
+<TabItem label="In-process (no network)">
+Skip HTTP entirely and call the app's own client, which routes through `app.fetch` internally in the same process:
+
+```ts
+const client = app.getClient();
+const { data } = await client.from("todos").select("*");
+```
+
+Same `@supabase/supabase-js` API, no HTTP round trip. Useful for scripts, tests, and server-side code that doesn't need a network boundary. `getClient()` defaults to the configured `auth.publishable_key` (override with `getClient({ apikey })`). Disable API-key enforcement entirely with `options.server.apiKeys: false`, or supply a custom key→role resolver via `options.server.apiKeys.resolver`. See [API keys](/auth/overview#api-keys).
+</TabItem>
+<TabItem label="Over HTTP">
+Serve `app.fetch` with any Web-API-compatible server and point `@supabase/supabase-js` at the URL, same as talking to a hosted Supabase project:
+
+```ts
+// Bun
+const server = Bun.serve({
+  hostname: "127.0.0.1",
+  fetch(request) {
+    return app.fetch(request, {
+      peerAddress: server.requestIP(request)?.address ?? null,
+    });
+  },
+});
+```
+
+```ts
+// Node, via @hono/node-server
+import { serve } from "@hono/node-server";
+serve({
+  port: 3000,
+  hostname: "127.0.0.1",
+  fetch(request, env) {
+    return app.fetch(request, {
+      peerAddress: env.incoming.socket.remoteAddress ?? null,
+    });
+  },
+});
+```
+
+```ts
+import { createClient } from "@supabase/supabase-js";
+const client = createClient("http://127.0.0.1:3000", "<sb_publishable_...>");
+```
+
+`AppRequestContext.peerAddress` is trusted transport metadata, not a forwarded header. Supply it only from the socket object owned by your server adapter. If the adapter cannot determine the peer, pass `null` so admin mode fails closed. Omitting the context preserves the in-process/edge fallback, where only the loopback hostname guard is available.
+</TabItem>
+</Tabs>
+
+## Drivers per runtime
+
+`@supabase/lite/sqlite` resolves to the right SQLite binding automatically based on the runtime's export condition (`bun`, `node`, `browser`); you don't need to pick a driver yourself for local SQLite use. For other backends, import the matching subpath explicitly:
+
+| Runtime/DB | Import |
+|---|---|
+| Bun | `@supabase/lite/sqlite` (resolves to `bun:sqlite`) |
+| Node.js ≥ 22 | `@supabase/lite/sqlite` (resolves to `node:sqlite`) |
+| Browser | `@supabase/lite/sqlite` (resolves to `@sqlite.org/sqlite-wasm`) |
+| Cloudflare Workers (D1) | `@supabase/lite/workerd` |
+| PGlite | `@supabase/lite/pglite` |
+| Postgres | `@supabase/lite/postgres` |
+| libsql / Turso | `@supabase/lite/libsql` |
+
+See [Database backends](/database/backends) for how backend choice affects feature support (RLS enforcement, `rpc()`, ranges, and so on).
+
+## Related
+
+- [Running Supabase Lite](/running): how embedding compares to `lite dev`/`lite start`/the Vite plugin.
+- [Database backends](/database/backends): connection config per backend.
+- [Frameworks](/integrations/frameworks): the Next.js and Cloudflare Workers patterns built on this `App` API.
+- Upstream: [Supabase local development](https://supabase.com/docs/guides/local-development). There's no embedded/programmatic mode in Supabase itself; this is a Supabase Lite-specific concept for running the backend inside your own process instead of Docker.

package/docs/integrations/frameworks.mdx

@@ -0,0 +1,83 @@
+---
+title: "Framework guides"
+description: "Running Supabase Lite inside Next.js, Cloudflare Workers, and Docker."
+---
+
+Supabase Lite mounts as a request handler (`app.fetch`), so it fits into most frameworks without a custom server.
+
+## Next.js App Router
+
+Run Supabase Lite in the same `next dev` process via App Router catch-all route handlers, no webpack plugin or custom server needed.
+
+Add `@supabase/lite` to `serverExternalPackages` so Next treats it as server-only:
+
+```ts
+// next.config.ts
+import type { NextConfig } from "next";
+
+const nextConfig: NextConfig = {
+  serverExternalPackages: ["@supabase/lite"],
+};
+
+export default nextConfig;
+```
+
+Create one server singleton that boots the app in-process (cache the boot promise on `globalThis` so hot-reload doesn't reboot it), then re-export it from three catch-all routes:
+
+```txt
+app/auth/v1/[[...path]]/route.ts
+app/rest/v1/[[...path]]/route.ts
+app/%5Fsystem/[[...path]]/route.ts
+```
+
+```ts
+export const runtime = "nodejs";
+export { DELETE, GET, HEAD, OPTIONS, PATCH, POST, PUT } from "@/lib/server";
+```
+
+The `%5Fsystem` folder name is intentional: Next treats folders starting with `_` as private, so the URL-encoded form is what produces a public `/_system` route.
+
+What's different from a standard Supabase + Next.js setup: no Docker, no `supabase start`, and no separate origin, since the client just talks to `window.location.origin`.
+
+## Cloudflare Workers
+
+D1 is reached through `@supabase/lite/workerd`. Two schema-management approaches work:
+
+- **CLI-managed:** a `supabase/` directory with declarative schemas and seed SQL, applied against the D1 binding through the `lite` CLI.
+- **Wrangler-native:** no Supabase Lite CLI involved. Schema lives in `migrations/0_schema.sql` and is applied with `wrangler d1 migrations apply`, wrangler's own tooling.
+
+The Worker itself is identical either way:
+
+```ts
+import { d1 } from "@supabase/lite/workerd";
+import { App } from "@supabase/lite";
+
+export default {
+  async fetch(request, env, _ctx): Promise<Response> {
+    const connection = d1({ binding: env.DB });
+    const app = new App({ connection, studio: { enabled: true } });
+    return app.fetch(request);
+  },
+} satisfies ExportedHandler<Env>;
+```
+
+`wrangler.json(c)` declares the D1 binding as usual:
+
+```json
+"d1_databases": [
+  { "binding": "DB", "database_name": "db", "migrations_dir": "./migrations" }
+]
+```
+
+What's different from a standard Supabase setup: there's no separate database service at all, D1 runs as part of the Worker's own bindings. `experimental` features (Storage, etc.) default to off in workerd since `process.env` isn't available there; toggle them explicitly from a binding with `setExperimental("storage", env.EXPERIMENTAL_STORAGE === "1")`.
+
+## Docker
+
+Package the published `@supabase/lite` npm package into a container with `supabase/` bind-mounted for config, schema, seed, and the SQLite file. Run `lite migration up` (or `lite db diff -f <name>` then `lite migration up`) as a one-off bootstrap step, then serve with `lite start --host --no-admin`: `--host` listens beyond the container loopback and `--no-admin` makes the public-boundary choice explicit.
+
+## Related
+
+- [Embedded / programmatic](/integrations/embedded): the `App` API these guides build on.
+- [Vite plugin](/integrations/vite): the equivalent pattern for Vite frontends instead of Next.js/Workers.
+- [Database backends](/database/backends): D1, PGlite, and Postgres connection setup.
+- Upstream: [Supabase local development](https://supabase.com/docs/guides/local-development), the Docker-based setup these framework integrations replace.