<div align="center"> <img src="docs/assets/mekka-readme-logo.png" alt="Mekka" width="112" />

MEKKA

BACKEND INFRASTRUCTURE THAT FITS IN YOUR HEAD.

SQLite through Bun's native driver. Embedded Studio. Scoped Agent Access.

DATABASE · AUTH · STORAGE · REALTIME · STUDIO · SAFE AGENTS

Why Mekka · Architecture · Studio · Roadmap · Run it · Security </div>

<br />

<p align="center"> <img src="docs/assets/studio/table-editor.jpg" alt="Mekka Studio table editor running against a local SQLite project" width="100%" /> _{Real Studio. Real local SQLite project. No mockup.} </p>

---

Less Platform. More Product.

Most products need durable data, auth, files, realtime, and a control surface. They do not need PostgreSQL infrastructure as a lifestyle.

<table> <tr> <td width="33%" valign="top"><strong>SQLite-native</strong><br />_{Ordinary database files through Bun's native driver.}</td> <td width="33%" valign="top"><strong>One Studio</strong><br />_{Data, users, files, branches, and approvals in one place.}</td> <td width="33%" valign="top"><strong>Agents with limits</strong><br />_{Read by default. Preview first. Production only after approval.}</td> </tr> </table>

Mekka is the Supabase killer for teams that need the product surfaces, not the PostgreSQL fleet.

Why Mekka

Supabase is broad by design. Mekka is deliberately smaller: keep the useful backend surface, remove the machinery most projects never touch, and make agent safety part of the architecture.

	Mekka	Supabase	Plain SQLite
Data plane	SQLite through Bun's native driver	PostgreSQL	SQLite
Studio	Bundled private fork	Hosted or self-hosted	Bring your own
Backend surface	Data, Auth, Storage, Realtime	Broad PostgreSQL platform	Database only
Agent access	Native scoped MCP	Configurable MCP	Application-defined
Write path	Preview → exact SQL → approval → CAS promotion	Configuration-dependent	Application-defined
Self-host shape	Bun/Node services + SQLite files	Multi-service Postgres stack	Embedded database

Choose Supabase when deep PostgreSQL compatibility is the requirement.

Choose Mekka when shipping with less infrastructure is the requirement.

<details> <summary><strong>Comparison notes and sources</strong></summary>

Mekka implements a selected supabase-js Data API subset. It does not claim parity for PostgreSQL arrays, ranges, native RLS, extensions, casts, or every PostgREST feature.

Supabase references: Database, MCP Server, and Self-hosting.

</details>

Safe Agent Changes

Agents get room to work, not room to improvise in production.

PROMPT → SCOPED TOKEN → ISOLATED PREVIEW → VALIDATION → EXACT SQL → APPROVAL → PRODUCTION

Read	Write
Default capability: mcp:read	Requires explicit Studio opt-in
Maximum five-minute opaque token	Bound to a disposable preview branch
Full tenant identity attached	No production execute scope
Revoked with the originating session	One-time artifact-bound approval secret

<details> <summary><strong>See the complete trust chain</strong></summary>

1. Studio issues an opaque Agent Access token with a maximum five-minute lifetime.
2. The grant is bound to organization, project, environment, branch, generation, and auth session.
3. Write access creates an isolated preview instead of granting production execution.
4. Mekka records the migration artifact, exact SQL, schema hashes, and destructive-operation flag.
5. Studio approval issues a short-lived, one-time secret bound to that exact artifact.
6. Production promotion atomically consumes the secret and rechecks authorization and schema CAS.

An agent typo can damage its disposable preview. It cannot silently rewrite production.

</details>

<details> <summary><strong>Universal MCP configuration</strong></summary>

{
  "mcpServers": {
    "mekka": {
      "type": "http",
      "url": "https://mekka.example.com/mcp",
      "headers": {
        "Authorization": "Bearer <temporary-agent-access-token>"
      }
    }
  }
}

</details>

Architecture

Every request carries one unambiguous identity:

organization / project / environment / branch / generation

Developer / AI Agent
         │
         │ HTTPS + scoped five-minute token
         ▼
┌──────────────────────┐
│     MCP Gateway      │  body limits · rate limits
└──────────┬───────────┘
           ▼
┌──────────────────────┐
│    Token Verifier    │  session · tenant · TTL
└──────────┬───────────┘
           │
     read  │  write opt-in
           │        └──────► isolated preview
           │                   │ plan · apply · test
           │                   ▼
           │              exact SQL approval
           ▼                   │
┌──────────────────────┐◄──────┘
│     sqlite-meta      │  manifest · compiler · audit
└──────────┬───────────┘
           ▼
┌──────────────────────┐
│   SQLite Database    │  prepared statements
└──────────────────────┘

<details> <summary><strong>Follow a normal query</strong></summary>

Client / Studio / MCP
  → authentication
  → rate and size limits
  → tenant-bound capabilities
  → typed query or migration artifact
  → policy rewrite
  → prepared SQLite statement
  → storage adapter
  → response, metrics, and audit

</details>

Studio

One control surface for the backend paths people actually use.

<table> <tr> <td width="50%"><img src="docs/assets/studio/sql-editor.jpg" alt="Mekka SQL editor" /></td> <td width="50%"><img src="docs/assets/studio/auth-users.jpg" alt="Mekka Auth users administration" /></td> </tr> <tr> <td align="center">_{<strong>SQL EDITOR</strong>}</td> <td align="center">_{<strong>AUTH USERS</strong>}</td> </tr> <tr> <td width="50%"><img src="docs/assets/studio/agent-access.jpg" alt="Mekka Agent Access registration and token controls" /></td> <td width="50%"><img src="docs/assets/studio/auth-providers.jpg" alt="Mekka authentication provider configuration" /></td> </tr> <tr> <td align="center">_{<strong>AGENT ACCESS</strong>}</td> <td align="center">_{<strong>AUTH PROVIDERS</strong>}</td> </tr> </table>

Built In

Surface	What ships
Data + SQLite	Typed reads and mutations, tables, rows, indexes, migrations, schema diff, backup, and restore
Auth + Storage	Sessions, JWT/JWKS, OAuth, audit, local/S3 objects, signed reads, resumable uploads, and quotas
Realtime + Branching	Changefeeds, private channels, presence, preview snapshots, validation, restore points, and CAS promotion
Studio + MCP	Visual administration, read tools by default, preview mutations, exact-SQL approval, and production promotion

Run It

Four commands. Two local services. No external database to provision.

git clone https://github.com/yiaany/mekka.git
cd mekka
bun install --frozen-lockfile
bun run dev

Open http://127.0.0.1:8082.

Service	Address	Purpose
Studio	127.0.0.1:8082	Browser control surface and same-origin API
sqlite-meta	127.0.0.1:3001	Data, Auth, branches, approvals, and MCP backend

Requires Bun 1.3.14, Git, and a current browser. Local state lives in apps/studio/.local/ and is ignored by Git and Docker contexts.

<details> <summary><strong>Production deployment</strong></summary>

The production shape is one public Studio endpoint, one loopback backend, and one persistent data directory.

Variable	Purpose
MEKKA_STUDIO_ACCESS_TOKEN	Protects Studio; minimum 24 characters
MEKKA_AUTH_SESSION_SECRET	Auth and Agent Access HMAC secret; minimum 32 random characters
MEKKA_PUBLIC_URL	Public origin used by Auth and MCP metadata
NEXT_PUBLIC_SITE_URL	Public browser origin baked into Studio
SQLITE_META_DATA_DIRECTORY	Absolute persistent data directory
MEKKA_RESEND_API_KEY	Server-only production email credential
MEKKA_AUTH_EMAIL_FROM	Verified Auth email sender

bun run build

MEKKA_STUDIO_ACCESS_TOKEN="replace-with-a-random-token" \
MEKKA_AUTH_SESSION_SECRET="replace-with-a-random-secret" \
MEKKA_PUBLIC_URL="https://mekka.example.com" \
SQLITE_META_DATA_DIRECTORY="/absolute/path/to/mekka-data" \
bun run --cwd apps/studio start:production

Backend listeners remain loopback-only. Terminate TLS at a trusted reverse proxy, persist the data directory, and test restores before storing valuable data.

</details>

<details> <summary><strong>Docker build</strong></summary>

docker build \
  --build-arg NEXT_PUBLIC_SITE_URL=https://mekka.example.com \
  --build-arg NEXT_PUBLIC_MEKKA_GATEWAY_URL=https://mekka.example.com \
  -f apps/studio/Dockerfile \
  -t mekka-studio .

</details>

Security

Self-hosted is a deployment model, not a security model.

Boundary	Guarantee
Identity	Authentication precedes authorization; every check uses the full tenant tuple
Agent access	Read-only by default; writes stay preview-bound until explicit approval
SQL	User values are prepared parameters; public SQL is constrained and allowlisted
Secrets	Tokens, SQL values, provider credentials, and secrets are not logged
Mutations	Durable idempotency, audit outbox, bounded payloads, and schema CAS
Recovery	Destructive schema changes require a verified checkpoint

See SECURITY.md for private vulnerability reporting and docs/runbooks/ for recovery procedures.

<details> <summary><strong>Additional security guarantees</strong></summary>

• Logout, password reset, expiry, and session deletion invalidate Agent Access.
• Mutation request bodies, MCP messages, query rows, and responses are bounded.
• Production promotion rechecks secret expiry inside the mutation lock.
• Unexpected errors become sanitized envelopes without stack traces.
• Identifiers resolve through the schema manifest instead of user-provided SQL fragments.

</details>

Ecosystem Roadmap

<div align="center">

The local engine was the opening move.

The target is the fastest agent-native database platform from laptop to global edge.

Mekka is not building a smaller Supabase clone. We are making heavyweight database infrastructure optional, then taking the control plane, the agent workflow, and the developer experience further.

</div>

<table> <tr> <td width="25%" valign="top"> _{PHASE 1.0}<br /> <kbd>SHIPPED</kbd><br /><br /> <strong>LOCAL CORE</strong><br /><br /> Bun + SQLite<br /> Embedded Studio<br /> Scoped MCP<br /> Guarded promotion </td> <td width="25%" valign="top"> _{PHASE 1.5}<br /> <kbd>COMING NEXT</kbd><br /><br /> <strong>PGLITE TRACK</strong><br /><br /> In-process Postgres<br /> WASM portability<br /> JSONB workflows<br /> pgvector target </td> <td width="25%" valign="top"> _{PHASE 2.0}<br /> <kbd>ADAPTER TRACK</kbd><br /><br /> <strong>LIBSQL PLANE</strong><br /><br /> Remote adapter<br /> Replicated reads<br /> Primary write routing<br /> Managed clones </td> <td width="25%" valign="top"> _{PHASE 3.0}<br /> <kbd>PLANNED</kbd><br /><br /> <strong>MEKKA CLOUD</strong><br /><br /> Serverless orchestration<br /> Autosuspend<br /> PR databases<br /> Multi-region control </td> </tr> <tr> <td align="center"><strong>PROVE IT</strong></td> <td align="center"><strong>EXPAND IT</strong></td> <td align="center"><strong>DISTRIBUTE IT</strong></td> <td align="center"><strong>OWN THE CATEGORY</strong></td> </tr> </table>

Supabase made backend platforms accessible. Mekka is making the old platform weight obsolete.

Where The Platform Goes

Engine layer	Control layer	Execution layer	Developer layer
Bun SQLite today	Tenant-aware orchestration	Isolated TypeScript functions	Studio and CLI workflows
PGlite compatibility track	Branch and replica topology	Realtime mutation streams	PR preview databases
libSQL/Turso adapter track	Autosuspend and placement	Agent-safe plugin runtime	Engine choice per project

<details> <summary><strong>libSQL distributed data plane</strong></summary>

The next SQLite-shaped engine track is a real remote adapter for libSQL and Turso, not a renamed HTTP client. The adapter must pass Mekka's storage, migration, branching, credential, and failure conformance contracts before it can carry production traffic.

Targets:

• Read replicas close to applications and agents, with writes routed to the primary.
• Managed database clones and scoped credentials through verified Turso platform primitives.
• The same typed API, Studio, MCP scopes, audit trail, and promotion workflow across local and remote projects.
• Dense tenant isolation without keeping every inactive database hot in memory.

Upstream replication and managed-clone primitives are verified. The product adapter and its credentials are not implemented yet. See docs/engine-capabilities/branching.md.

</details>

<details> <summary><strong>PGlite compatibility engine</strong></summary>

Some teams need PostgreSQL semantics without volunteering to operate PostgreSQL servers. The PGlite track targets a WASM-backed, in-process engine option with the same Mekka control surface.

Targets:

• PostgreSQL-compatible local and preview workflows without Docker as a baseline requirement.
• JSONB and pgvector-compatible workflows for memory, embeddings, retrieval, and agent workloads.
• Engine capability negotiation instead of pretending SQLite and PostgreSQL have identical semantics.
• One Studio and one agent protocol across both engine families.

PGlite support is roadmap work. No production adapter is claimed today.

</details>

<details> <summary><strong>Mekka Cloud, previews, and plugin runtime</strong></summary>

The hosted product is designed around databases that wake when needed, disappear from memory when idle, and become disposable infrastructure whenever a pull request or agent task needs isolation.

Targets:

• Autosuspend with a single-digit-millisecond resume target for warm platform paths.
• Disposable PR and CI databases with a sub-200ms orchestration target where the engine permits it.
• Bun-isolated TypeScript functions executing beside the selected data plane.
• Plugins for engine adapters, object stores, Auth providers, agent tools, and deployment hooks.
• Realtime mutation broadcasting without forcing every engine through heavyweight WAL parsing.

These numbers are engineering targets, not current service guarantees. Hosted Cloud, edge execution, and the general plugin SDK are planned rather than released.

</details>

The strategy is simple: win local development, expand engine choice, distribute the data plane, then ship the cloud platform built for software teams where agents are first-class operators.

Developer Reference

<details> <summary><strong>Commands</strong></summary>

Command	Purpose
bun run dev	Start local Studio and sqlite-meta
bun run test	Run the core Bun test matrix
bun run test:workspaces	Run compatible workspace suites
bun run test:studio:fork	Run Mekka Studio integration assertions
bun run lint	Run Biome lint checks
bun run typecheck	Typecheck core project references
bun run typecheck:studio	Typecheck Studio and route contracts
bun run build	Build packages and production Studio
bun run smoke:studio:production	Exercise Studio, Auth, SQLite, MCP, approval, and promotion
bun audit	Check dependencies for known advisories
bun run check	Run the complete release gate

</details>

<details> <summary><strong>Repository map</strong></summary>

apps/
  gateway/             REST, Storage, Realtime, compatibility, MCP mount
  health-service/      Independent health-service example
  mcp/                 Resources, tools, transport, mutation workflow
  sqlite-meta/         SQLite, Auth, branches, approvals, Agent grants
  studio/              React control surface and production server

packages/
  auth-core/           Sessions, JWT/JWKS, OAuth, refresh rotation
  branch-core/         Preview lifecycle and guarded promotion
  migration-engine/    Migration artifacts, checkpoints, restore
  policy-engine/       Row and field authorization
  protocol/            Tenant identity, capabilities, errors
  query-ast/           Validated Data API query representation
  realtime-core/       Changefeeds, channels, presence
  schema-manifest/     Stable SQLite schema contracts
  sqlite-compiler/     Prepared statement compiler
  storage-core/        SQLite adapter and object storage
  studio-domain-sdk/   Typed Studio/backend boundary

</details>

<details> <summary><strong>Compatibility and upstream provenance</strong></summary>

Compatibility is tested, never assumed. Unsupported PostgreSQL behavior returns explicit errors.

• apps/gateway/SUPABASE_DATA_COMPATIBILITY.md
• apps/sqlite-meta/COMPATIBILITY.md
• apps/studio/UPSTREAM.md

Mekka Studio contains code derived from Supabase Studio under Apache License 2.0. Upstream provenance and the reproduced license remain in apps/studio/UPSTREAM.md and apps/studio/UPSTREAM_LICENSE.

</details>

Status And License

Mekka is under active development. Passing tests cover reviewed paths; production deployments still require monitoring, backups, restore tests, and independent security review.

Source is available under the Mekka Business License 2.0. This is not an OSI-approved open-source license. See LICENSE.md for the controlling terms.