Database scaling

​

Goal

Retain the original writer while serving reads from healthy, synchronized native replicas.

​

Prerequisites

• A sealed containerd database on the selected server and an updated agent advertising native_database_scaling_v1.
• A retained backup with passed restore validation before replication preparation or failed-reader replacement.
• Explicit hosted maximum size option, copy count, total hourly cost, and cost acknowledgement; connected servers use owned capacity.

​

Workflow

​

Engine contracts

• PostgreSQL uses a physical base backup, physical slots, WAL replay, and hot standby; the reader retains the writer’s system identity.
• MySQL uses GTID auto-positioning with secure replication, read_only, and super_read_only. MariaDB uses its own GTID protocol, unique server identity, secure transport, and persistent read-only configuration.
• Redis uses native TLS replication and restricted replication credentials. Readers use read-only ACLs and must report a synchronized source link.
• ClickHouse uses native ReplicatedMergeTree data and an embedded Keeper on the original writer with TLS and dedicated credentials. It preserves table UUIDs and local data during conversion. This same-server topology does not provide writer failover.
• Readers never auto-promote. Removal withdraws read routing, drains for a bounded interval, and removes only the sealed reader workload and its exact volume after verified cleanup.

​

Pricing and automation

In the dashboard, Use selected limits calculates the hourly database cap from the maximum authorized size’s catalog rate multiplied by maximum copies. Review the calculated amount and explicitly acknowledge billing before applying. Existing saved caps remain unchanged until you choose this option; Custom cap lets you enter a separate limit. Missing catalog prices block calculated authorization. Amounts retain catalog cents because the catalog does not declare a currency; this is not an all-in infrastructure budget. Hosted requests bind exact size IDs and acknowledged bounds. Existing size_gb provisioning retains its original catalog lookup; scaling-only size variants use exact IDs without changing old prices. Billing follows actual allocation epochs, including partial failed operations and provisioned readers. Retained storage remains charged until exact removal is observed. Completed hourly usage is idempotent, supports standalone databases, and offsets legacy usage for the same interval. A late verified cleanup preserves the original hourly charge and appends one auditable signed adjustment in the current accounting period. Repeated and concurrent reconciliation cannot apply the same correction twice. Invoice settlement, account-credit carry-forward, and the catalog currency contract remain unqualified; these local usage receipts do not establish a settled customer credit. Deleting a scaled database uses its durable writer tombstone: the agent withdraws reader routing, drains and retires the exact readers before removing the writer and volumes. Accepted cleanup receipts close matching billed allocations at their persisted physical removal times. Blocked deletion, retained volumes, missing receipts, and unknown cleanup keep their allocation accounting open. Retirement preserves allocation epochs and original usage; hourly replay reconciles late confirmation with an append-only adjustment. Automatic vertical memory growth uses memory priority, freshness, a thirty-minute cooldown for every database scaling action, and a two-increases-per-hour vertical growth limit. CPU-only vertical growth applies with horizontal automation off. Hosted live growth selects an authorized exact option at the current storage size. Automatic database scale-out needs CPU above 70% for ten minutes, traffic on the read endpoint, and healthy replication. Scale-in needs CPU below 30% for thirty minutes with safe remaining utilization. Database horizontal cooldown is thirty minutes. The first read replica is prepared manually before read-endpoint traffic can authorize automatic scale-out. If scale-in returns to the writer alone, the read endpoint refuses connections and cannot provide this signal; manually add a reader again. After manual initialization, set minCopies to at least two to retain a reader and its demand signal.

​

API and tools

Application bindings support private_runtime for the writer and private_read for a qualified private reader endpoint. Reader bindings keep TLS verification, use the reader port in workload egress, and never fall back to the writer or rewrite generic writer environment aliases. Use a separate variable such as READ_DATABASE_URL. The reader-binding migration is required; removing all reader bindings is required before rolling it back. GET /api/v1/databases/{id}/scaling reports authoritative deployment_mode (hosted or connected_node), policy, authorization, applied resources, preparation, replicas, read endpoints, and operation. Missing or unknown placement leaves dashboard mutation controls unavailable until the selected server is confirmed. PUT requires current revision, idempotency key, action, copies, policy, and authorization. Actions are configure, resize, prepare_replication, scale, and recover_replication. Hosted requests use size_option_id and authorization.max_size_option_id; arbitrary hosted memory/CPU values are rejected. Connected requests use memory_mb and cpu_millicores without hosted prices. Use stackshift database scaling DATABASE and stackshift database scale DATABASE —file scaling.json. Agent tools inspect state and apply only governed concrete requests. Application manifests accept scaling on database references: copies, bounded automation, exact hosted sizeOptionId/maxSizeOptionId and acknowledged maxHourlyCostCents, or connected memoryMB/cpuMillicores. Preparation and failed-reader recovery remain explicit backup-authorized API, dashboard, CLI or governed tool actions. Apply combined resource/copy changes in verified stages; a pending allocation requires reconciliation before reapplying the manifest. Scaled database journals use authenticated metadata v3-scaling. Rollback must keep an agent compatible with that schema, existing replicas and exact allocation receipts; retain migrations and billing epochs. Older agents cannot manage scaled databases. These capabilities are local and unreleased. Linux runtime, engine failure/retry, packaged install/upgrade, architecture, UI, and generated documentation qualification must pass before deployment.

​

Expected result

​

Common failures