tinbase

A pure-JS, Docker-free Supabase backend built on PGlite (Postgres compiled to WASM). It speaks the same wire protocols as hosted Supabase, so the official @supabase/supabase-js SDK works unchanged - REST, Auth, Storage, and Realtime.

One command, one small binary, real Postgres with Row Level Security - and 1:1 with Supabase's APIs and migration conventions.

Warning

Experimental. tinbase is young and moving fast - great for prototypes, local development, demos, and embedded/browser use. It is not meant for production usage yet.

npx tinbase start

• No Docker, no external services. One runtime dependency: @electric-sql/pglite.
• Real Postgres semantics. RLS policies, auth.uid(), triggers, FKs - it is Postgres.
• Two engines, one API. Default is PGlite (WASM Postgres - portable, browser-ready). --engine native runs an embedded native Postgres instead: ~59 MB of RAM at boot, PocketBase-class footprint, zero semantic differences.
• Supabase CLI migration conventions. Reads supabase/migrations/*.sql and supabase/seed.sql; tracks them in supabase_migrations.schema_migrations. Your migration files stay portable to hosted Supabase.
• Browser-ready core. Every service is a pure (Request) => Response fetch handler. In Node it's served over HTTP; in the browser you can hand it to supabase-js as a custom fetch and run the whole backend in-process (PGlite already runs in the browser via IndexedDB/OPFS).

Quick start

# in a project with a supabase/ directory (or none - it still boots)
npx tinbase start

#   API URL: http://127.0.0.1:54321
#   anon key: eyJ...
#   service_role key: eyJ...

Point the ordinary supabase-js client at it:

import { createClient } from '@supabase/supabase-js'

const supabase = createClient('http://127.0.0.1:54321', ANON_KEY)

await supabase.auth.signUp({ email: 'me@example.com', password: 'secret123' })
await supabase.from('todos').insert({ title: 'hello' })
const { data } = await supabase.from('todos').select('*, author:users(name)').eq('done', false)

supabase
  .channel('feed')
  .on('postgres_changes', { event: 'INSERT', schema: 'public', table: 'todos' }, console.log)
  .subscribe()

CLI

tinbase start      # boot the server (applies pending migrations first)
tinbase migrate    # apply pending migrations and exit
tinbase status     # list applied migrations
tinbase keys       # print anon / service_role keys
tinbase gen types  # print a TypeScript Database type for the schema
tinbase db reset   # wipe the database + storage, re-run migrations and seed
tinbase db diff    # DDL for schema changes not yet in migrations (-f <name> to save one)

  -p, --port <n>        port (default 54321; or TINBASE_PORT / PORT env)
      --dir <path>      project dir containing supabase/ (default cwd)
      --data-dir <path> PGlite data dir (default <dir>/.tinbase/db)
      --jwt-secret <s>  JWT secret (or TINBASE_JWT_SECRET)
      --memory          in-memory database, no persistence (wasm engine)
      --engine <e>      wasm (default) or native

Engines

• wasm (default): PGlite. Zero setup, runs anywhere Node runs - and in the browser. Its WASM heap uses ~575-650 MB RAM.
• native: embedded native Postgres 17. First run downloads platform binaries (~12 MB, from theseus-rs/postgresql-binaries, cached in ~/.cache/tinbase), then initdb with memory-lean settings. ~59 MB RAM at boot. Listens only on a private unix socket (0700 dir, trust auth) - never TCP. macOS/Linux on x64/arm64; on Windows use wasm.

Both engines run the identical bootstrap, migrations, RLS, and realtime CDC - the test suite passes on both (TINBASE_TEST_ENGINE=native npm test).

Single-binary build

npm run build:binary   # requires bun; emits dist-bin/tinbase (~57 MB)

./tinbase start        # that's the whole deployment

One compiled executable, no Node or npm on the target machine. It defaults to the native engine (Postgres binaries auto-download on first run, 12 MB) and serves everything - REST, Auth, Storage, Realtime WebSockets - at ~49 MB of RAM at boot (~66 MB under load). Runs under Bun's runtime via a Bun-native server (Bun.serve + built-in WebSockets); the same CLI on Node uses the node:http server.

Embedding (Node or browser)

import { createBackend } from 'tinbase'

const backend = await createBackend({
  // dataDir: 'idb://my-app'  <- browser persistence
  migrations: [{ name: '20240101000000_init', sql: 'create table notes (...)' }],
})

// supabase-js talks to it in-process - no HTTP server, no network
const supabase = createClient('http://localhost', backend.anonKey, {
  global: { fetch: (input, init) => backend.fetch(new Request(input, init)) },
})

Node-only helpers live in tinbase/node:

import { serve, FsStorageDriver, loadSupabaseProject } from 'tinbase/node'

const project = await loadSupabaseProject(process.cwd())
const backend = await createBackend({ ...project, storageDriver: new FsStorageDriver('./files') })
const server = await serve(backend, { port: 54321 })

What's implemented

Service	Endpoint	Coverage
REST (PostgREST)	/rest/v1	select with embedded resources (to-one, to-many, many-to-many via junction, nested, !inner, aliases, hints, casts, JSON paths), all common filter operators incl. or/and trees, full-text search, order/limit/offset (top-level and per-embed), single/maybeSingle, count, insert/bulk insert, upsert (merge/ignore), update, delete, Prefer handling, RPC (scalar, setof, void, filters on results), PostgREST-shaped errors
Auth (GoTrue)	/auth/v1	email/password signup + sign-in, anonymous sign-in, session refresh with rotation, getUser, updateUser, sign-out, admin user CRUD (service key), GoTrue-shaped errors. JWTs are HS256 via WebCrypto; passwords are PBKDF2
Storage	/storage/v1	bucket CRUD, upload (raw + multipart), download, public objects, signed URLs, signed upload URLs, list with folder entries, move/copy, remove, size/MIME limits. Metadata lives in storage.objects with RLS enforced; bytes go through a pluggable driver (fs in Node, memory anywhere)
Edge Functions	/functions/v1	supabase.functions.invoke() - Supabase-style Deno.serve(handler) functions (with Deno.env) run unchanged, as do export default handlers; loaded from supabase/functions/<name>/index.{ts,js,mjs} by the CLI or passed via createBackend({ functions }). Web-API functions work as-is; npm:/jsr:/URL imports still need bundling
Queues (pgmq)	pgmq.*	Message queues via a pure-SQL pgmq subset (create/send/read/pop/delete/archive, visibility timeouts). Call from SQL or supabase.schema('pgmq').rpc(...). No extension
Cron	cron.*	Scheduled jobs: select cron.schedule(name, '*/5 * * * *', 'sql') (also 'N seconds'); an in-process scheduler runs due jobs and logs to cron.job_run_details. No extension
Database Webhooks	config	Fire HTTP requests on table INSERT/UPDATE/DELETE with Supabase's exact payload (type/table/schema/record/old_record). Configured via createBackend({ webhooks }), backend.webhooks.register(), or supabase/webhooks.json. Built on the CDC pipeline — no extension needed
Studio (Admin UI)	/_/	A Supabase-Studio-style dashboard (React + Radix + Tailwind): Table Editor with full row CRUD, SQL editor, user management, bucket/object CRUD, and a database overview. One self-contained HTML file (works in the single binary); log in with the service_role key
Realtime	/realtime/v1	Phoenix protocol (v1 JSON and v2 array/binary serializers), postgres_changes (INSERT/UPDATE/DELETE, filters) fed by triggers + pg_notify, broadcast (incl. binary payloads), presence. WebSocket server is a ~150-line RFC 6455 implementation - no ws dependency

