PostgreSQL Plugin

TLS settings location

TLS modes, CA/client certificates and keys, server names and verification options are grouped under Security > TLS. Endpoint/port fields keep their original location. Grouping does not change field keys, saved values, defaults, sensitive handling, visibility or validation.

CloudNativePG exporter preset

For external collection, choose the metric source first, then select Exporter preset → CloudNativePG (CNPG) in Metrics (metric_exporter=cnpg). The default remains postgres_exporter; Konduo-managed collection continues to use its own standard mapping.

The preset returns a complete postgresql-cnpg-prometheus-pack-v1 pack. It reuses database statistics and adjusts connections, collector status, settings units, WAL and replication names. Checkpointer counters support PostgreSQL before and after 17. An empty metric prefix uses CNPG names directly; an existing cnpg_ prefix (including replacement from pg_) is applied exactly once. Use actual scrape labels, for example job="konduo-postgresql" and the relevant pod/namespace/cluster labels. Do not assume every series has a cluster label.

Mappings and corrections belong to each resource, independently of other resources sharing its metric source. Choose an exporter preset, then diagnose, edit and validate corrections as needed. Share reviewed corrections through JSON export/import. The preset is based on CNPG default monitoring, not arbitrary custom SQL collectors.

CNPG aggregate transaction durations do not provide PID identity. Unsupported PID charts, last-replay age and detailed recovery-conflict charts are declared unsupported and optional. Their default panels hide through when_available; supported empty, stale or failed queries remain visible. Older bgwriter counters may be absent after PostgreSQL 17; absence alone is not a capability declaration.

References: CNPG monitoring and default query definitions.

Basic accessibility observation

Resource overviews show accessible, inaccessible, or access unknown independently of metric sources. Successful access does not attest healthy membership, replication, partitions, or workloads; use domain diagnostics and alerts for those conditions. Existing liveness/readiness fields are domain evidence and do not drive the single core-owned access alarm. Unknown observations do not resolve firing incidents.

TLS

Set a TLS-only sslmode and paste a private CA into tls_ca_cert (PEM) to verify the server without a CA file. With a CA, sslmode=require becomes verify-full; tls_server_name can select the certificate DNS name. For mutual TLS, provide tls_client_cert and tls_client_key together. tls_insecure_skip_verify=true instead bypasses server verification, including PGSSLROOTCERT, without falling back to plaintext. It cannot be combined with sslmode=disable and defaults to false.

Resource Metrics settings keep corrections and revision history independently, even when resources share a Prometheus source. Use JSON export/import to share corrections after reviewing the selected preset and base version. Old dashboard keys are explicit alias_of aliases; edit the canonical postgres.* metric instead. Diagnosis checks instant and range independently. No data alone is not a mapping error: first check collection, labels and connectivity.

Chart value semantics

Exporter scrape status maps 0 to success and 1 to failure; it is not an error count. Replica role and boolean logging settings have their own localized meanings without implying health. Mapping v4 preserves target observations for these states. Counts use integers and percentage gauges use 0–100.

Overview combines six compact connection/transaction values with five workload and query-quality trends (11 panels). Storage/WAL keeps four compact values, a full-width database-size comparison and four checkpoint trends (9 panels). Replication has four compact values, four trends including logging history, and six configuration values in the collapsed settings row (14 panels).

Counts, states and durations use numeric cards; connection utilization retains its percentage gauge. All 34 panel keys, query definitions, units and saved personalized layouts remain available.

The PostgreSQL plugin registers PostgreSQL servers as Konduo resources and connects connection, replication, vacuum, lock, transaction, and query activity signals to the operator UI.

Highlights

• Collects server state and operational snapshots with read-only SQL queries.
• Supports both Prometheus mapping packs and Konduo-managed PostgreSQL metric collection.
• Focuses dashboards on availability evidence, connection pressure, transaction age, lock activity, replication lag, and cache/write behavior.
• Separates diagnostics for connectivity, permissions, metric coverage, replication, and bloat/vacuum risk.

Before Registration

