How to ship a database every day<br>Sharding: up to 256TB in one indexNEW: Scale a single namespace up to 256TB with namespace sharding

How to ship a database every day<br>August 14, 2026•Tarun Pothulapati (Engineer)

Every day, turbopuffer customers ask for things: new query plans, new APIs, new<br>index structures. In response, we deploy dozens of database upgrades per day<br>across our clusters, many of them the same day we open the PR. Shipping fast is<br>how we<br>make every customer feel like they're our only customer.

We don't want to limit where you can run turbopuffer, so we support many<br>regions across three deployment models:<br>public SaaS, single-tenant SaaS,<br>and BYOC. In total, we operate<br>100+ clusters, twice as many as we had 6 months ago, and growing as we add more<br>public regions and many more BYOC deployments.

╔═ turbopuffer cloud account ═════════════════════╗ ╔═ customer cloud account ═══╗<br>║ ║░ ║ ║░<br>║ ┏━ public ━━━━━━━━━━┓ ┏━ single-tenant ━━━━━┓ ║░ ║ ┏━ BYOC ━━━━━━━━━━━━━━━┓ ║░<br>║ ┃ AWS | GCP ┃ ┃ AWS | GCP ┃ ║░ ║ ┃ AWS | GCP | Azure ┃ ║░<br>║ ┃ shared resources ┃ ┃ dedicated resources ┃ ║░ ║ ┃ customer's resources ┃ ║░<br>║ ┃ ┃ ┃ ┃ ║░ ║ ┃ ┃ ║░<br>║ ┃ tpuf operator ┃ ┃ tpuf operator ┃ ║░ ║ ┃ no tpuf operator ┃ ║░<br>║ ┃ access ┃ ┃ access ┃ ║░ ║ ┃ access ┃ ║░<br>║ ┗━━━━━━━━━━━━━━━━━━━┛ ┗━━━━━━━━━━━━━━━━━━━━━┛ ║░ ║ ┗━━━━━━━━━━━━━━━━━━━━━━┛ ║░<br>║ ║░ ║ ║░<br>╚═════════════════════════════════════════════════╝░ ╚════════════════════════════╝░<br>░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░╔═ tpuf account ═══════════╗<br>║ ┏ public ━━━━━━━━━━━━━━┓ ║<br>║ ┃ AWS | GCP ┃ ║<br>║ ┃ shared resources ┃ ║<br>║ ┃ tpuf operator access ┃ ║<br>║ ┗━━━━━━━━━━━━━━━━━━━━━━┛ ║<br>║ ┏ single-tenant ━━━━━━━┓ ║<br>║ ┃ AWS | GCP ┃ ║<br>║ ┃ dedicated resources ┃ ║<br>║ ┃ tpuf operator access ┃ ║<br>║ ┗━━━━━━━━━━━━━━━━━━━━━━┛ ║<br>╚══════════════════════════╝

╔═ customer account ═══════╗<br>║ ┏ BYOC ━━━━━━━━━━━━━━━━┓ ║░<br>║ ┃ AWS|GCP|Azure ┃ ║░<br>║ ┃ customer's resources ┃ ║░<br>║ ┃ no tpuf operator ┃ ║░<br>║ ┃ access ┃ ║░<br>║ ┗━━━━━━━━━━━━━━━━━━━━━━┛ ║░<br>╚══════════════════════════╝░<br>░░░░░░░░░░░░░░░░░░░░░░░░░░░░

The problem with BYOC

BYOC clusters live inside our customers' cloud accounts, to which we hold no<br>credentials by default. We can't just SSH or kubectl in. Some BYOC vendors<br>solve this by asking the customer to carve out a dedicated cloud account and<br>grant the vendor standing admin credentials inside it. That keeps the rest of<br>the customer's cloud account isolated, but every dedicated account creates<br>security monitoring + compliance + billing overhead that we generally prefer to<br>avoid.

We don't want different control planes for BYOC and SaaS, so we have to design<br>for the lowest common denominator. We must be able to operate every cluster<br>without reaching in.

How do you operate a database cluster you can't touch?

The only way this works is if every operation we need to perform on a cluster<br>can run without us reaching in. The cluster must be able to independently drive<br>its operations to a terminal state, even if it loses its connection to the<br>central control plane.

The solution to this is standard Kubernetes stuff. On every cluster, we run a<br>local cluster agent that implements a simple state machine. A single Kubernetes<br>CRD called TurbopufferOperation<br>expresses every operation kind, from upgrade to tidy. A Kubernetes<br>controller drives each custom resource (CR) from state to state via a<br>reconciliation loop until it reaches a terminal state. Operations advance on<br>their own by default, but BYOC customers can gate operations on<br>approval<br>or<br>maintenance windows.<br>These are baked into the CRD as waiting states that advance when approvals are<br>given or the window opens.

╔═ operation lifecycle ═══════════════════════════════════════════╗<br>║ ║░<br>║ ┏━━━━━━━━━━━━━━━━━━━┓ ║░<br>║ ┃ REQUIRES_APPROVAL ┃ ║░<br>║ ┗━━━━━━━━┯━━━━━━━━━━┛ ║░<br>║ │ approve (auto or manual) ║░<br>║ ▼ ║░<br>║ ┏━━━━━━━━━━━━━━━━━━━┓ ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓ ║░<br>║ ┃ PENDING ┃ ──▶ ┃ AWAITING_MAINTENANCE_WINDOW ┃ ║░<br>║ ┗━━━━━━━━┯━━━━━━━━━━┛ ◀── ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛ ║░<br>║ │ start() ║░<br>║ ▼ ║░<br>║ ┏━━━━━━━━━━━━━━━━━━━┓ ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓ ║░<br>║ ┃ RUNNING ┃ ──▶ ┃ AWAITING_EXTERNAL_EXECUTION ┃ ║░<br>║ ┗━━━━━━━━┯━━━━━━━━━━┛ ◀── ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛ ║░<br>║ │ poll() ║░<br>║ ┌────┴────┐ ║░<br>║ ▼ ▼ ║░<br>║ ┏━━━━━━━┓ ┏━━━━━━━┓ ║░<br>║ ┃SUCCESS┃ ┃FAILURE┃ ║░<br>║ ┗━━━━━━━┛ ┗━━━━━━━┛ ║░<br>║ ║░<br>╚═════════════════════════════════════════════════════════════════╝░<br>░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░╔═ operation lifecycle ════╗<br>║ ┏━━━━━━━━━━━━━━━━━━━━━━┓ ║░<br>║ ┃ REQUIRES_APPROVAL ┃ ║░<br>║ ┗━━━━━━━━━━━┯━━━━━━━━━━┛ ║░<br>║ ▼ approve ║░<br>║ ┏━━━━━━━━━━━━━━━━━━━━━━┓ ║░<br>║ ┃ PENDING ┃ ║░<br>║ ┗━━━━━━━━━━━┯━━━━━━━━━━┛ ║░<br>║ ▼ start() ║░<br>║ ┏━━━━━━━━━━━━━━━━━━━━━━┓ ║░<br>║ ┃ RUNNING ┃ ║░<br>║ ┗━━━━┯━━━━━━━━━━━┯━━━━━┛ ║░<br>║ ▼ poll() ▼ ║░<br>║ ┏━━━━━━━━━┓ ┏━━━━━━━━━┓ ║░<br>║ ┃ SUCCESS ┃ ┃ FAILURE ┃ ║░<br>║ ┗━━━━━━━━━┛ ┗━━━━━━━━━┛ ║░<br>╚══════════════════════════╝░<br>░░░░░░░░░░░░░░░░░░░░░░░░░░░░

The key is to define states that...