<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.47 includes application bindings, member inspection and measured resource history for its released PostgreSQL, Redis and MongoDB integrations. This article explains the design decisions; the managed database guide records 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.

These are engine concepts, not a claim that every row is available in Hakopod. PostgreSQL, Redis and MongoDB are included in alpha.47. MySQL and ClickHouse remain unavailable with incomplete native qualification. Oracle Free remains unavailable while recovery acceptance is incomplete. Managed Vitess is being implemented and still needs runtime acceptance. Oracle Enterprise/Data Guard deployment remains disabled pending licensed native acceptance.

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 / 9 min read

How Hakopod manages a database

The path from a database configuration to durable operations, native controllers, verified connections and a reviewed recovery.

Read the story↗
Engineering / 3 min read

Let a quiet HTTP service sleep

Scale-to-zero is useful when the waiting is acceptable. Here is how to decide which services should sleep.

Read the story↗