• Prepare PostgreSQL host, port, database, username, password, and TLS settings.
• Use a least-privilege account that can run the required read-only diagnostic queries.
• Tune timeouts for managed collection so diagnostic queries do not add unexpected load.
• When Prometheus is the managed collection write target, run Prometheus with --web.enable-remote-write-receiver.

Operations Tips

• Review connection pressure together with max connection settings.
• Interpret replication lag with primary/replica role, WAL receiver state, and apply delay.
• For long transactions, lock waits, and delayed vacuum, read diagnostic snapshots together with metric trends.
• Treat an idle-in-transaction alert as a pg_stat_activity backend session problem. Managed collection uses PID and transaction start time to verify continuity, so a replacement transaction starts a new alert hold period. Inspect PID, user, database, client, last query, and transaction age together.

Operator Views

• The activity view shows session state, long-running queries, transaction age, and wait events in units an operator can act on.
• The idle transaction sessions view lists only idle in transaction sessions with PID, user, database, application, client, transaction start, state-change time, and last query.
• The locks view exposes blocking and blocked relationships plus lock mode to support cancel or terminate decisions.
• The replication view combines primary/standby role, replay/apply lag, receiver state, and archiver evidence.
• The storage/vacuum view connects database size, dead tuples, autovacuum, and vacuum/analyze needs to diagnostic evidence.
• Failover-planning evidence helps review current role and replication state; automatic failover orchestration is outside CE scope.

Idle In Transaction Response

• PostgreSQL idle in transaction means a backend session is idle while a transaction remains open. Even without an active query, it can hold locks, delay vacuum visibility, and consume connection pool capacity.
• Konduo-owned PostgreSQL connections set idle_in_transaction_session_timeout by default so a Konduo-side bug is less likely to leave an indefinite idle transaction in Konduo's own database.
• In managed collection mode, the Long Transaction alert tracks client backends in the current database by PID and transaction start time. PostgreSQL background work and idle in transaction sessions are excluded, and a replacement transaction cannot inherit the previous transaction's hold period.
• When a target PostgreSQL resource raises the alert, open the idle transaction sessions view first and identify the PID and ownership context.
• If a query is active, consider query cancellation first. For a pure idle in transaction session, there is no running statement to cancel, so application-owner coordination or backend termination after impact review is usually the practical response.
• Before termination, preserve the user, database, application name, client address, last query, and transaction age as evidence, and keep audit and confirmation boundaries intact.

Diagnostics And Alerts

• Diagnostics separate connectivity and permission checks, connection pressure, lock contention, long transactions, vacuum/bloat, replication, and WAL/checkpoint risk.
• Alert rules cover scrape health, connection utilization, long transactions, lock contention, cache/temp pressure, checkpoint/WAL pressure, replication lag, and archiver health.
• Managed collection converts read-only SQL snapshots into postgres_exporter-style samples and isolates them with the resource identity label.
• When historical evidence is missing, inspect the metric source or mapping pack instead of assuming PostgreSQL is healthy.

Management Boundary

• Arbitrary SQL console access is intentionally not provided.
• Query cancel, backend terminate, analyze, and vacuum analyze are management actions that require confirmation, reason, and safe-mode override when applicable.
• A resource marked as the Konduo runtime database blocks those management mutations entirely. Safe mode remains a confirmation guard and is not a substitute for a read-only database role.
• Terminating an idle-in-transaction session can abort user work, so treat it as an impact-reviewed operation rather than a simple alert cleanup.
• Schema/table changes, user and role management, backup/restore, and replication topology changes are outside the CE operating boundary.
• Even read-only accounts can lack catalog-view permissions, so distinguish partial diagnostic evidence from actual PostgreSQL health.

Example Workflows

• For connection saturation, inspect active/idle sessions, max connections, pooler settings, and long transactions together.
• For Idle In Transaction Sessions alerts, open the dedicated view to identify PID and last query, then review pooler or application transaction boundaries.
• For lock waits, review the blocking session, query age, wait event, and workload impact before choosing cancel or terminate.
• For delayed vacuum, compare dead tuples, autovacuum activity, transaction age, and table-size growth.
• For replica lag, combine WAL generation, receiver state, replay lag, and network or storage latency evidence.

