> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pylonsync.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Pylon vs. Supabase

> Supabase is Postgres-as-a-platform. Pylon is one binary. Here's when each wins.

[Supabase](https://supabase.com) is a well-known open-source Firebase alternative. It's a managed Postgres + GoTrue + PostgREST + Realtime + Storage stack with web/mobile SDKs. Pylon hits the same problem space with a different shape.

## TL;DR

* **Choose Supabase** if you want full Postgres SQL surface, you're comfortable with multi-service deployments, or you need pgvector + edge functions + storage in one place.
* **Choose Pylon** if you want one binary on a VPS, native faceted search, or a tighter integration between sync and policies.

## Architecture

|                  | Pylon                                           | Supabase                                                                                      |
| ---------------- | ----------------------------------------------- | --------------------------------------------------------------------------------------------- |
| Services / ports | 1 service, 1 port                               | 5+ services (Postgres, GoTrue, PostgREST, Realtime, Storage, Studio, optional Edge Functions) |
| Default DB       | SQLite                                          | Postgres                                                                                      |
| Backed by        | Rust server + a bundled Bun runtime for your TS | Postgres + Go + Elixir + Deno                                                                 |
| Self-host        | binary + Bun + `systemctl`                      | Docker Compose stack                                                                          |

Supabase is a curated stack of best-in-class single-purpose services. Pylon is one binary that does many of those things itself. Both are valid; pick the trade-off.

## Same shape

Both ship:

* Real-time subscriptions over WebSocket
* Built-in auth (magic links, password, OAuth)
* File storage
* Row-level access control (RLS for Supabase, policies for Pylon)
* Web SDK + mobile SDKs
* Self-hostable, FOSS-licensed
* Managed cloud option

## Where Supabase is better

* **Full Postgres** — every Postgres feature works: CTEs, window functions, JSONB operators, materialized views, foreign data wrappers, GIST indexes, partitioning. Pylon's query layer is intentionally limited.
* **pgvector** — first-class vector search via Postgres extension. Pylon has the `vector_search` plugin (in-memory), but for million-scale vectors Supabase wins.
* **PostgREST auto-API** — every table becomes a REST endpoint automatically. Pylon also auto-generates these (`/api/entities/<name>`) but PostgREST has 8 years of battle-testing.
* **Edge Functions** — globally distributed Deno runtime; nice for latency-sensitive endpoints. Pylon functions run in your single binary's region.
* **Larger ecosystem** — more libraries, more tutorials, more StackOverflow answers, more job postings.
* **Database UI** — Supabase Studio is excellent for SQL exploration. Pylon Studio is more focused on entity inspection.

## Where Pylon is better

* **One service** — one binary plus Bun, one port, one config file. Compare to a Docker Compose stack.
* **Faceted search** — Supabase has Postgres `tsvector` for FTS but no native facets ([docs](https://supabase.com/docs/guides/database/full-text-search)). Pylon ships FTS5 + roaring-bitmap facet counts.
* **Game shards** — `Shard<S: SimState>` for tick-based multiplayer (authored in Rust, with a `useShard` client hook; there's no TypeScript shard-authoring API yet). Supabase has nothing equivalent.
* **In-process mutations** — Pylon mutations run as typed handler-level transactions in the app process. Supabase Edge Functions are separate Deno functions that call Postgres over HTTP or a database client, so you manage transaction boundaries explicitly.
* **CRDTs** — Pylon integrates Loro for collaborative editing. Supabase Realtime gives you Postgres Changes, Broadcast, and Presence; CRDT-backed collaborative data is still something you bring yourself.
* **Plugin system** — built-in plugins for cross-cutting concerns such as search, files, presence, audit logs, and payments. Supabase has extensions, but they're Postgres extensions, not framework-level.
* **TypeScript declarative schema** — `entity("User", {...})` in TS. Supabase uses SQL migrations; you can codegen TS types from them but the source of truth is SQL.

## Functions

|                                | Pylon                    | Supabase                                    |
| ------------------------------ | ------------------------ | ------------------------------------------- |
| Runtime                        | Bun (in-process)         | Deno (separate Edge Functions)              |
| Type sharing with client       | After codegen            | Manual or via `supabase gen types`          |
| DB access                      | Direct (`ctx.db`)        | Supabase JS over HTTP or explicit DB client |
| Atomic with caller transaction | ✅ for mutations          | Manual transaction management               |
| Latency                        | In-process for app logic | Region and network dependent                |

Pylon's "mutation = transaction" model is a meaningful difference. Throw inside a `mutation` and everything rolls back. Supabase Edge Functions can do this with explicit transaction handling, but it's not the default shape.

## Pricing

|                   | Pylon                                             | Supabase                             |
| ----------------- | ------------------------------------------------- | ------------------------------------ |
| Self-host         | Your infra                                        | Your infra                           |
| Hobby / prototype | Pylon Cloud Hobby or self-hosted infra            | Supabase free tier                   |
| Production hosted | Pylon Cloud plan + machine compute                | Supabase Pro tier + add-ons          |
| Large usage       | Team plan + machine compute, or self-hosted infra | Higher tiers, add-ons, or enterprise |

Supabase's free tier is generous for prototypes and includes managed Postgres. Pylon Cloud includes the application runtime, sync, domains, deploys, and machine hosting; self-hosted Pylon puts those costs on your own infrastructure.

## Migrating from Supabase

If you're moving an existing Supabase app:

| Supabase                          | Pylon                                                                       |
| --------------------------------- | --------------------------------------------------------------------------- |
| SQL schema + RLS                  | `pylon.manifest.json` entities + policies                                   |
| `supabase.from('todos').select()` | `useQuery("Todo")`                                                          |
| `supabase.auth.signInWithOtp()`   | `startMagicCode(email)` + `verifyMagicCode(...)`                            |
| Storage buckets                   | `/api/files/init` → direct PUT → `/api/files/confirm` (Stack0 / S3 / local) |
| Edge Functions                    | `mutation`/`action` in `functions/*.ts`                                     |
| Realtime subscriptions            | `useQuery` (server-authoritative) or `subscribeCrdt` (collaborative)        |
| `pg_net` outbound HTTP            | `fetch` inside an action (with `net_guard` plugin for SSRF defense)         |
| `auth.users`                      | Pylon's `User` entity (you control the shape)                               |

The biggest delta today: Pylon's entity API is the data API. If your app relies on raw Postgres queries (CTEs, window functions, materialized views, pgvector), you have two options:

1. **Express the logic in a Pylon `action`** in TypeScript — for joins and aggregates this is usually fine, and you keep the type-safe entity model.
2. **Run a sidecar against the same Postgres** — Pylon doesn't lock the DB; you can connect any tool that speaks Postgres for analytics, BI, or specialized queries.

Raw SQL exposure from inside `action` handlers (e.g. `ctx.pg.query(sql, params)` in `postgres-live` builds) is on the roadmap; there's no architectural reason to gate-keep it. For now, most app workloads fit the entity API; if yours needs more Postgres surface, Supabase has a head start.

## Honest weakness

Supabase's Postgres-native data layer is more flexible than Pylon's for analytics, complex queries, and integrations with tools that speak SQL (Metabase, Hex, Mode, Retool). If your data model needs to interop with a wider data ecosystem, Supabase's "it's just Postgres" is genuinely valuable.

## Both / and

Pylon supports Postgres as a backing store via the `postgres-live` feature. You can run Pylon as the application layer (entities, policies, functions, sync) on top of an existing Supabase Postgres instance. Some teams do this to keep Supabase Studio's SQL UI for exploration while getting Pylon's sync engine and facets for the app.