npx mekka

Why Mekka exists

Mekka explores a compact backend surface for people and agents working on the same application. The current release runs on Bun and supports two SQLite-compatible data profiles: a local Bun SQLite database for development and an authenticated remote libSQL primary for self-hosted deployments. A typed data API, Studio, Auth, policy, migrations, Storage, Realtime primitives, and scoped MCP access ship in the same repository.

The project is experimental and targets controlled local development and self-hosted beta evaluation. It does not claim full Supabase or PostgreSQL compatibility.

What runs today

The remote profile does not silently fall back to a project .sqlite file. If libSQL authentication, routing, or policy resolution fails, the request fails.

Every request carries the full tenant identity, and every user value stays a prepared-statement parameter. That's the contract:

Deep PostgreSQL compatibility still belongs on PostgreSQL. Mekka rejects unsupported behavior instead of faking it. Teams that need native RLS, stored procedures, ranges, or a large extension catalog should use PostgreSQL directly.

Request path

sequenceDiagram
    participant C as Client / Studio / MCP
    participant G as Gateway
    participant A as Auth (ES256 JWT)
    participant P as Policy Engine
    participant S as Schema Manifest
    participant X as SQLite Compiler
    participant DB as Bun SQLite / remote libSQL
    participant R as Realtime

    C->>G: request + tenant headers + bearer token
    G->>A: authenticate caller, verify signature, expiry, tenant
    A-->>G: TenantContext + bounded capabilities
    G->>P: capability check for this tenant
    G->>S: resolve schema manifest, validate table and columns
    G->>X: compile validated query to one prepared statement
    G->>DB: execute bounded, parameterized
    DB-->>G: result
    G->>R: append changefeed event
    G-->>C: result, audit, metrics

Auth happens before permissions. The backend resolves table and column names through the schema manifest, binds user values as parameters, applies policy, and executes one prepared statement. It never parses user SQL directly: the constrained query dialect becomes an AST first, then a compiled statement, then a bounded execution.

Mutations carry idempotency keys. Payloads, results, uploads, queues, and Realtime buffers have hard limits. Unsupported operations return an explicit error instead of an approximation. Errors don't carry secrets, SQL values, or stack traces.

The default backend binds 127.0.0.1:3001, Studio serves 127.0.0.1:8082. Put a trusted TLS reverse proxy in front of Studio, persist the control-plane data directory, and run a restore before trusting a backup. In the libSQL profile, the user database runs separately behind its own authenticated HTTPS endpoint.

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" \
NEXT_PUBLIC_SITE_URL="https://mekka.example.com" \
SQLITE_META_DATA_DIRECTORY="/absolute/path/to/mekka-data" \
bun run --cwd apps/studio start:production

Docker builds are available:

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 .

What's inside

Each subsystem ships in the repo and works against the same local project. Open any of them to see what it actually does.

• Tables, columns, indexes, migrations, schema hashes, checkpoints, backup, and restore
• Tables and columns resolve through a versioned schema manifest; values always bind as parameters
• Reads compile to one prepared statement, bounded by row, byte, and timeout caps
• Writes are idempotent via a SHA-256 fingerprint and reusable keys
• MEKKA_DATA_ENGINE selects local SQLite, remote libSQL, or the optional embedded-replica profile
• Remote mode uses authenticated libSQL directly and refuses accidental local user-data fallback

• better-auth with email OTP, password reset, and sessions
• ES256 access tokens with a published JWKS and a short expiry; verifier applies clock tolerance
• HttpOnly session cookie with rotating refresh
• Google and GitHub OAuth, plus a local verification-code endpoint for development

• Local filesystem and S3-compatible object providers behind one interface
• Checked checksums, bounded reads, signed read grants with TTL, and reconciliation
• Resumable upload subset with leases and cleanup
• Quotas per bucket and per object, MIME allowlist, and normalized safe paths

• Transactional SQLite journal drives changefeeds with a resume cursor and ack
• Policy-projected delivery: subscribers only see rows their policy allows
• Private channels, Broadcast, and Presence in one Bun runtime
• Bounded socket payloads and an idle timeout

• Short-lived preview branches with their own Auth and credential lifecycle
• One validated migration per preview lifecycle, schema-CAS promotion, and restore points
• Durable retries and TTL cleanup of stale previews
• Self-hosted libSQL intentionally returns unsupported for write-mode MCP previews; Turso-backed preview lifecycle is a separate profile

• Table Editor, restricted SQL Editor, Auth users/providers/configuration, Agent Access, and approval review
• The SQL editor runs one restricted statement, blocks system tables, and enforces LIMITs; guarded writes require an explicit checkbox
• Disabled upstream Storage, Realtime, Logs, and Settings routes redirect to the supported project surface in the self-hosted Studio profile
• Screenshots below come from the current project, not a design mockup

• One-hour tokens bound to a single tenant tuple and application session
• Schema read access works immediately; bounded row reads require a separate default-off checkbox and mcp:data:read
• Local write mode uses migration, preview validation, Studio approval, and one-time promotion
• Self-hosted libSQL write mode remains a typed unsupported operation