RLS works like real Supabase

Every REST/storage request runs inside a transaction with SET LOCAL role and request.jwt.claims, so policies like this behave identically to hosted Supabase:

create policy "own rows" on todos
  for all to authenticated
  using (user_id = auth.uid()) with check (user_id = auth.uid());

Studio

tinbase ships with a built-in dashboard at /_/ - the same shape as Supabase Studio:

• Table Editor - browse tables with pagination and row counts; insert, edit, and delete rows (type-aware, primary-key based)
• SQL Editor - run arbitrary SQL with result grids and Postgres error details
• Authentication - list, create, delete users and reset passwords
• Storage - create/delete buckets, upload/delete objects, toggle public access
• RLS Policies - list, create, and drop policies per table
• Database - stats, migrations, functions, and triggers

It is a React app compiled to a single self-contained HTML file, so it also works inside the single binary. Sign in with the service_role key printed at startup.

Extensions

The extensions Supabase enables by default are available out of the box, so migrations that call uuid_generate_v4(), gen_random_uuid(), crypt(), citext, pg_trgm, and friends just work: uuid-ossp, pgcrypto, citext, pg_trgm, ltree, hstore, fuzzystrmatch. They live in the extensions schema (like hosted Supabase) and are on the search path, so both qualified and unqualified calls resolve.