Connection utilization requires a positive observed pg_settings_max_connections. Missing or invalid zero capacity remains unavailable; an observed pool with zero connections and valid capacity correctly reports 0%.

---

PostgreSQL Enterprise Overlay

TLS settings location

TLS modes, CA/client certificates and keys, server names and verification options are grouped under Security > TLS. Endpoint/port fields keep their original location. Grouping does not change field keys, saved values, defaults, sensitive handling, visibility or validation.

CloudNativePG exporter preset

For external collection, choose the metric source first, then select Exporter preset → CloudNativePG (CNPG) in Metrics (metric_exporter=cnpg). The default remains postgres_exporter; Konduo-managed collection continues to use its own standard mapping.

The preset returns a complete postgresql-cnpg-prometheus-pack-v1 pack. It reuses database statistics and adjusts connections, collector status, settings units, WAL and replication names. Checkpointer counters support PostgreSQL before and after 17. An empty metric prefix uses CNPG names directly; an existing cnpg_ prefix (including replacement from pg_) is applied exactly once. Use actual scrape labels, for example job="konduo-postgresql" and the relevant pod/namespace/cluster labels. Do not assume every series has a cluster label.

Mappings and corrections belong to each resource, independently of other resources sharing its metric source. Choose an exporter preset, then diagnose, edit and validate corrections as needed. Share reviewed corrections through JSON export/import. The preset is based on CNPG default monitoring, not arbitrary custom SQL collectors.

CNPG aggregate transaction durations do not provide PID identity. Unsupported PID charts, last-replay age and detailed recovery-conflict charts are declared unsupported and optional. Their default panels hide through when_available; supported empty, stale or failed queries remain visible. Older bgwriter counters may be absent after PostgreSQL 17; absence alone is not a capability declaration.

References: CNPG monitoring and default query definitions.

Basic accessibility observation

Resource overviews show accessible, inaccessible, or access unknown independently of metric sources. Successful access does not attest healthy membership, replication, partitions, or workloads; use domain diagnostics and alerts for those conditions. Existing liveness/readiness fields are domain evidence and do not drive the single core-owned access alarm. Unknown observations do not resolve firing incidents.

TLS

Set a TLS-only sslmode and paste a private CA into tls_ca_cert (PEM) to verify the server without a CA file. With a CA, sslmode=require becomes verify-full; tls_server_name can select the certificate DNS name. For mutual TLS, provide tls_client_cert and tls_client_key together. tls_insecure_skip_verify=true instead bypasses server verification, including PGSSLROOTCERT, without falling back to plaintext. It cannot be combined with sslmode=disable and defaults to false.

Resource Metrics settings keep corrections and revision history independently, even when resources share a Prometheus source. Use JSON export/import to share corrections after reviewing the selected preset and base version. Old dashboard keys are explicit alias_of aliases; edit the canonical postgres.* metric instead. Diagnosis checks instant and range independently. No data alone is not a mapping error: first check collection, labels and connectivity.

Chart value semantics

Exporter scrape status maps 0 to success and 1 to failure; it is not an error count. Replica role and boolean logging settings have their own localized meanings without implying health. Mapping v4 preserves target observations for these states. Counts use integers and percentage gauges use 0–100.

Overview combines six compact connection/transaction values with five workload and query-quality trends (11 panels). Storage/WAL keeps four compact values, a full-width database-size comparison and four checkpoint trends (9 panels). Replication has four compact values, four trends including logging history, and six configuration values in the collapsed settings row (14 panels).

Counts, states and durations use numeric cards; connection utilization retains its percentage gauge. All 34 panel keys, query definitions, units and saved personalized layouts remain available.

The PostgreSQL Enterprise overlay adds MCP descriptors, advanced diagnostics, log evidence mapping, metric mapping, and anomaly rules to PostgreSQL resources. It summarizes session, lock, connection, replication, storage, and vacuum state as operator evidence.

Highlights

