How xataio/xata works
Xata is a Kubernetes-based Postgres-as-a-Service platform centered on creating and managing projects and database branches. The control-plane API authenticates users and provisions branches; the branch operator manages their Kubernetes resources, while the SQL gateway routes client connections and can wake scaled-to-zero branches. The README also documents branching, backups, high availability, and serverless SQL. Connections below rely mainly on README-level architecture statements; sampled implementation confirms API routing and serverless entry points, but not most cross-service wiring.
Main entry points: server.go HTTP / WebSocket SQL · handler.go Projects REST API · projects.go Projects service · reconciler.go Branch operator
Components 18
Control plane
- Projects REST API
services/projects/api/handler.go - Projects service
services/projects/projects.go - Project store
services/projects/store/sqlstore/store_sql.go - Clusters service
services/clusters/clusters.go
Branch lifecycle
- Branch operator
services/branch-operator/pkg/reconciler/reconciler.go - Postgres branches
- Scale-to-zero sidecar
services/scale-to-zero-sidecar/internal/sidecar/sidecar.go
SQL connectivity
- SQL gateway
services/gateway/gateway.go - HTTP / WebSocket SQL
services/gateway/serverless/server.go - Branch sessions
services/gateway/session/session.go
Identity and access
- Auth REST API
services/auth/api/handler.go - Auth service
services/auth/auth.go
Other components
- Platform user
- Xata CLI
- Keycloak
- Kubernetes
- CloudNativePG
- Backup object storage
Connections 20
- Platform user → Xata CLI: manages via
- Xata CLI → Projects REST API: calls REST
- Projects REST API → Projects service: handles requests
- Projects service → Project store: persists projects
- Projects service → Clusters service: provisions branches
- Platform user → Auth REST API: authenticates
- Auth REST API → Auth service: handles identity
- Auth service → Keycloak: uses identity provider
- Projects REST API → Auth service: requires API authentication
- Clusters service → Branch operator: requests branch management
- Branch operator → Kubernetes: manages resources
- Kubernetes → CloudNativePG: runs database operator
- CloudNativePG → Postgres branches: operates instances
- Branch operator → Backup object storage: manages backup resources
- Platform user → HTTP / WebSocket SQL: sends SQL
- SQL gateway → HTTP / WebSocket SQL: serves SQL transport
- HTTP / WebSocket SQL → Branch sessions: resolves connections
services/gateway/serverless/server.go - Branch sessions → Postgres branches: routes database traffic
- HTTP / WebSocket SQL → Scale-to-zero sidecar: wakes inactive branch
- Scale-to-zero sidecar → Kubernetes: scales branch resources