Typed clients

Generate a Supabase-shaped Database type from the live schema, the same as supabase gen types typescript:

tinbase gen types typescript > database.types.ts

import { createClient } from '@supabase/supabase-js'
import type { Database } from './database.types'
const supabase = createClient<Database>(url, anonKey)  // fully typed queries

Emits Tables (Row/Insert/Update/Relationships), Views, Functions, and Enums.

Footprint: tinbase vs PocketBase vs Supabase local

Measured on an Apple Silicon Mac (48 GB), macOS 15. Same workload for all three: boot with one migrated table, then 1,000 single-row inserts followed by 1,000 filtered list queries. Memory is physical footprint (vmmap) for native processes and the sum of docker stats for containers. Reproduce with bench/footprint.ts; raw numbers in bench/results.json.

	tinbase (single binary)	tinbase (native, Node)	tinbase (wasm)	PocketBase v0.39.5	Supabase local (CLI 2.40)
Database	real Postgres 17 + RLS	real Postgres 17 + RLS	real Postgres (PGlite) + RLS	SQLite	Postgres 17
Runtime memory at boot	49 MB	59 MB	~610 MB¹	15 MB	1,441 MB
Runtime memory after workload	66 MB	100 MB	~640 MB¹	24 MB	1,626 MB
Data on disk (1k rows)	39 MB	39 MB	40 MB	7 MB	70 MB
Install size	92 MB (no runtime needed)	36 MB²	27 MB²	30 MB	2,291 MB³
Processes	2 (tinbase + postgres)	2 (node + postgres)	1	1	12 containers + Docker
1,000 inserts	0.4 s	0.5 s	0.8 s	0.3 s	1.1 s
1,000 filtered reads	0.3 s	0.4 s	0.9 s	0.3 s	1.0 s

¹ The wasm figure is essentially PGlite's WASM heap, which measures anywhere in ~575–650 MB depending on GC timing at the sample — treat it as a band, not a point. It does not shrink under load. The API layers add only single-digit MB. Use wasm where portability matters (browser, one-dependency install); deploy the native engine or single binary on servers. ² Native: unpacked Postgres 17 binaries + dist. Wasm: dist + @electric-sql/pglite. Both exclude the Node runtime you already have. ³ Sum of the Docker image sizes the default local stack runs, excluding Docker Desktop itself.

How to read this honestly:

• vs Supabase local: same SDK, same APIs, ~16-24x less memory (native engine / single binary), ~25-65x smaller install, 2 processes instead of a 12-container stack, and boots in ~2 s instead of a minute. That's the entire point of the project.
• vs PocketBase: the single binary lands in PocketBase's weight class - ~2.7x the RAM (66 vs 24 MB under load), one downloadable file, no runtime prerequisite - while running real Postgres (RLS, jsonb, FKs, triggers) behind Supabase's exact wire APIs, so your code and migration files move to hosted Supabase unchanged. PocketBase is still the lightest option if you don't need any of that.
• The wasm engine trades memory for portability: its ~575-650 MB is PGlite's WASM heap (the API layers add single-digit MB), and it's the only engine that runs in a browser. On servers, use the native engine or single binary.

