[!WARNING] 🚧 Alpha. Supalite is pre-1.0 and under active development. APIs, config shape, and on-disk format may change. Not for production use yet. See Feature Overview for current state.

Supabase Lite

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.

Scope: Both declarative schema (supabase/schemas/*.sql) and imperative Postgres migrations (supabase/migrations/*.sql, Supabase-CLI compatible) are supported. See Migrations. Advanced Postgres-specific column types (ranges, arrays of composites, and similar) are not available.

Validated against the upstream PostgREST and GoTrue test suites: 1,803 tests passing.

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.

| Service | Status | Notes | |-------------------------|--------|--------------------------------------------------------------------| | Databases | ✅ | bun:sqlite, node:sqlite, sqlite-wasm, Cloudflare D1 + DO, PGlite, PostgreSQL | | Data API (PostgREST) | ✅ | 47/74 supabase-js methods on SQLite: from, select, insert, update, delete, upsert, eq, neq, gt, gte, lt, lte, in, notIn, is, isDistinct, like, ilike, likeAllOf, likeAnyOf, ilikeAllOf, ilikeAnyOf, match, or, not, filter, order, limit, range, single, maybeSingle, csv, abortSignal, setHeader, throwOnError, maxAffected, returns, overrideTypes, plus full resource embedding (FK joins, !inner, spreads, nested, aggregates). Partial: contains, containedBy, overlaps. rpc not supported on SQLite. 72/74 on Postgres. | | Auth API (GoTrue) | ✅ | 21/63 supabase-js methods (11 backend + 10 client-side helpers): signUp, signInWithPassword, signInWithOtp, verifyOtp, refreshSession, signOut, getUser, updateUser, resetPasswordForEmail, resend, reauthenticate. OAuth, anonymous, identity linking, admin API, and MFA planned. | | Storage API | 🧪 | 20/20 supabase-js methods: upload, download, list, remove, move, copy, info, exists, update, getPublicUrl, createSignedUrl, createSignedUrls, createSignedUploadUrl, uploadToSignedUrl, listBuckets, getBucket, createBucket, updateBucket, deleteBucket, emptyBucket. Role-based access + RLS pending. ⚠️ Gated behind EXPERIMENTAL_STORAGE. | | Realtime | 🔄 | Coming soon | | Edge Functions | 🔄 | Coming soon | | Cloud Hosting | 🔄 | Coming soon | | CLI | ✅ | Upstream supabase CLI parity for: init, start, db diff, db query. Aligned to v2.98.2 command shape. | | Upgrade to Supabase | 🧪 | lite upgrade migrates a project to hosted or local Supabase: schema + user-table data + auth sessions (signing-key import). Storage/realtime migration pending. SQLite shim health audit via --dry-run. |

Install

npm install -g @supabase/lite     # global, exposes `lite` CLI
# or per-project: npm install @supabase/lite  (run via `npx @supabase/lite <cmd>`)

Quick start

lite init      # scaffold supabase/ directory
lite dev       # start server with schema hot-reload

The API is now running at http://localhost:54321. Point @supabase/supabase-js at it:

import { createClient } from "@supabase/supabase-js";

const supabase = createClient("http://localhost:54321", "any-string-works-for-now");
const { data } = await supabase.from("todos").select("*");

No anon key is required yet. Pass any non-empty string as the second argument.

Edit supabase/schemas/schema.sql and the dev server re-applies the schema automatically.

CLI

lite <command> [options]

Local commands

| Command | Description | |------------------|---------------------------------------------------------------| | init | Scaffold supabase/ (config, schema, seed, data dir) | | dev | Start server + watch schemas/*.sql, auto-apply on change | | start | Start server (no watch, no auto-migrate) | | db schema | Print current DB schema; --diff compares vs schemas/*.sql | | migration diff | Generate/apply migrations from schema diff | | repl | Interactive REPL with app, client, conn in scope | | db query | Run a SQL statement against the local DB | | debug | Show runtime/config info |

Common flags:

lite init --pglite          # use PGlite instead of SQLite
lite dev --recreate         # wipe DB and reapply schema on start
lite db schema --diff       # diff current DB vs schemas/*.sql
lite db schema --sql        # print raw CREATE statements
lite migration diff         # preview migration plan
lite migration diff --execute --force   # apply, overriding data-loss warnings
lite db query "select count(*) from todos"
lite upgrade --dry-run          # rehearsal plus SQLite shim audit
lite upgrade --dry-run --json   # machine-readable shim audit output

Upgrade targets:

lite upgrade --target hosted  # default: create/migrate to hosted Supabase
lite upgrade --target local   # initialize/migrate local Supabase in the current directory
lite upgrade --target local --local-dir ../my-local-supabase

See UPGRADE.md for upgrade behavior, target differences, session migration, known gaps, and test strategy.

Telemetry

The lite CLI sends anonymous usage telemetry to help prioritize fixes and features. No personally identifiable information is collected: no file paths, project names, DB URLs, env values, hostnames, IPs, or stack traces. Only the command name, CLI flag presence (boolean, never values), runtime (node/bun/deno), node version, platform/arch, CI/agent/container detection, DB driver (sqlite/sqlite-postgres/pglite/postgres), DB location (file/memory/local/remote), and DB size bucket.

Opt out with any of:

lite --no-telemetry <cmd>
LITE_TELEMETRY=0 lite <cmd>
DO_NOT_TRACK=1 lite <cmd>     # https://consoledonottrack.com

Vite plugin

If your frontend uses Vite, skip the separate CLI + proxy setup. The @supabase/lite/vite plugin runs the supalite backend inline inside the Vite dev server, so one process serves both your app and the API.

// vite.config.ts
import { defineConfig } from "vite";
import { supalite } from "@supabase/lite/vite";

export default defineConfig({
   plugins: [supalite()],
});

Then from your frontend:

import { createClient } from "@supabase/supabase-js";

const client = createClient(
   import.meta.env.VITE_SUPABASE_URL,
   import.meta.env.VITE_SUPABASE_ANON_KEY,
);

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.

See examples/todo for a full Vite + React + Tailwind + RLS example, or examples/next-todo for the same pattern using Next.js App Router catch-all route handlers.

Project layout

lite init creates a Supabase-compatible directory layout:

supabase/
├── config.toml          # API port, auth settings, DB path, etc.
├── schemas/
│   └── schema.sql       # Postgres DDL, auto-translated to SQLite
├── seed.sql             # Seed data, applied after migrations
└── .temp/
    └── data.db          # SQLite database (git-ignored)

config.toml follows the Supabase CLI config format. Minimal example:

[api]
port = 54321

[db]
driver = "sqlite-postgres"    # or "sqlite" | "pglite" | "postgres"
url = "file:./supabase/.temp/data.db"

[db.migrations]
schema_paths = ["./schemas/schema.sql"]

[db.seed]
sql_paths = ["./seed.sql"]

[auth]
enabled = true
jwt_secret = "dev-secret-change-me"
jwt_expiry = 3600
enable_signup = true

[auth.email]
enable_confirmations = false

auth.jwt_secret: if omitted, auth falls back to the insecure placeholder "unsafe-secret-change-me" so local dev doesn't break. Always set your own for anything beyond throwaway local use.

Writing schemas

Write Postgres DDL in supabase/schemas/*.sql. When the DB driver is SQLite, DDL is translated on the fly (SERIAL → INTEGER PRIMARY KEY AUTOINCREMENT, NOW() → datetime('now'), JSONB → TEXT with a json_valid() check, and so on). Postgres-only features that don't translate (ranges, LATERAL, table inheritance) throw a descriptive error.

RLS works across all backends: on SQLite, policies are extracted from DDL and enforced at the application layer by rewriting the query AST; on PGlite/Postgres, native RLS is used. auth.uid(), auth.jwt(), and roles (anon, authenticated, service_role) resolve from the JWT.

Full translation reference: STATUS.md#postgres-to-sqlite-translation and app/POSTGRES-SQLITE-COMPAT.md.

Migrations

Imperative Postgres migrations live in supabase/migrations/*.sql (Supabase-CLI compatible — same filename format <14-digit-ts>_<name>.sql, same history table supabase_migrations.schema_migrations). On sqlite-postgres, pglite, and postgres drivers, write raw Postgres DDL — the runtime translates it on the fly. On the bare sqlite driver, write sqlite DDL in supabase/sqlite-migrations/*.sql instead.

lite migration new add_users    # create 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 db reset                   # drop everything, replay migrations, run seed

Migrations and declarative schemas coexist: lite dev and the Vite plugin apply pending migrations on boot, then run the declarative diff. RLS policies authored in migration files are picked up at request time.

Using @supabase/supabase-js

Two ways to get a client:

Over HTTP

import { createClient } from "@supabase/supabase-js";

const client = createClient("http://localhost:54321", "<anon-key>");

// database
const { data } = await client.from("todos").select("*");

// auth
await client.auth.signUp({ email: "[email protected]", password: "secret123" });
const { data: session } = await client.auth.signInWithPassword({
   email: "[email protected]",
   password: "secret123",
});

In-process (no network)

When you embed the app:

const client = app.getClient();
const { data } = await client.from("todos").select("*");

Queries route through app.fetch internally. Same API, no HTTP round trip.

Embedded / programmatic

Embed @supabase/lite in any Web-API-compliant runtime (Bun, Node, browser, and edge runtimes).

Bun / Node

import { App } from "@supabase/lite";
import { createConnection } from "@supabase/lite/sqlite";   // picks driver per runtime

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

Supported databases

| Runtime/DB | Driver | |--------------|----------------------------------| | Bun | bun:sqlite (auto) | | Node.js ≥ 22 | node:sqlite (auto) | | Browser | @sqlite.org/sqlite-wasm (auto) | | Workerd | @supabase/lite/workerd | | PGlite | @supabase/lite/pglite | | Postgres | @supabase/lite/postgres |

REPL

lite repl

Gives you an interactive session with app, client (supabase-js), conn, and db in scope. Built-in commands: .tables, .table <name>, .indexes, .config [path].

> await client.from("todos").select("*")
> .tables
> .table todos