Skip to content

Topology and schema

Last updated

View as Markdown

Topology records your database and the infrastructure it runs on. It covers every node in the cluster, how those nodes replicate, where they are hosted, and how each one is configured. Within each database, it records every table, column, index, constraint, view, function and extension, and it records the cluster’s roles. The data forms a tree and is captured over time.

Open a database and choose Topology. It has two views:

ViewWhat it is for
VisualizationThe schema as a diagram you can explore
ChangesWhat differs between two points in time

The component’s own Topology entry, above its databases in the sidebar, shows Changes for the whole component: every database, plus the servers and their settings.

Links to the older topology-browser, schema-operations and schema-management pages open Topology.

There is nothing to turn on. The collector captures topology at a fixed interval, set by interval under [topology] in collector.toml. The CLI writes interval = "60s".

On PostgreSQL, for each node in the component, including the writer and every replica, it records:

  • Identity. Host, port, role (writer or reader), the PostgreSQL version that node is running, and its cluster name.
  • Replication. A standby records the node it replicates from, so the replication layout is part of the record.
  • Settings. The node’s key configuration parameters, each with its value, unit, default, where it was set, whether changing it needs a restart, and whether a change is already waiting on one.
  • Hosting. What the platform reports about the node, such as an RDS instance class.
  • TLS. When the collector is configured with a CA file, the subject, fingerprint, and expiry date of the certificate in it that expires first, and how many certificates the file holds. With a single CA, that is the date a connection will start failing. In a bundle such as Amazon RDS’s, the certificate that expires first need not be the one your server chains to.
  • Metrics. Each node links to the infrastructure metrics its platform publishes: CloudWatch for RDS, the CloudNativePG exporter on Kubernetes, and node_exporter on a host you run yourself.

The cluster also gets one identity object. It carries system_identifier and the control and catalog versions when the monitoring role can read them.

Every object has a type. The type list includes more than tables and columns:

Structure. cluster, server, scope (a database), schema, table, column, view, sequence.

Constraints and indexes. pk, fk, uk, check, index.

Code. function, aggregate, trigger, event_trigger.

Configuration and access. settings, database_properties, role, default_acls, extension, publication.

Migrations. migration and migration_folder. If your database is managed by Flyway, DBGorilla reads the migration history table and treats each migration as a topology object with its version, description, who installed it, when, and how long it took. Alembic keeps only the current version, so an Alembic database gets one migration object that names that version. You can then diff migration history alongside the schema it produced. This helps answer “when did this column appear”.

Every object has a path. A server is /host:port, a database is /mydb, and objects nest under it. Paths identify objects for agents and provide the basis for deep links.

Visualization draws an entity-relationship diagram with tables, columns, and foreign keys. The diagram shows one schema at a time. Pick it from the Schema picker or from the list of schemas that the empty diagram offers.

A snapshot is the whole topology as it stood at one moment. Change history is based on snapshots.

Snapshots are recorded when something changes. The collector reports the full state on its own schedule and stores a new snapshot when that state differs from the last one. The list shows changes, not every collection time. On a live component it looks like this:

captured=2026-09-15T23:07:32Z
captured=2026-09-15T23:04:31Z
captured=2026-09-12T01:51:37Z
captured=2026-09-12T01:50:34Z
captured=2026-09-11T19:22:51Z
captured=2026-09-11T19:19:19Z
captured=2026-09-03T19:00:22Z
captured=2026-09-03T18:59:20Z

Eight snapshots over three weeks, in pairs minutes apart, on four days. The collector recorded no topology changes on the other seventeen. Read the list that way: a gap means that nothing about the structure changed, and a cluster of snapshots means that several changes occurred close together.

Every stored snapshot remains in the list.

The Changes view answers “what is different”.

Click a bar in the timeline to see that snapshot against the one before it. Use this to investigate a current problem.

Click an object in a change to see its properties. The compared with picker next to its date sets which earlier capture of that object it is compared against. Use this for “what has changed since the release”, when the relevant boundary is not between consecutive snapshots.

Either way, the output is a list of paths and the change to each:

action=ADDED path=/shop/public/orders/idx_orders_customer_created class=index
action=MODIFIED path=/shop/migrations/c4d9e2a1b6f3 class=migration

The actions are:

ActionMeaning
ADDEDThe object did not exist in the older snapshot.
REMOVEDIt existed and no longer does.
MODIFIEDIt exists in both and something about it differs.

A modified object carries its before and after states, so you can see which property changed.

Infrastructure objects are versioned like the schema. A new replica, a version upgrade, or a changed setting between two snapshots shows up in Changes the same way a new column does.

Sandboxes are built from a snapshot: the clone’s schema is the snapshot’s schema.

Tuning reads your current parameter values from the settings object.

Investigations read topology to confirm what exists before proposing a change.

An assistant connected through Connect your editor gets the same tree. get_topology_overview lists the servers and databases, list_topology_snapshots lists snapshots, and compare_topology_snapshots compares any two of them, however far apart.

Narrow a comparison by class when a deployment changed a hundred things and you care about one kind. Narrow by path prefix when you care about one database or one schema. These are the class_filter and path_prefix arguments of compare_topology_snapshots.