• Common CRUD flows against the pinned supabase-js release, verified by a differential harness
• select, filters, order, limit, range, exact count, insert, update, delete, upsert
• Everything else (arrays, ranges, RLS, RPC, casts, FTS) fails explicitly; it is never approximated

Read the exact contracts:
Data API ·
Gateway ·
SQLite meta ·
Realtime protocol ·
Core matrix

Product tour

Studio contains code derived from Supabase Studio under Apache License 2.0. Provenance and the reproduced license live in apps/studio/UPSTREAM.md and apps/studio/UPSTREAM_LICENSE.

Agent access without production roulette

An AI agent should not need your database password or libSQL JWT. Mekka gives it a short-lived token bound to one organization, project, environment, branch, generation, and application session. Schema access and row access are separate grants. Write access exists only where the active engine profile can create an isolated preview.

Agent
  → one-hour scoped token
  → schema-only metadata by default
  → optional bounded row reads after explicit opt-in
  → optional isolated preview for supported write profiles
  → exact migration approval before production promotion

For profiles with write previews, Mekka stores the migration artifact, SQL, schema hashes, and the destructive-operation flag. Studio shows the change before approval. The approval secret works once and only for that artifact. Promotion checks the production schema again before it runs. The agent can break its preview; production stays behind a human decision and a schema check.

There is no direct production-write tool, no arbitrary SQL, no credential or token passthrough. query_rows requires explicit mcp:data:read, permits only manifest-resolved columns and simple bounded filters, and still applies row and field policy. Each tool is gated by a separate capability: mcp:read, mcp:data:read, mcp:preview:create, mcp:preview:propose, mcp:preview:apply, mcp:preview:validate, mcp:promotion:request.

{
  "table": "notes",
  "columns": ["id", "title"],
  "filters": [{ "column": "id", "operator": "gte", "value": 1 }],
  "orderBy": { "column": "id", "direction": "asc" },
  "limit": 20,
  "offset": 0
}

The self-hosted beta policy permits all rows and public manifest columns after the user enables row access. Deployments that need row-level restrictions must supply a stricter policy source. Prompt text, filter values, row values, logs, and database content cannot create or elevate this capability.

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

For a local MCP server that bridges stdio to the remote Streamable HTTP endpoint:

npx mekka mcp-stdio --url https://mekka.example.com/mcp --token-env MEKKA_MCP_TOKEN

API surface

Every request gates on the tenant tuple organization / project / environment / branch / generation.

Supported from supabase-js: select, eq/neq/gt/gte/lt/lte/in/is/not/or/match, order, limit, range, exact count, insert, update, delete, upsert (primary key only, merge duplicates only). Embedding, aliases, casts, RPC, arrays, ranges, and full-text search fail explicitly.

Local filesystem and S3-compatible providers, checksummed bounded reads, MIME allowlisting, quotas, and reconciliation. Full TUS, transforms, and multipart uploads are not claimed.

Security model

Security research is welcome. Source access makes review possible; it doesn't prove the absence of vulnerabilities.

Capability and status

Run it

Install Node.js 20 or newer, then:

npx mekka my-app

Pass a folder name if the default mekka directory is taken. The CLI installs Bun when needed. Git is optional; without it, Mekka downloads the GitHub archive over HTTPS and enforces caps on archive size, extracted bytes, and entry count.

Inside an existing checkout:

bun install --frozen-lockfile
bun run dev

Local state stays in apps/studio/.local/.

Self-hosted libSQL profile

Run the pinned single-primary libSQL deployment behind Caddy HTTPS, issue a scoped EdDSA client JWT, and configure Mekka with server-only environment variables:

MEKKA_DATA_ENGINE=libsql-remote
MEKKA_LIBSQL_URL=https://libsql.example.com
MEKKA_LIBSQL_TOKEN_ENV=MEKKA_LIBSQL_TOKEN
MEKKA_LIBSQL_TOKEN=<scoped-client-jwt>

docker compose -f deploy/libsql/compose.yaml up -d
bun run smoke:libsql
bun run --cwd apps/studio start:production

The baseline is one writable primary with persistent storage. It is not multi-writer and does not claim automatic failover or PITR. Backups must be encrypted, stored off-host, and restored into an isolated volume during drills. See docs/runbooks/self-hosted-libsql.md.

Verification and development

bun run check runs the full gate: formatting, lint, typecheck (core and Studio), the CLI suite, workspace tests, Studio tests, the production build, and smoke tests.

Read CONTRIBUTING.md before opening a pull request.

Roadmap

Mekka is ready for controlled local and self-hosted libSQL beta testing. The current single-primary profile still requires operator-owned monitoring, off-host backups, restore drills, TLS, secret rotation, and capacity planning before it should carry important production data.

Repository map

Support and security

Use GitHub Issues for reproducible bugs, questions, and feature requests. Report vulnerabilities privately through the process in SECURITY.md.

Mekka is under active development. Reviewed paths have tests. A production deployment still needs monitoring, verified backups, deployment hardening, and an independent security review.

License

Individuals may inspect, modify, test, and learn from the source. Qualifying small organizations may use Mekka in their products under the additional grant.

Large companies and cloud providers may not repackage Mekka as a competing hosted backend without a commercial agreement. LICENSE.md contains the terms.