• Provides database info, monitoring overview, connectivity checks, diagnostics, topology, and metric mapping through MCP.
• Includes session, lock, connection, configuration, replication, and storage/vacuum evidence in diagnostics.
• Connects PostgreSQL diagnostics to an Enterprise log source through log evidence mapping.
• Evaluates PostgreSQL logical metrics through declarative metric anomaly rules.
• Connects the Community idle-in-transaction session view and PID-based action path with Enterprise log evidence, MCP lookup, and anomaly analysis.

Before Registration

• Community PostgreSQL connectivity and read permissions must be healthy.
• Prepare Prometheus postgres exporter mapping and an OpenSearch log source when log evidence is needed.
• Confirm topology read permissions for replication and failover planning context.

Operations Tips

• Interpret lock waits, connection saturation, and replication lag together with application deployments and vacuum state.
• Treat Idle In Transaction Sessions alerts as pg_stat_activity backend session evidence, not as a separate transaction inventory. Managed collection uses PID and transaction start time to verify continuity, so a replacement transaction starts a new alert hold period.
• In managed collection mode, the Long Transaction alert tracks client backends in the current database by PID and transaction start time. PostgreSQL background work and idle in transaction sessions are excluded, and a replacement transaction cannot inherit the previous transaction's hold period.
• A pure idle in transaction session may not have an active query to cancel; review PID, user, database, client, last query, transaction age, and application logs before deciding whether termination is appropriate.
• Failover descriptors provide planning and inventory context; actual state changes need separate authorization and audit boundaries.

Operational Scenarios

• For API latency or transaction backlog, inspect sessions, locks, connection pools, vacuum state, and replication lag in one flow.
• When idle-in-transaction alerts fire, open the dedicated session list to identify PID and last query, then use same-window OpenSearch log evidence to trace application transaction boundaries.
• During incident analysis, connect PostgreSQL diagnostics to OpenSearch log evidence and compare application and database errors from the same time window.
• Use failover planning context for topology and inventory review; perform actual role changes through approved operational procedures.

Boundaries

• Resources marked as the Konduo runtime database block query cancellation, session termination, ANALYZE, and VACUUM management actions. Safe mode is a confirmation guard, not a read-only database role.
• The EE overlay provides advanced diagnostics, log evidence mapping, and anomaly metadata. It does not automatically run destructive maintenance.
• Without PostgreSQL metric mapping, storage, vacuum, and replication anomalies should remain unavailable or partial evidence.
• Terminating idle-in-transaction sessions can abort user work, so Enterprise correlation analysis must not execute it automatically.

Connection utilization requires a positive observed pg_settings_max_connections. Missing or invalid zero capacity remains unavailable; an observed pool with zero connections and valid capacity correctly reports 0%.

MCP diagnostic execution effects

The run_diagnostics tool changes diagnostic execution and cooldown state. Its descriptor declares operation_class: diagnostic_lifecycle; MCP advertises readOnlyHint=false, destructiveHint=false and idempotentHint=false. Diagnostic queries retain read-only hints. Both queries and actions continue to require mcp:invoke and the existing resource permissions/audit checks. Safety hints do not change authorization or guarantee safe retries.

MCP tool input contracts

Connection checks, database metadata, replication inspection, failover planning, static catalogs, and maintenance operation inventory accept {}. Session and lock inspection expose pagination and row filters. Historical evidence declares lookback, metric_source_id, and log_source_id; topology accepts comma-separated host instance IDs. Dynamic selector and legacy alias inputs remain supported on the routes that consume them.

The advertised JSON Schema is checked before plugin dispatch. Omitted optional values retain plugin defaults. Arguments do not replace resource-instance authorization; stored connection credentials are supplied by Konduo. Open schemas are retained only for existing dynamic filters or aliases, and each advertised property describes its caller-facing meaning. Plugin result shapes can vary with product/version, available evidence, and partial failures; no stable outputSchema is promised for these dynamic responses. Client and resource coverage rules are defined in enterprise/backend/docs/plugin-contract.md in the Enterprise source repository.