How complete is it?

Rough coverage of the supabase-js SDK surface, measured against what each sub-library can express (all "supported" claims are exercised by the test suite):

Module	Coverage	Supported	Missing
Database (postgrest-js)	~85%	full filter grammar, embeds (to-one/to-many/m2m/nested/!inner), JSON paths, upsert, count, single/maybeSingle, RPC	aggregates in select, full spread embeds, .explain(), .csv(), geojson
Auth (auth-js)	~80%	email/password, anonymous sign-in, OTP + magic links + password recovery (pluggable mailer), OAuth providers (Google/GitHub presets + generic) with PKCE and identity linking, refresh rotation, user updates, admin CRUD	MFA, SSO/SAML, phone auth
Storage (storage-js)	~80%	buckets, upload/download, signed URLs + signed uploads, list/move/copy/remove, size/MIME limits	resumable (TUS) uploads, image transformations
Realtime (realtime-js)	~85%	postgres_changes with filters + per-subscriber RLS filtering (INSERT/UPDATE), broadcast (incl. binary), presence, v1+v2 serializers	per-row DELETE RLS, private channel auth, DB-triggered broadcast
Edge Functions (functions-js)	~70%	invoke(); Deno.serve/Deno.env-style functions run unchanged + export-default; auth context, project-dir loading	npm:/jsr:/URL import resolution, supabase functions deploy
Type generation	~85%	tinbase gen types typescript → Database type (Tables/Views/Functions/Enums/Relationships)	composite-type args, multi-schema output

Overall: roughly 80% of the supabase-js SDK surface - and ~90% of what a typical CRUD + auth + storage + realtime app actually calls.

Beyond the client SDK, the local platform features real projects depend on also work: type generation, RLS (enforced on REST, Storage, and realtime), database webhooks, cron, queues (pgmq), the Studio dashboard, and Supabase-CLI migration conventions (db reset / db diff). The remaining gaps are OAuth logins' provider variety, the Deno edge-function runtime, and pgvector (needs an extension binary).

Known gaps

• postgres_changes applies RLS per subscriber for INSERT/UPDATE (the row is re-checked by primary key as that user). DELETE events can't be re-queried (the row is gone), so they are delivered to authenticated/service subscribers but not filtered per-row — hosted Supabase does this via WAL-level policy evaluation (WALRUS).
• Spread embeds (...rel(col)) support flat column lists only; aggregate functions in select are not implemented.
• Auth: OAuth works for any OAuth2/OIDC provider (Google & GitHub have built-in presets; configure via TINBASE_OAUTH_<PROVIDER>_CLIENT_ID/_CLIENT_SECRET). Still missing: MFA, SSO/SAML, phone auth. OTP/magic-link/recovery emails go through a pluggable mailer (default logs to console).
• pg_notify payloads cap at ~8 kB - realtime events for larger rows arrive with record: null and an errors entry, like Supabase's "payload too large".
• One writer at a time: PGlite is single-connection, and the native engine currently serializes requests over one connection for parity (a connection pool is a straightforward future upgrade). Fine for dev tools and small apps, not for high-concurrency production.

Tests

53 integration tests + 4 realtime e2e tests run the real @supabase/supabase-js against the backend (REST via in-process fetch, realtime over actual WebSockets):

npm test

Roadmap

tinbase aims to be a local, Docker-free replacement for supabase start where almost everything just works. The North Star, the in-scope/out-of-scope line, the current coverage table, and the phased plan live in ROADMAP.md.

Why

tinbase was built for lifo - a project that maps Linux APIs into the browser - to let Expo apps run fully in the browser with full-stack capability (database, auth, storage, realtime, no server). It is part of RapidNative. That origin drives the architecture:

1. Every service is a pure fetch handler and the default engine is Postgres compiled to WASM, so the whole backend can run in-process inside a browser tab.
2. The same design makes a lighter Supabase for local dev and self-contained apps - npx tinbase start instead of Docker Compose.