Replicas and topology

Parix models replica count as part of a catalog-backed cluster topology. Operators choose a topology and PX size; they do not create or remove individual TigerBeetle replicas directly.

Use this page to understand the model. To queue a supported change, follow Cluster configurations.

Topology choices

Developer databases are logical tenants on a Parix-operated shared cell. The customer database does not own or configure the backing cell's replica topology.

Enterprise topology is contractual and not a general self-service option.

Replica metadata

For isolated databases, the control plane tracks provider-reported replica details such as:

• zero-based replica index
• provider machine or instance identity
• runtime state
• disk or volume identity
• private address and placement information
• effective CPU, memory, storage, and network profile

Dashboard topology, machine selectors in Metrics, and replica context in Logs depend on this metadata. If provider convergence is incomplete, the UI can temporarily show fewer details than the selected target shape.

Size and topology are one cluster decision

A cluster change resolves a complete target from the active catalog:

• topology and replica count
• PX size
• provider and region compatibility
• storage constraints
• regional machine profile
• current price

Changing from PX-10 to PX-20 is not the same as adding a replica. Changing from Single Node to HA 3 changes both topology and replica count, even if the PX size stays the same.

Missing catalog combinations fail closed. Parix does not substitute a different region, machine, or price unless the create or placement workflow explicitly supports and records that fallback.

Post-create topology changes

Dedicated topology changes are provider- and storage-aware:

• Google Cloud can use a backup-driven migration when node count changes require a replacement replica set.
• The database is unavailable during the migration cutover; wait for the workflow and profile to return to an active state.
• AWS node-count migration is currently blocked until the restore-backed migration path is available.
• Local NVMe blocks post-create topology and instance-size changes.
• Shared Developer topology is operated by Parix and is not customer-configurable.

The Instances page compares current and selected state, shows price impact, and queues the change only after validation.

Workflow and status behavior

A topology request can move through:

1. validation against plan, provider, storage, billing, and lifecycle state
2. durable change/job queueing
3. backup creation when the migration path requires it
4. provider resource convergence
5. data restore or rolling change
6. route and profile cutover
7. durable change-history update

Do not treat the form submission as completion. Confirm:

• the change job completed
• the database profile is active
• the topology graph shows the target replica count
• all replicas report healthy telemetry
• gateway queries succeed

Cross-region Production HA

Cross-region HA is a fail-closed beta controlled by a master feature flag and environment configuration.

When the create catalog exposes it:

• the cluster uses one provider
• the topology must be multi-replica
• there are 2 or 3 total regions
• additional regions are selected at creation time
• the primary region remains the control-plane, gateway-affinity, and CDC home

It is synchronous placement for one TigerBeetle cluster, not asynchronous geo-replication or a cross-provider disaster-recovery copy.

The standard self-service Production path remains single-region unless the create form explicitly offers additional regions. Post-create region addition or provider migration is not a general workflow.

Observability consequences

Dedicated Metrics can provide aggregate and replica-scoped views. Use machine/replica selectors to compare:

• CPU, memory, disk, network, and restarts
• TigerBeetle replica health and synchronization
• cache and operation timing
• gateway request rate, latency, and failures

Logs can include machine and component context. If one replica diverges from the others, preserve its replica index and provider machine identity when escalating.

Backup and import consequences

An imported database requires exactly one .tigerbeetle file for every selected replica index. Parix validates embedded cluster and replica metadata before the import can proceed.

Backup restore eligibility also requires the backup artifact set and active target to match replica count and the other exact shape attributes. A backup from HA 3 is not eligible for an in-place restore into a Single Node or HA 6 target.

Current limits

• no direct per-replica create/delete API
• no customer direct protocol access to a replica
• no customer topology controls for Developer shared databases
• no cross-provider replica group
• no arbitrary post-create region addition
• no AWS node-count migration in the current upgrade path
• no post-create topology changes for local NVMe

Continue with Cluster configurations, Metrics, or Providers and regions.