Deploying & scaling Rindle

Choose a data-tier deployment separately from your browser and API server. Rindle’s SQLite authority has two profiles. Standalone runs one rindled process for SQL writes, reads, and live subscriptions. Replicated separates the write master from optional read followers. A replicated deployment needs at least one follower for live queries and browser sync. The PostgreSQL-source preview uses a gateway and followers while Postgres remains authoritative.

Your API server connects through one URL and server-only token:

RINDLE_URL=https://app.example.com
RINDLE_DATABASE_TOKEN=<server-only-bearer>

Standalone can expose that one origin directly. A fleet edge routes SQL and migrations to the master and follower protocols to the selected read replica. A query lease tells the browser which public WebSocket endpoint and follower-affinity ticket to use. The ticket controls placement, not authorization.

# Deployment shapes

# Standalone desktop or hosted micro

Set profile = "standalone" in rindle.ncl, or run the thin container with ROLE=standalone. One source-less rindled serves authoritative SQL, mutations, migrations, reads, materializations, and subscriptions from the same file and origin. It is a good fit for a desktop/local app or a deliberately single-node hosted micro app whose recovery contract is provider volume snapshots.

Standalone has no follower fan-out, HCTree/OCC writer pool, continuous journal backup, PITR, or automatic failover. Writes serialize. It does not scale out by adding a second writable daemon. Moving to a fleet is an export/import into a new HCTree store followed by a routing cutover; the wal2 file is not promoted in place.

# Master-only SQL

The smallest replicated deployment is one rindle-replicator. Its HCTree database is the authoritative state and it serves the public SQL surface, interactive transactions, ordered migrations, and backup shipping. Use it with @rindle/sql-client, Drizzle, or rindle sql when live queries are not required.

# Master plus one follower

Add one rindled follower for the complete synced-app stack. The follower restores from the master’s lineage, tails its journal into a WAL2 SQLite database, and owns materialized queries and live subscriptions. The pair can share a host for local or small deployments. They remain separate processes.

# Read-scaled fleet

One master can feed multiple followers. Live queries, one-shot maintained-query reads, and subscriptions scale across them. Ordinary /v1/sql requests still go to the write authority, and all writes retain the same sequencing point. A stable edge and signed affinity tickets keep each browser’s lease and WebSocket on one follower and re-place it after a failure.

This multi-follower shape is built for self-hosting. It is not currently a Rindle Cloud SKU.

# Writes: one order, topology-specific execution

Standalone deliberately has one serialized wal2 writer. Its commit’s captured changes cross the local IVM worker barrier and become visible without a replication wait. wal2 lets reader snapshots sit beside that writer, so a read-only public SQL transaction never parks writes: each one is backed by its own reader snapshot. A held snapshot pins wal2 checkpointing, so open read-only transactions are capped — RINDLE_READ_TXN_SESSIONS (default 4); past the cap a begin answers 503 instead of queueing.

In the replicated profile, “one write master” does not mean “one transaction at a time.” The master pools HCTree BEGIN CONCURRENT connections. Disjoint transaction bodies can execute in parallel. HCTree validation assigns successful commits the cid that defines the journal order.

• RINDLE_WRITE_CONNECTIONS controls open transaction capacity (default 8).
• RINDLE_WRITE_THREADS controls execution parallelism (default 1). Raise it toward the cores available to the master.
• Replayable pure-write conflicts retry inside the master.
• A read-bearing conflict re-drives the authoritative mutator, because replaying only its generated SQL is unsound.

Followers scale reads. Adding another write master is an application-level sharding decision, not a replica-count change.

# Local lifecycle

rindle dev owns the normal development lifecycle in one command:

rindle dev --migrate --gen shared/schema.gen.ts -- \
  vite dev --port 3000

It:

1. evaluates rindle.ncl once
2. starts one standalone daemon, or the replicated master, followers, and rindle-dev-edge
3. waits for readiness
4. applies and watches migrations
5. generates and watches schema
6. injects RINDLE_URL plus RINDLE_DATABASE_TOKEN
7. forwards signals
8. stops the fleet with the app command

When you need to supervise only the data fleet, use rindle up. rindle exec -- … remains as a compatibility adapter that runs one command with bindings derived from rindle.ncl. For new projects, use rindle dev.

The replicated profile runs the native development edge even for one follower, so local code exercises the same unified ingress and affinity path as production. The standalone profile binds read HTTP, write HTTP, and subscriptions directly to its one daemon.

# Durability and recovery

Standalone desktop/local recovery is an app-owned SQLite snapshot (VACUUM INTO, the backup API, or an OS backup) on an explicit schedule. Hosted micro recovery is a completed provider volume snapshot restored onto a replacement volume and daemon. Its RPO is the configured snapshot interval; its RTO includes provisioning and restore downtime. Compute may scale to zero, but the persistent volume and snapshots do not.

A product-initiated standalone snapshot must quiesce/close the writer. Before promising scheduled snapshots on a provider, qualify an active-wal2 snapshot → new-volume restore, run SQLite integrity checks, and prove the fresh-query correctness contract. Do not describe this as continuous backup or HA.

In a fleet, a backup block makes the master ship logical journal segments and portable bases to an S3-compatible store. The durable manifest watermark bounds local journal garbage collection. Maintenance compacts segments, creates new bases, enforces retention, and scans for orphans. Restore exercises on a separate host must prove that the same generation can be restored.

A new follower restores a WAL2 database from the latest portable base and replays the tail. A replacement master restores and promotes an HCTree leader from the same lineage. A follower older than retained history restores instead of requesting an unbounded replay.

# Rindle Cloud on OVH

Rindle Cloud’s Cloudflare-hosted control plane records billing, placement, DNS, and versioned intent. It commits desired state to the fleet repository. rindle-poold converges packed processes on the assigned OVH box and reports the applied generation. Cloudflare Tunnel publishes the stable app-<id>.rindle.cloud ingress.

The dashboard offers SQL and Sync plans for a SQLite authority, plus a PostgreSQL-source preview. SQL runs a master; Sync adds a read follower. The PostgreSQL preview keeps writes in your existing Postgres database and requires source preparation. It is a different authority topology, not a SQL/Sync upgrade.

The dashboard does not currently expose arbitrary host, region, machine-size, volume-size, or follower-count controls. Consult the dashboard for current pricing and limits. See Cloud quickstart for available plans and the Postgres guide for preview requirements.

# What is available

# Run it yourself, or have us run it

• Self-host — run standalone with your snapshot/restore contract, or operate the fleet master, followers, edge, backup lineage, and restore drills in infrastructure you control.
• Rindle Cloud — provision the SQL or Sync stack, or follow the PostgreSQL-source preview workflow. The control plane manages its declared serving processes.

Self-hosted and hosted SQLite deployments use the same schema, SQL client, API server, browser client, and migrations. A PostgreSQL source keeps its own write and migration workflow. The dashboard cannot convert an existing SQL/Sync app to Postgres or a Postgres-source app to SQL/Sync in place.

# Next steps

• Cloud quickstart — choose SQL, Sync, or the PostgreSQL-source preview.
• Connect your app — use one URL and one token.
• The three-tier architecture — the application shape around the data tier.
• Run the daemon — standalone authority and follower postures in full.