@supabase/lite 0.3.1-next.1 → 0.3.1-next.3

package/LIMITATIONS.md

@@ -0,0 +1,49 @@
+# Limitations (quick reference)
+
+Token-efficient cheat sheet for agents and humans. Read this before authoring schema or client code. Detailed semantics, status tables, and workarounds live in [STATUS.md](https://github.com/supabase-community/lite/blob/HEAD/STATUS.md).
+
+Anchors below point to the corresponding STATUS.md section. If a limitation here is fixed, delete the bullet (do not strike-through). If you ship a feature change in STATUS.md, update this file in the same commit (see [AGENTS.md](https://github.com/supabase-community/lite/blob/HEAD/AGENTS.md)).
+
+## SQL / DDL (SQLite path)
+
+- `DEFAULT auth.uid()` (and `auth.role()`, `auth.email()`, `auth.jwt()`) on columns → not supported. Drop the default, pass `user_id` from the client, rely on RLS `WITH CHECK`. See [Column Defaults](https://github.com/supabase-community/lite/blob/HEAD/STATUS.md#column-defaults).
+- Subquery `WITH CHECK` on `INSERT` (`user_id IN (SELECT …)`, `EXISTS (…)`) → throws. Denormalise the owning column. See [RLS known limitations](https://github.com/supabase-community/lite/blob/HEAD/STATUS.md#row-level-security-rls).
+- Scalar functions outside the allow-list in `DEFAULT` or `CHECK` (`trim`, `btrim`, `length`, `lower`, `upper`, …) → `Function call "<name>" not supported`. Use literals or move the check to the app layer. See [Column Defaults](https://github.com/supabase-community/lite/blob/HEAD/STATUS.md#column-defaults) and [CHECK constraint functions](https://github.com/supabase-community/lite/blob/HEAD/STATUS.md#check-constraint-functions).
+- `nextval` / `currval`, `clock_timestamp`, `txid_current`, user-defined functions → not supported. See [Column Defaults](https://github.com/supabase-community/lite/blob/HEAD/STATUS.md#column-defaults).
+- `DROP POLICY` / `ALTER POLICY`, `FORCE ROW LEVEL SECURITY` → not translated. See [RLS known limitations](https://github.com/supabase-community/lite/blob/HEAD/STATUS.md#row-level-security-rls).
+- PL/pgSQL `DECLARE`, `IF`, `LOOP`, `RAISE`, variables → not supported in trigger bodies. See [PL/pgSQL Trigger Functions](https://github.com/supabase-community/lite/blob/HEAD/STATUS.md#plpgsql-trigger-functions).
+
+## supabase-js (SQLite path)
+
+- `rpc()` → not supported. Use a regular HTTP endpoint for custom logic. See [Control & Specialized](https://github.com/supabase-community/lite/blob/HEAD/STATUS.md#control--specialized).
+- Embedded-table dotted-path filters (`eq('rel.col', v)`) → not supported. Filter on a FK column or restructure the query. See [Embedded filters](https://github.com/supabase-community/lite/blob/HEAD/STATUS.md#embedded-filters).
+- `contains` / `containedBy` / `overlaps` → partial. Arrays of scalars and shallow objects work; arrays of objects and nested objects do not. See [Array & JSON Filters](https://github.com/supabase-community/lite/blob/HEAD/STATUS.md#array--json-filters).
+- `textSearch` (fts/plfts/phfts/wfts) → not implemented on SQLite. See [Full-Text Search](https://github.com/supabase-community/lite/blob/HEAD/STATUS.md#full-text-search).
+- `regexMatch` / `regexIMatch` → not implemented on SQLite. See [Regex](https://github.com/supabase-community/lite/blob/HEAD/STATUS.md#regex).
+- Range operators (`rangeGt`, …) and quantified comparisons (`eq(any)`, …) → not implemented on SQLite. See [Range Operators](https://github.com/supabase-community/lite/blob/HEAD/STATUS.md#range-operators) and [Quantified Comparison Operators](https://github.com/supabase-community/lite/blob/HEAD/STATUS.md#quantified-comparison-operators).
+- `schema()` → SQLite is single-schema. See [Control & Specialized](https://github.com/supabase-community/lite/blob/HEAD/STATUS.md#control--specialized).
+
+## Auth (planned, not yet shipped)
+
+- OAuth, anonymous sign-in, identity linking, admin API, MFA → planned. See [Auth API: Planned](https://github.com/supabase-community/lite/blob/HEAD/STATUS.md#-planned).
+
+## Runtime / dev
+
+- `vite preview` does **not** mount the API. Plugin runs in `vite` / `vite dev` only. See [Vite plugin scope](https://github.com/supabase-community/lite/blob/HEAD/STATUS.md#vite-plugin-scope).
+- Do not run `lite dev` (or `lite start`) alongside the Vite plugin — both bind the API and collide. See [When to use what](https://github.com/supabase-community/lite/blob/HEAD/README.md#when-to-use-what).
+
+## Postgres backends (pglite, postgres)
+
+Most SQLite-only limitations above do not apply. `rpc()`, ranges, regex, quantified comparisons, full-text search, and native `DEFAULT auth.uid()` all work on the Postgres path. See per-section status tables in [STATUS.md](https://github.com/supabase-community/lite/blob/HEAD/STATUS.md).
+
+## Anti-patterns
+
+Common ways code goes wrong against supalite. The fix for each is the corresponding bullet above.
+
+- Don't put `DEFAULT auth.uid()` on a column. Drop the default; pass `user_id` from the client; let RLS `WITH CHECK` enforce ownership.
+- Don't call `rpc()` on the SQLite path. Run a regular HTTP endpoint, or switch the driver to `pglite` / `postgres` in `config.toml`.
+- Don't use embedded dotted-path filters (`.eq('rel.col', v)`) on SQLite. Filter the FK column on the parent, or fetch matching ids first.
+- Don't run `lite dev` or `lite start` next to the Vite plugin — port collision.
+- Don't assume `vite preview` mounts the API. It doesn't. Use `lite start` or a real backend for non-dev environments.
+- Don't write `.env` files with `VITE_SUPABASE_URL` for an in-Vite plugin app until [#27](https://github.com/supabase-community/lite/issues/27) ships — use `window.location.origin` + any non-empty anon string.
+- Don't reach for `trim` / `length` / `lower` inside `CHECK` constraints on SQLite — use literal/operator comparisons.

package/PATTERNS.md

@@ -0,0 +1,119 @@
+# Patterns
+
+Canonical recipes for apps built on `@supabase/lite`. Pair with [LIMITATIONS.md](https://github.com/supabase-community/lite/blob/HEAD/LIMITATIONS.md) (what to avoid) and [STATUS.md](https://github.com/supabase-community/lite/blob/HEAD/STATUS.md) (full reference).
+
+This file is the authoritative source — the bundled [`supalite` skill](https://github.com/supabase-community/lite/blob/HEAD/skills/supalite/SKILL.md) points agents here, so updates land for every consumer on the next `npm install`.
+
+## Per-user multi-tenant ("each user sees only their own X")
+
+Most-common shape. Works the same on SQLite, PGlite, and Postgres.
+
+Schema:
+
+```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 (SQLite RLS evaluates `WITH CHECK` against supplied values; there is no `DEFAULT auth.uid()` on SQLite — see [LIMITATIONS.md](https://github.com/supabase-community/lite/blob/HEAD/LIMITATIONS.md#sql--ddl-sqlite-path)):
+
+```ts
+const { data: { session } } = await supabase.auth.getSession();
+await supabase.from("<thing>").insert({
+  user_id: session.user.id,
+  // ...
+});
+```
+
+## Filtering an embedded resource (SQLite path)
+
+Dotted-path filters (`.eq('rel.col', v)`) are not supported on SQLite. Two options:
+
+```ts
+// Not supported on SQLite:
+// supabase.from("trips").select("*, days(*)").eq("days.city", "Paris")
+
+// Option A — filter on FK column after pre-resolving ids:
+const { data: dayMatches } = await supabase.from("days").select("trip_id").eq("city", "Paris");
+const tripIds = dayMatches.map(d => d.trip_id);
+const { data } = await supabase.from("trips").select("*, days(*)").in("id", tripIds);
+
+// Option B — flatten the query and group in JS.
+```
+
+Native on Postgres / PGlite.
+
+## Custom server logic without `rpc()`
+
+`rpc()` is not implemented on the SQLite path. Three options, 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` in `supabase/config.toml`. `rpc()` works there.
+3. Run a regular server endpoint (Hono / Express / Next route handler / Vite middleware) and call it directly from the client.
+
+## Vite + supalite cold start
+
+The canonical Vite recipe:
+
+1. `bun add @supabase/lite @supabase/supabase-js`
+2. `vite.config.ts`:
+   ```ts
+   import { defineConfig } from "vite";
+   import { supalite } from "@supabase/lite/vite";
+   export default defineConfig({ plugins: [supalite()] });
+   ```
+3. `bunx lite init` to scaffold `supabase/`.
+4. Write Postgres DDL in `supabase/schemas/schema.sql` (RLS enabled).
+5. `src/lib/supabase.ts`:
+   ```ts
+   import { createClient } from "@supabase/supabase-js";
+   export const supabase = createClient(window.location.origin, "any-string-works-for-now");
+   ```
+6. `bun run dev`.
+
+Same-process, same origin, hot-reload on schema changes. Do **not** run `lite dev` alongside.
+
+## `updated_at` timestamps 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 `CREATE TRIGGER` body. See [STATUS.md#plpgsql-trigger-functions](https://github.com/supabase-community/lite/blob/HEAD/STATUS.md#plpgsql-trigger-functions) for the supported subset.
+
+## Profiles 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.

package/README.md

@@ -10,7 +10,7 @@
 
 Lightweight TypeScript-native Supabase implementation. SQLite as the primary database, with PGlite and Postgres support. Ships a PostgREST-compatible REST API and a GoTrue-compatible Auth API, so `@supabase/supabase-js` works as-is.
 
-Supalite targets AI builders who want quick, cheap prototypes today with a clear path to upgrade later. It supplements Supabase rather than replacing it. The project stays lightweight by implementing only what fits on top of non-UDF SQLite: roughly 60% of the most-used Supabase features, focused on the subset most useful for fast iteration.
+Supalite targets AI builders who want quick, cheap prototypes today with a clear path to upgrade later. It supplements Supabase rather than replacing it. The project stays lightweight by implementing only what fits on top of stock SQLite: roughly 60% of the most-used Supabase features, focused on the subset most useful for fast iteration.
 
 **Scope:** Both declarative schema (`supabase/schemas/*.sql`) and imperative Postgres migrations (`supabase/migrations/*.sql`, Supabase-CLI compatible) are supported. See [Migrations](#migrations). Advanced Postgres-specific column types (ranges, arrays of composites, and similar) are not available.
 
@@ -18,6 +18,27 @@ Validated against the upstream PostgREST and GoTrue test suites: 1,803 tests pas
 
 ---
 
+## Agents & Skill
+
+If you're an agent working on a supalite project, read these first:
+
+- [`LIMITATIONS.md`](https://github.com/supabase-community/lite/blob/HEAD/LIMITATIONS.md) — what's unsupported / partial, plus anti-patterns. Token-efficient cheat sheet.
+- [`PATTERNS.md`](https://github.com/supabase-community/lite/blob/HEAD/PATTERNS.md) — canonical recipes (per-user RLS, embedded filter workarounds, custom server logic, Vite cold start, triggers).
+
+The npm package ships a [`supalite` skill](https://github.com/supabase-community/lite/blob/HEAD/skills/supalite/SKILL.md). After `npm install`, link it into your agent's skills dir so the cold-start checklist, routing rule, and limitation pointers trigger automatically:
+
+```bash
+# Agent standard: project-scoped install
+mkdir -p .agents/skills && ln -s ../../node_modules/@supabase/lite/skills/supalite .agents/skills/supalite
+
+# Claude Code: project-scoped install
+mkdir -p .claude/skills && ln -s ../../node_modules/@supabase/lite/skills/supalite .claude/skills/supalite
+```
+
+The skill itself points at the installed docs (not their content), so updates land for every consumer on the next `npm install`.
+
+---
+
 ## Feature overview
 
 Compatibility is measured from the `@supabase/supabase-js` surface. The goal is that code written against Supabase keeps working when pointed at @supabase/lite. Direct database access (raw SQL clients, Postgres wire protocol, `psql`) is **not** a target; everything below is scoped to what supabase-js exercises.
@@ -65,6 +86,20 @@ Edit `supabase/schemas/schema.sql` and the dev server re-applies the schema auto
 
 ---
 
+## When to use what
+
+| Scenario | Use | Notes |
+|---|---|---|
+| Vite frontend (React/Vue/Svelte/…) | [`@supabase/lite/vite` plugin](#vite-plugin) | Same-process. No separate CLI. API mounted on the Vite dev server. |
+| Non-Vite app, want auto schema-reload | `lite dev` | Separate process. Watches `schemas/*.sql`, re-applies on change. |
+| Non-Vite app, manual control / CI / prod-like | `lite start` | Separate process. No watch, no auto-migrate. |
+
+> Do not run `lite dev` or `lite start` alongside the Vite plugin — both bind the API and will collide.
+
+Known limitations across all paths: see [LIMITATIONS.md](https://github.com/supabase-community/lite/blob/HEAD/LIMITATIONS.md). Canonical recipes: see [PATTERNS.md](https://github.com/supabase-community/lite/blob/HEAD/PATTERNS.md).
+
+---
+
 ## CLI
 
 ```
@@ -136,20 +171,26 @@ export default defineConfig({
 });
 ```
 
-Then from your frontend:
+Then from your frontend. Because the plugin mounts the API on the Vite dev
+server itself, the simplest dev setup is to point supabase-js at the current
+origin and pass any non-empty string as the anon key:
 
 ```ts
 import { createClient } from "@supabase/supabase-js";
 
-const client = createClient(
-   import.meta.env.VITE_SUPABASE_URL,
-   import.meta.env.VITE_SUPABASE_ANON_KEY,
-);
+const client = createClient(window.location.origin, "any-string-works-for-now");
 ```
 
+The plugin does **not** currently inject `VITE_SUPABASE_URL` or
+`VITE_SUPABASE_ANON_KEY` — env injection is tracked in [#27](https://github.com/supabase-community/lite/issues/27). Until that lands, prefer `window.location.origin` over an env-driven URL for the in-Vite path.
+
 The plugin auto-resolves `./supabase/config.toml`, applies the schema on boot,
 watches `schemas/*.sql` for hot-reload, and mounts `/auth/v1`, `/rest/v1`, and
-`/_system` on the Vite server. Only active during `vite` / `vite dev`.
+`/_system` on the Vite server. Active in both `vite` / `vite dev` and `vite
+preview` (preview mounts the API and runs boot migrations, but does not watch
+schemas — it simulates production).
+
+> Do not run `lite dev` or `lite start` next to the plugin — both bind the API and will collide. See [When to use what](#when-to-use-what).
 
 See [`examples/todo`](https://github.com/supabase-community/lite/tree/HEAD/examples/todo) for a full Vite + React + Tailwind + RLS example, or [`examples/next-todo`](https://github.com/supabase-community/lite/tree/HEAD/examples/next-todo) for the same pattern using Next.js App Router catch-all route handlers.
 

package/STATUS.md

@@ -156,6 +156,56 @@ CREATE TABLE orders
 
 Unsupported PostgreSQL data types currently include `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, internal types (`tid`, `pg_lsn`, `internal`), pseudo-types, and handler types.
 
+### Column Defaults
+
+Column `DEFAULT` expressions in Postgres DDL are evaluated by the SQLite translator at CREATE TABLE time. Only constant expressions and a small allow-list of functions are honored.
+
+**Honored:**
+
+| Default expression                          | SQLite emission                           | Notes                       |
+|---------------------------------------------|-------------------------------------------|-----------------------------|
+| 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. They only work inside RLS `USING` / `WITH CHECK` (rewritten on the AST), not as column defaults.
+- `nextval(...)`, `currval(...)` — sequences are not modeled.
+- `clock_timestamp()`, `statement_timestamp()`, `txid_current()`, and other volatile catalog functions.
+- User-defined functions and any function not in the allow-list above.
+
+**Workaround for `default auth.uid()`:**
+
+Drop the default; pass `user_id` from the client on insert (sourced from the authenticated session). RLS `WITH CHECK (user_id = auth.uid())` already enforces 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.
+```
+
+This limitation applies only to the SQLite path. On PGlite/Postgres backends, `auth.uid()` works as a column default because the `auth.uid()` SQL function is bootstrapped natively.
+
+### CHECK constraint functions
+
+`CHECK (…)` constraints in Postgres DDL are passed to SQLite as-is and evaluated by SQLite at write time. Only functions SQLite itself knows are valid. Postgres-only scalars that are commonly reached for in `CHECK` constraints are rejected by the translator with `Function call "<name>" not supported`:
+
+- `trim`, `btrim`, `ltrim`, `rtrim` → use literal comparisons or move the validation to the app layer.
+- `length` (on text) → SQLite has `length()`, but the translator currently rejects it inside `CHECK`. Track in [#27 / friction logs].
+- `lower`, `upper` → same — work in `WHERE` but not currently in `CHECK`.
+- Any custom function or extension scalar (`btrim`, `regexp_replace`, etc.).
+
+**Workaround:** keep CHECK constraints to literal/operator comparisons (`length(col) > 0` is unsafe; `col <> ''` is fine), and validate richer rules in the app or via RLS `WITH CHECK` predicates.
+
+On the Postgres / PGlite path these functions work as in upstream Postgres.
+
 ### Row Level Security (RLS)
 
 RLS is supported on all database backends. The enforcement strategy differs by dialect:
@@ -182,7 +232,7 @@ RLS is supported on all database backends. The enforcement strategy differs by d
 
 | Limitation                              | Details                                                                                                                                                     |
 |-----------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| Subquery `WITH CHECK` on `INSERT`       | `WITH CHECK` expressions containing subqueries (e.g. `user_id IN (SELECT ...)`) cannot be evaluated in-memory. Currently throws an error.                   |
+| Subquery `WITH CHECK` on `INSERT`       | `WITH CHECK` expressions containing subqueries (e.g. `user_id IN (SELECT ...)`, `EXISTS (...)`) cannot be evaluated in-memory. Currently throws an error. **Workaround:** denormalise the authorising column (e.g. `user_id` onto the child table) and use `auth.uid() = user_id`. See [WITH CHECK subqueries](https://github.com/supabase-community/lite/blob/HEAD/internal/docs/limitations/rls-with-check-subqueries.md). |
 | `UPSERT` applies `INSERT` policies only | Postgres applies `UPDATE` policies on conflict; supalite applies `INSERT WITH CHECK` to all upsert rows since conflict resolution is unknown pre-execution. |
 | `FORCE ROW LEVEL SECURITY`              | Not differentiated from `ENABLE ROW LEVEL SECURITY`; table owner is not exempt.                                                                            |
 | `RETURNING` + `SELECT` policy           | Postgres errors if `RETURNING` references rows not visible to `SELECT` policy. Not checked.                                                                 |
@@ -349,6 +399,23 @@ All operators are parsed into the AST. The "Status" column reflects whether a wo
 | Nested embedding      | ✅      | ✅        | Multi-level joins                                                                               |
 | Aggregates            | ✅      | ✅        | count, sum, avg, min, max; spread aggregates return PGRST127                                    |
 
+### Embedded filters
+
+Filtering an embedded resource by one of its own columns (the dotted-path syntax `.eq('rel.col', value)` from supabase-js) is **not supported on SQLite**. Such filters are not rewritten into the embedded subquery; results are unfiltered or error.
+
+**Workaround:** filter on the foreign-key column on the parent table, or fetch the embedded set and filter in JS. Example:
+
+```ts
+// Not supported on SQLite:
+await client.from("trips").select("*, days(*)").eq("days.city", "Paris");
+
+// Use instead:
+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));
+```
+
+Supported natively on the Postgres / PGlite path.
+
 ### Response Shaping & Utilities
 
 | Method           | SQLite | Postgres | Notes                                 |
@@ -732,7 +799,13 @@ Mirrors upstream behavior documented in [`internal/docs/cli/environment.md`](htt
 | **Drivers**        | ✅      | Minimal email, SMS, and cache driver interfaces. Configured via `options.drivers`, exposed at `app.drivers`. |
 | **Realtime**       | 🔄     | Config schema defined (`app/src/config/realtime.ts`).                                                 |
 | **Edge Functions** | 🔄     | Config schema defined (`app/src/config/functions.ts`). Per-function JWT verification, entrypoints.    |
-| **Vite plugin**    | ✅      | `@supabase/lite/vite` subpath export mounts supalite as middleware in a Vite dev server (`app/src/vite/`). |
+| **Vite plugin**    | ✅      | `@supabase/lite/vite` subpath export mounts supalite as middleware in a Vite dev server (`app/src/vite/`). See [Vite plugin scope](#vite-plugin-scope). |
+
+### Vite plugin scope
+
+- **Active only during `vite` / `vite dev`.** `vite preview`, `vite build`, and any production server do **not** mount the API. Use a real backend (`lite start`, hosted Supabase, or equivalent) for non-dev environments.
+- **Same-process by design.** The plugin mounts `/auth/v1`, `/rest/v1`, and `/_system` on the Vite dev server. Do not run `lite dev` or `lite start` alongside — both bind the API and will collide on port.
+- **No env-var injection (yet).** The plugin does not currently set `VITE_SUPABASE_URL` / `VITE_SUPABASE_ANON_KEY`. Tracked in [#27](https://github.com/supabase-community/lite/issues/27). For now pass `window.location.origin` + any non-empty anon string to `createClient`.
 
 ---