<Home>
← JournalEngineering · 5 min read

Read a database topology before you trust it

What replicas, shards, endpoints and connected applications tell you about a database, and what a diagram cannot prove.

AN ORIGINAL HAKOPOD ILLUSTRATION

When inspecting a database diagram, check the observed member count, the age of the observation and where the members run. Six configured replicas do not tell you whether six replicas are ready or whether they would survive a node failure.

Hakopod alpha.55 includes application bindings, member inspection and measured resource history for PostgreSQL, Redis, MySQL, MongoDB and ClickHouse. This article explains the design decisions; the managed database guide records controller setup, availability and the engines still under development.

Read the members before the lines

Start with the engine and its topology. A PostgreSQL primary with two replicas has different routing and failure rules from three ClickHouse shards. A replica keeps another copy. A shard holds a portion of the data. A coordinator helps members agree about metadata or leadership; it usually does not store another complete copy of your application data.

Compare requested and observed counts. Asking for six replicas does not prove that six replicas started, caught up or have usable storage. Check the observation time and configuration revision too. An old healthy observation cannot verify a new resize.

The dashboard design places member inspection beside the diagram. Role, readiness, restarts, node, image and resource allocation help explain what a node represents. Unavailable metrics should remain unavailable. A configured storage volume is capacity, not measured disk usage.

An endpoint has a specific job

EngineWhat the application needs to understand
PostgreSQLSend writes to the primary route. Choose replica reads explicitly and account for replication lag. PgBouncer pools connections; it does not decide which arbitrary SQL statements are safe on a replica.
MySQL Group ReplicationMySQL Router exposes primary and secondary routes. Applications must reconnect after failure and handle interrupted transactions.
Redis ClusterUse a cluster-aware client that follows slot ownership and MOVED/ASK responses. Every advertised member must be reachable.
MongoDB replica setsThe driver discovers members and applies read preferences and write concerns. A seed address is the start of discovery, not a promise that every request uses that host.
ClickHouseReplication copies data within a shard. Distributed tables or explicit query design combine shards. Balancing connections does not turn a local table query into a query across the cluster.
Vitessvtgate routes through the configured keyspaces and VSchema. Its topology and recovery are a separate managed-engine contract.
Oracle DatabaseThe service name and edition matter. Oracle Database Free is proprietary software, free to use within its license limits, and runs standalone; a licensed Data Guard deployment needs role-aware services and its own failover contract.

PostgreSQL, Redis, MySQL, MongoDB, ClickHouse, Vitess, Oracle Database Free and MyDuck are included in self-hosted alpha.56. Oracle Free and MyDuck are standalone Linux amd64 databases. Vitess requires private Linux amd64 workers, approved capacity and native backup storage. Cloud alpha.35 packages the same database support. The current shared Cloud service cannot provision Vitess or Oracle Free. MyDuck availability depends on eligible worker capacity and runtime setup.

Oracle Database Free is proprietary, no-cost software. Oracle Enterprise, Data Guard and public database endpoints remain unavailable. MyDuck clusters, Neon and Supabase also remain unavailable. The table describes routing models; it does not make unavailable engines ready to deploy.

For PostgreSQL, choose pooling after checking the application’s connection needs. Transaction pooling releases a server connection after each transaction, so applications cannot assume arbitrary session state survives between transactions. Session pooling retains that relationship for the client’s session. Neither choice removes the need for transaction retries or an explicit read-consistency policy. The PgBouncer feature matrix describes those compatibility differences.

Connected applications describe configuration

A useful diagram shows the checkout API reaching the write endpoint and a reporting worker reaching a replica route. Selecting the application should reveal the service, variable and saved revision behind that line.

Saved bindings are not live sessions. A failed deployment can leave the previous successful revision running. An application using manually entered credentials may not appear in binding records at all. Read these as records of saved connections. They do not establish which applications are sending traffic now.

Dense diagrams need the same care as small ones. Fifteen applications and six replicas need readable targets, search, a scrolling canvas and a keyboard-accessible inspector. The whole topology should not shrink until its labels become unreadable.

Placement is part of the failure model

Three containers on one worker can disappear together. Three workers on one VM can also disappear together. Zone and provider labels help explain scheduling, but labels do not verify independent disks, power, networks or control planes.

Before choosing a distributed deployment, define which failure it must survive and how much data loss or recovery time is acceptable. Then test that failure. Majority-based replication also needs a connected voting majority; spreading members across distant providers adds latency and more network boundaries.

Hakopod’s current development tests run on nodes sharing one physical VM. They can test scheduling and database behavior, but they cannot establish independent-zone or cross-provider availability.

Keep replicas and recovery separate

Replication can copy an accidental deletion as efficiently as a useful write. Backups need their own verified capture, retention and recovery process.

Restore into a separate target, inspect the data and application behavior, then review a connection change. Writes made after the captured point do not automatically follow a logical restore. Coordinate them before cutover. The recovery guide explains the current PostgreSQL and Redis workflow.

Use the database catalog to compare engines and availability. Compare its routing, consistency and failure behavior with the requirements of your application.

Have a use case we should understand?Share it on GitHub ↗

Keep exploring.

All stories↗
Engineering / 7 min read

How we made our Next.js Docker build about 40% faster

Our Next.js production image built in 8m43s on a fresh spot VM runner. Three workflow changes brought it to 5m18s. Here is what we changed, with the YAML.

Read the story↗
Engineering / 4 min read

What MyDuck’s two SQL protocols actually mean

How one DuckDB database serves MySQL and PostgreSQL clients, where compatibility stops, and what the managed release does and does not provide.

Read the story↗