PostgreSQL Configuration

Configuring A PostgreSQL Data Source In Coordimap

This guide explains how to configure the Coordimap agent to crawl a PostgreSQL server. With PostgreSQL configured correctly, Coordimap can discover databases, schemas, tables, indexes, and relationships, then keep those diagrams updated over time.

For PostgreSQL, use the server or cluster system_identifier as scope_id. That value represents the database lineage more accurately than any Coordimap connector ID or friendly label.

Prerequisites

Before you start, make sure you have:

Installed the Coordimap agent in an environment that can reach the PostgreSQL server.
Added the PostgreSQL data source in the Coordimap UI so you have a data_source_id.
Created a read-only PostgreSQL user for the agent.

Use a read-only user

Use a dedicated read-only PostgreSQL user whenever possible. Follow the setup guide here: PostgreSQL Read-Only User.

Find The Correct `scope_id`

Use the PostgreSQL system identifier:

SELECT system_identifier FROM pg_control_system();

If pg_control_system() is unavailable in your environment, retrieve the same value with PostgreSQL system tooling such as pg_controldata.

Configuration File Structure

coordimap:
  api_key: ${COORDIMAP_API_KEY}
  data_sources:
    - type: postgres
      data_source_id: <YOUR_DATASOURCE_ID_FROM_UI>
      config:
        - name: scope_id
          value: "<POSTGRES_SYSTEM_IDENTIFIER>"
        - name: db_name
          value: "mydatabase"
        - name: db_host
          value: "postgres.example.com"
        - name: db_port
          value: "5432"
        - name: db_user
          value: "coordimap_readonly_user"
        - name: db_pass
          value: ${POSTGRES_PASSWORD}
        - name: ssl_mode
          value: "require"
        - name: crawl_interval
          value: "10m"

Configuration Options

Attribute Name	Required	Description
`type`	Yes	The data source type. For PostgreSQL this must be `postgres`.
`data_source_id`	Yes	The Coordimap data source identifier created in the UI. It identifies the connector record, not the PostgreSQL server identity.
`config.name: scope_id`	Yes	Stable upstream identity for the PostgreSQL server or cluster. Use `system_identifier`.
`config.name: db_name`	Yes	The PostgreSQL database name to connect to.
`config.name: db_host`	Yes	Hostname or IP address of the PostgreSQL server.
`config.name: db_port`	No	PostgreSQL port. If omitted, the standard PostgreSQL default is typically used.
`config.name: db_user`	Yes	Database user the agent connects with. Use a read-only user.
`config.name: db_pass`	Yes	Password for `db_user`. Prefer an environment variable.
`config.name: ssl_mode`	No	SSL mode such as `disable`, `allow`, `prefer`, `require`, `verify-ca`, or `verify-full`.
`config.name: crawl_interval`	No	How often the agent refreshes the schema inventory. See Shared Configuration Options.

Why `scope_id` Matters For PostgreSQL

PostgreSQL assets should stay attached to the same upstream server identity even if you recreate the Coordimap connector or move the crawler. Reusing the same scope_id keeps database object identities stable and avoids duplicate graph objects for the same server lineage.

Next Steps

Create or verify the read-only PostgreSQL user.
Add the PostgreSQL block to the agent YAML file.
Set COORDIMAP_API_KEY and any database password environment variables.
Restart the agent.
Verify that the PostgreSQL schema appears in Coordimap after the next crawl cycle.