diff --git a/docs/configuration/pgdog.toml/general.md b/docs/configuration/pgdog.toml/general.md index 07bd4e10..98755f6b 100644 --- a/docs/configuration/pgdog.toml/general.md +++ b/docs/configuration/pgdog.toml/general.md @@ -722,12 +722,6 @@ Replication lag threshold (in bytes) at which PgDog will pause traffic automatic Default: **`1_000_000`** (1 MiB) -### `cutover_save_config` - -Save the swapped configuration to disk after a [traffic cutover](../../features/sharding/resharding/cutover.md#swap-the-configuration). When enabled, PgDog will backup both configuration files as `pgdog.bak.toml` and `users.bak.toml`, and write the new configuration to `pgdog.toml` and `users.toml`. - -Default: **`false`** (disabled) - ### `cutover_replication_lag_threshold` Replication lag (in bytes) that must be reached before PgDog will [swap the configuration](../../features/sharding/resharding/cutover.md#swap-the-configuration) during a cutover. diff --git a/docs/enterprise_edition/mcp.md b/docs/enterprise_edition/mcp.md new file mode 100644 index 00000000..5327adbf --- /dev/null +++ b/docs/enterprise_edition/mcp.md @@ -0,0 +1,159 @@ +--- +icon: material/robot +--- + +# MCP + +!!! note "New feature" + + MCP is a new feature. Please test it before deploying to production. + +MCP (model context protocol) allows coding agents and harnesses to fetch real time PgDog metrics, logs and deployment information to help debug production incidents or configuration issues. + +## How it works + +MCP is an HTTP protocol and most coding harnesses, e.g., Codex, Pi, Claude Code support it out of the box. It's disabled by default, so to enable MCP you need to set the following config in the [control plane](control_plane/index.md): + +=== "Helm chart" + + ```yaml + control: + config: + mcp: + enabled: true + ``` + +=== "control.toml" + + ```toml + [mcp] + enabled = true + ``` + +When enabled, the MCP server will be running on the same host and port as the control plane, under the `/mcp` path. + +### Authentication + +Requests to the MCP server require Bearer token authentication. Unauthenticated requests will be rejected automatically. To configure authentication, you have two options: + +1. Hardcode a set of tokens in the configuration +2. Enable [Raft](control_plane/ha.md) and add tokens via the web dashboard + +#### Configuring tokens + +A fixed set of Bearer tokens can be configured as follows: + +=== "Helm chart" + + ```yaml + control: + config: + mcp: + enabled: true + tokens: + - token_one + - token_two + ``` + +=== "control.toml" + + ```toml + [mcp] + enabled = true + tokens = ["token_one", "token_two"] + ``` + +If you're running our [Helm chart](control_plane/installation.md), you can also load a comma-separated list of tokens from a Kubernetes Secret. + +#### Create a Secret + +Create the Secret in the same namespace as the control plane: + +```yaml title="mcp-secret.yaml" +apiVersion: v1 +kind: Secret +metadata: + name: pgdog-mcp-tokens +type: Opaque +stringData: + tokens: "token_one,token_two" +``` + +Once the Secret is created, you can reference it in the Helm chart values: + +```yaml title="values.yaml" +control: + config: + mcp: + enabled: true + secret: + name: pgdog-mcp-tokens + tokensKey: tokens +``` + +#### Dynamic tokens + +Managing tokens via configuration can be tedious, so the control plane also supports storing authorized tokens in its [Raft](control_plane/ha.md) log. Stored tokens are checked on each request to the MCP server, so tokens can be created and deleted at any time without configuration changes. + +
+ MCP Add token +
+ +### Configuring agents + +Most agent harnesses support MCP out of the box, so configuring PgDog's MCP server should be pretty straightforward. + +#### Codex + +To add the MCP server to Codex, you can add it to either `.codex/config.toml` or `~/.codex/config.toml` as follows: + +```toml title=".codex/config.toml" +[mcp_servers.pgdog] +url = "https://control.example.com/mcp" +http_headers = { Authorization = "Bearer " } +``` + +## Tools + +!!! info "Tools are read-only" + + All PgDog MCP tools are read-only and don't have any side effects. This makes them pretty safe to use + with or without human supervision. + +The MCP server comes with four tools: + +| Tool | Description | +| ----------------------- | ------------------------------------------------------------------------------------------------------------------------- | +| `pgdog.proxy_instances` | Show an up-to-date list of PgDog instances currently running. | | +| `pgdog.proxy_metrics` | Fetch real-time PgDog metrics. The tool allows you to filter by database/user, by Kube instance name, and by time window. | +| `pgdog.proxy_logs` | Fetch real-time logs from Kube containers running PgDog. | +| `pgdog.auth_check` | A no-op tool that allows you to verify if the harness has the correct Bearer token. | + +An agent typically doesn't need special instructions to use these tools. For example, a common prompt to debug a production incident could be: + +=== "Prompt" + + ``` + Give me the state of PgDog. + ``` + +=== "Output" + + ``` + PgDog looks operational across the five reporting instances, as of 1:39 PM PST, November 10. + + All five report running, with fresh telemetry and the same version: v0.1.64-v2026-11-03, commit 295f5ea. None reports maintenance mode or a pending reload. + + | Instance | Clients | CPU | Memory | + |---|---:|---:|---:| + | Staging 87mh9 | 11 | 40.9% | 52.4 MiB | + | Staging fqs8t | 16 | 54.8% | 52.7 MiB | + | Sharded 0 | 7 | 10.1% | 11.6 MiB | + | Sharded 1 | 13 | 15.7% | 14.7 MiB | + | Resharding 0 | 0 | 0.2% | 7.1 MiB | + + - No clients currently waiting for backend connections across reported pools. + - No warnings or errors in the recent log tails inspected. + - Staging CPU is the main watch item: observed peaks reached 97.7% and 92.5%. Pool queues peaked at six waiting clients, but are now clear. + - Resharding: no client traffic; logs show destination schema synchronization. + ``` diff --git a/docs/features/sharding/resharding/cutover.md b/docs/features/sharding/resharding/cutover.md index 65f99a56..6f65b0b1 100644 --- a/docs/features/sharding/resharding/cutover.md +++ b/docs/features/sharding/resharding/cutover.md @@ -82,19 +82,7 @@ If something goes wrong after the traffic is moved to the new (destination) data For this to work, the original database must remain in the [configuration files](../../../configuration/index.md), so PgDog performs a swap: source becomes destination and destination becomes the source database. This is the equivalent of running `sed s/source/destination/g` (and vice versa) on both `pgdog.toml` and `users.toml` files, making sure the clients don't know the databases have been changed. -The configuration swap happens in memory, but PgDog has the ability to write the new configuration files to disk as well. This is disabled by default, but can be enabled with a setting: - -=== "pgdog.toml" - ```toml - [general] - cutover_save_config = true - ``` -=== "Helm chart" - ```yaml - cutoverSaveConfig: true - ``` - -When enabled, PgDog will backup both configuration files, `pgdog.toml` as `pgdog.bak.toml` and `users.toml` as `users.bak.toml`, and save its in-memory configuration to `pgdog.toml` and `users.toml` respectively, so the new cutover configuration persists in case of an error. +The configuration swap happens in memory. !!! note "Multi-node deployments" If you're running more than one PgDog node, you should consider deploying our [Enterprise Edition](../../../enterprise_edition/index.md), which has support for saving the configuration files on multiple PgDog nodes at the same time. @@ -167,10 +155,7 @@ To restore traffic to the original cluster, run a `CUTOVER` against the reverse CUTOVER ; ``` -This performs the same atomic swap in reverse: the source and destination are swapped back in `pgdog.toml` and `users.toml`, and traffic returns to the original cluster. Because the reverse stream kept the original cluster in sync, no data written to the new cluster is lost. The task's status in `SHOW TASKS` shows `rolling back` while this happens. - -!!! note "Restoring the configuration files" - The rollback swaps the configuration back in memory (and on disk when [`cutover_save_config`](#swap-the-configuration) is enabled). If you enabled `cutover_save_config`, the configuration as it was before the original cutover is also preserved in the `pgdog.bak.toml` and `users.bak.toml` backups, so you can always restore the previous state by hand. +This performs the same atomic swap in reverse: the source and destination are swapped back in memory, and traffic returns to the original cluster. Because the reverse stream kept the original cluster in sync, no data written to the new cluster is lost. The task's status in `SHOW TASKS` shows `rolling back` while this happens. ### Finalizing the migration diff --git a/docs/images/ee/mcp_system.png b/docs/images/ee/mcp_system.png new file mode 100644 index 00000000..0091674d Binary files /dev/null and b/docs/images/ee/mcp_system.png differ diff --git a/tests/test_code_blocks.py b/tests/test_code_blocks.py index a6707f88..a2e025d4 100644 --- a/tests/test_code_blocks.py +++ b/tests/test_code_blocks.py @@ -23,7 +23,11 @@ def verify(binary): for file in glob.glob("docs/**/*.md", recursive=True): - skip_toml = file.startswith("docs/enterprise_edition/control_plane/") + # Control plane configuration cannot be validated by pgdog configcheck. + skip_toml = ( + file.startswith("docs/enterprise_edition/control_plane/") + or file == "docs/enterprise_edition/mcp.md" + ) with open(file, "r") as f: content = f.read() print(f"Checking {file}")