genai-toolbox/docs/en/resources/tools/postgres/postgres-replication-stats.md at b6835aedd33459efbd2fa77dcc01399cfa980caf

mirror of https://github.com/googleapis/genai-toolbox.git synced 2026-02-04 20:25:05 -05:00

Files

Yuan Teoh 293c1d6889 feat!: update configuration file v2 (#2369 )

This PR introduces a significant update to the Toolbox configuration
file format, which is one of the primary **breaking changes** required
for the implementation of the Advanced Control Plane.

# Summary of Changes
The configuration schema has been updated to enforce resource isolation
and facilitate atomic, incremental updates.
* Resource Isolation: Resource definitions are now separated into
individual blocks, using a distinct structure for each resource type
(Source, Tool, Toolset, etc.). This improves readability, management,
and auditing of configuration files.
* Field Name Modification: Internal field names have been modified to
align with declarative methodologies. Specifically, the configuration
now separates kind (general resource type, e.g., Source) from type
(specific implementation, e.g., Postgres).

# User Impact
Existing tools.yaml configuration files are now in an outdated format.
Users must eventually update their files to the new YAML format.

# Mitigation & Compatibility
Backward compatibility is maintained during this transition to ensure no
immediate user action is required for existing files.
* Immediate Backward Compatibility: The source code includes a
pre-processing layer that automatically detects outdated configuration
files (v1 format) and converts them to the new v2 format under the hood.
* [COMING SOON] Migration Support: The new toolbox migrate subcommand
will be introduced to allow users to automatically convert their old
configuration files to the latest format.

# Example
Example for config file v2:
```
kind: sources
name: my-pg-instance
type: cloud-sql-postgres
project: my-project
region: my-region
instance: my-instance
database: my_db
user: my_user
password: my_pass
---
kind: authServices
name: my-google-auth
type: google
clientId: testing-id
---
kind: tools
name: example_tool
type: postgres-sql
source: my-pg-instance
description: some description
statement: SELECT * FROM SQL_STATEMENT;
parameters:
- name: country
  type: string
  description: some description
---
kind: tools
name: example_tool_2
type: postgres-sql
source: my-pg-instance
description: returning the number one
statement: SELECT 1;
---
kind: toolsets
name: example_toolset
tools:
- example_tool
```

---------

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>
Co-authored-by: Averi Kitsch <akitsch@google.com>

2026-01-27 16:58:43 -08:00

2.8 KiB

Raw Blame History

title, type, weight, description, aliases

title

type

weight

description

aliases

postgres-replication-stats

docs

The "postgres-replication-stats" tool reports replication-related metrics for WAL streaming replicas, including lag sizes presented in human-readable form.

/resources/tools/postgres-replication-stats

About

The postgres-replication-stats tool queries pg_stat_replication to surface the status of connected replicas. It reports application_name, client address, connection and sync state, and human-readable lag sizes (sent, write, flush, replay, and total) computed using WAL LSN differences.

Compatible sources:

This tool takes no parameters. It returns a JSON array; each element represents a replication connection on the primary and includes lag metrics formatted by pg_size_pretty.

Example

kind: tools
name: replication_stats
type: postgres-replication-stats
source: postgres-source
description: "Lists replication connections and readable WAL lag metrics."

Example response element:

{
  "pid": 12345,
  "usename": "replication_user",
  "application_name": "replica-1",
  "backend_xmin": "0/0",
  "client_addr": "10.0.0.7",
  "state": "streaming",
  "sync_state": "sync",
  "sent_lag": "1234 kB",
  "write_lag": "12 kB",
  "flush_lag": "0 bytes",
  "replay_lag": "0 bytes",
  "total_lag": "1234 kB"
}

Reference

field	type	required	description
pid	integer	true	Process ID of the replication backend on the primary.
usename	string	true	Name of the user performing the replication connection.
application_name	string	true	Name of the application (replica) connecting to the primary.
backend_xmin	string	false	Standby's xmin horizon reported by hot_standby_feedback (may be null).
client_addr	string	false	Client IP address of the replica (may be null).
state	string	true	Connection state (e.g., streaming).
sync_state	string	true	Sync state (e.g., async, sync, potential).
sent_lag	string	true	Human-readable size difference between current WAL LSN and sent_lsn.
write_lag	string	true	Human-readable write lag between sent_lsn and write_lsn.
flush_lag	string	true	Human-readable flush lag between write_lsn and flush_lsn.
replay_lag	string	true	Human-readable replay lag between flush_lsn and replay_lsn.
total_lag	string	true	Human-readable total lag between current WAL LSN and replay_lsn.

2.8 KiB Raw Blame History

About

Example

Reference

2.8 KiB

Raw Blame History