Rowkai

Rowkai Docs

Quickstart, architecture, API, and deployment guides.

Documentation

Everything you need to run branchable multitenant Postgres with GraphQL in one system.

These docs cover the fastest local setup path, the Rowkai architecture, the control plane API, and Kubernetes deployment. The core idea stays the same throughout: one system for multitenant Postgres, built-in GraphQL, blazing-fast branching, and security built into the operating model.

Quickstart

Run Rowkai locally, build the services, start the fullstack demo, and create your first branch.

Architecture

Understand compute and storage separation, branch trees, timelines, Pageserver, WAL, and GraphQL-ready computes.

API

Use the control plane to create tenants, timelines, branches, and computes through a clean JSON API.

Kubernetes

Deploy Rowkai on Kubernetes with S3-backed storage and optional Cloudflare-friendly GraphQL ingress.

Quickstart

Get Rowkai running locally in under 10 minutes.

Rowkai combines PostgreSQL, Go services, branching workflows, and a local admin UI. The fastest path is to build the PostgreSQL distribution with the Rowkai storage manager, build the Go services, then start the fullstack demo script.

Prerequisites

  • Go 1.22+
  • Node.js 18+ and npm
  • make, gcc, and standard build tools
  • libreadline-dev, zlib1g-dev, flex, and bison for PostgreSQL builds
  • Python 3 for the demo script helpers

Build PostgreSQL with Rowkai

./configure --prefix=/usr/local/pgsql \
  --with-openssl --with-libcurl

make -j$(nproc)
make install DESTDIR=.local-install

Build the Go services

cd controlplane
go build -o bin/controlplane ./cmd/controlplane/
go build -o bin/pageserver ./cmd/pageserver/
go build -o bin/walservice ./cmd/walservice/
cd ..

Start the local fullstack demo

scripts/rowkai-fullstack-demo start

This starts the control plane, pageserver, WAL service, a default tenant and timeline, a compute node, and the admin UI.

Architecture

Compute and storage are separated so branching stays fast and tenants stay flexible.

Rowkai uses a Neon-style storage and compute split. PostgreSQL computes are disposable and stateless. The Pageserver owns page storage and reconstruction. The WAL service handles durable WAL ingestion. The control plane manages tenants, timelines, branches, computes, and provisioners.

Core services

  • Control plane for tenants, timelines, branches, and compute lifecycle
  • Pageserver for versioned page reads and branch ancestry traversal
  • WAL service for durable WAL ingestion and optional quorum mode
  • PostgreSQL computes using the Rowkai storage manager

Branching model

  • Instant branch creation with metadata-only writes
  • Copy-on-write behavior for branch changes
  • Nested branches with no practical depth limit in the model
  • Timeline ancestry traversal for page lookup

Why this matters

This model is what makes Rowkai a real system for multitenant Postgres instead of a pile of scripts. You can isolate important tenants, branch live state quickly, expose GraphQL on the compute you care about, and reason clearly about promotion paths.

API Reference

The control plane API manages tenants, timelines, branches, and computes.

The default local base URL is http://127.0.0.1:9090. All request and response bodies use JSON, and errors return a JSON payload with an error field.

Common endpoints

  • GET /status for health and stats
  • GET /tenants and POST /tenants for tenant management
  • GET /tenants/{tenantId}/timelines for timeline listing
  • POST /tenants/{tenantId}/timelines/{timelineId}/branches for branching
  • POST /tenants/{tenantId}/timelines/{timelineId}/compute for compute creation

Create a tenant

curl -X POST http://127.0.0.1:9090/tenants \
  -H "Content-Type: application/json" \
  -d '{"name": "my-project"}'

Create a branch

curl -X POST \
  http://127.0.0.1:9090/tenants/TENANT_ID/timelines/TIMELINE_ID/branches \
  -H "Content-Type: application/json" \
  -d '{"name": "feature-branch"}'

Kubernetes

Deploy Rowkai with Kustomize, object storage, and optional GraphQL ingress.

The Kubernetes deployment path is built for teams that want Rowkai as a real tenant platform. The base deployment covers the control plane, Pageserver, WAL service, and compute provisioning. Optional Cloudflare-friendly ingress can expose the control plane and per-compute GraphQL over HTTP.

Deployment flow

  1. Create the rowkai namespace and S3 credentials secret.
  2. Build and push the PostgreSQL and Go service images.
  3. Update image references in the Kustomize config.
  4. Apply the Kubernetes manifests.

Apply the manifests

kubectl apply -k deploy/k8s/

Optional GraphQL ingress flags

--k8s-graphql-ingress-base-domain=gql.rowkai.example.com
--k8s-graphql-ingress-class=nginx
--k8s-graphql-cluster-issuer=letsencrypt-prod
--k8s-graphql-external-dns-target=<your-ingress-lb-hostname>
--k8s-graphql-cloudflare-proxied=true

Important note

Standard Kubernetes Ingress is for HTTP and HTTPS endpoints like the control plane and GraphQL. Raw PostgreSQL TCP traffic should use a LoadBalancer, Cloudflare Tunnel, or another TCP-capable edge strategy.

Need Help

Want help standing up Rowkai for your SaaS, tenant platform, or Kubernetes rollout?

If you are building a secure multitenant Postgres system with GraphQL and fast branching, we can help with architecture, rollout shape, and production planning.

Request access Contact sales