### Starting TiProxy Server

Source: https://context7.com/pingcap/tiproxy/llms.txt

Instructions on how to start the TiProxy server, including generating TLS certificates and running the `tiproxy` command with different configurations.

```APIDOC
## Starting TiProxy Server

The `tiproxy` command starts the proxy server with a configuration file specifying PD addresses, listening ports, and security settings.

```bash
# Generate TLS certificates for TiDB-TiProxy authentication
openssl req -x509 -newkey rsa:4096 -sha256 -days 3650 -nodes \
  -keyout key.pem -out cert.pem -subj "/CN=example.com"

# Start TiProxy with configuration file
bin/tiproxy --config=conf/proxy.toml

# Start with advertise address (for multi-node deployments)
bin/tiproxy --config=conf/proxy.toml --advertise-addr="192.168.1.100:6000"

# Connect to TiProxy (default port 6000)
mysql -h127.0.0.1 -uroot -P6000
```
```

--------------------------------

### Start TiProxy

Source: https://github.com/pingcap/tiproxy/blob/main/README.md

Start the TiProxy service using the specified configuration file.

```shell
bin/tiproxy --config=conf/proxy.toml
```

--------------------------------

### Starting and Connecting to TiProxy

Source: https://context7.com/pingcap/tiproxy/llms.txt

Commands to generate TLS certificates, start the proxy server, and connect via the MySQL client.

```bash
# Generate TLS certificates for TiDB-TiProxy authentication
openssl req -x509 -newkey rsa:4096 -sha256 -days 3650 -nodes \
  -keyout key.pem -out cert.pem -subj "/CN=example.com"

# Start TiProxy with configuration file
bin/tiproxy --config=conf/proxy.toml

# Start with advertise address (for multi-node deployments)
bin/tiproxy --config=conf/proxy.toml --advertise-addr="192.168.1.100:6000"

# Connect to TiProxy (default port 6000)
mysql -h127.0.0.1 -uroot -P6000
```

--------------------------------

### tiproxyctl CLI Tool

Source: https://context7.com/pingcap/tiproxy/llms.txt

Usage examples for the `tiproxyctl` command-line tool, demonstrating how to manage TiProxy configuration and check its health status.

```APIDOC
## tiproxyctl CLI Tool

The `tiproxyctl` command-line tool manages TiProxy configuration, namespaces, health status, and traffic operations through the HTTP API.

```bash
# Check TiProxy health status
tiproxyctl --host=127.0.0.1 --port=3080 health

# Get current configuration
tiproxyctl --host=127.0.0.1 --port=3080 config get

# Update configuration from file
tiproxyctl --host=127.0.0.1 --port=3080 config set --input=new-config.toml

# With TLS authentication
tiproxyctl --host=127.0.0.1 --port=3080 \
  --ca=ca.pem --cert=client-cert.pem --key=client-key.pem \
  health

# Skip TLS verification (testing only)
tiproxyctl --host=127.0.0.1 --port=3080 -k health
```
```

--------------------------------

### Configuration File (proxy.toml)

Source: https://context7.com/pingcap/tiproxy/llms.txt

An example of the `proxy.toml` configuration file, detailing settings for proxy behavior, API, security, logging, and load balancing.

```APIDOC
## Configuration File (proxy.toml)

The main configuration file controls proxy behavior, API settings, security, logging, and load balancing policies.

```toml
# Working directory for TiProxy data
workdir = "./work"

[proxy]
# SQL proxy listening address
addr = "0.0.0.0:6000"
# Advertise address for cluster communication
advertise-addr = ""
# PD addresses for TiDB cluster discovery
pd-addrs = "127.0.0.1:2379"
# Maximum client connections (0 = unlimited)
max-connections = 0
# Connection buffer size (1K to 16M, 0 = default)
conn-buffer-size = 0
# Proxy protocol support: "" (disabled) or "v2"
proxy-protocol = ""
# Seconds to wait before shutdown (for NLB drain)
graceful-wait-before-shutdown = 0
# Seconds to drain connections before force close
graceful-close-conn-timeout = 15

[api]
# HTTP API listening address
addr = "0.0.0.0:3080"
# Proxy protocol for HTTP: "" or "v2"
proxy-protocol = ""

[log]
# Log level: debug, info, warn, error
level = "info"
# Log format: tidb, json, console
encoder = "tidb"

[log.log-file]
filename = "/var/log/tiproxy/tiproxy.log"
max-size = 300    # MB
max-days = 3
max-backups = 3

[security]
# TLS for accessing TiDB/PD cluster
[security.cluster-tls]
# skip-ca = true

# TLS for connecting to TiDB SQL port
[security.sql-tls]
skip-ca = true

# TLS for proxy SQL port (server-side)
[security.server-tls]
# auto-certs = true
# cert = "server-cert.pem"
# key = "server-key.pem"

# TLS for proxy HTTP port
[security.server-http-tls]
# auto-certs = true

[balance]
# Balance policy: resource, location, connection
policy = "resource"
# Routing policy: prefer-idle, random
routing-policy = "prefer-idle"
```
```

--------------------------------

### Define Namespace Configuration

Source: https://context7.com/pingcap/tiproxy/llms.txt

Example TOML configuration for defining frontend user mappings and backend TiDB instance pools.

```toml
# namespace.toml
namespace = "production"

[frontend]
user = "app_user"

[frontend.security]
# TLS settings for client connections
# cert = "client-cert.pem"
# key = "client-key.pem"

[backend]
instances = ["tidb1:4000", "tidb2:4000", "tidb3:4000"]

[backend.security]
# TLS settings for backend connections
# ca = "ca.pem"
# skip-ca = true
```

--------------------------------

### POST /api/traffic/replay

Source: https://github.com/pingcap/tiproxy/blob/main/docs/design/2024-08-27-traffic-replay.md

Starts a traffic replay job.

```APIDOC
## POST /api/traffic/replay

### Description
Starts the traffic replay process using specified input files and credentials.

### Method
POST

### Endpoint
/api/traffic/replay

### Request Body
- **input** (string) - Required - The directory path containing traffic files.
- **speed** (float) - Required - The replay speed multiplier.
- **username** (string) - Required - Database username.
- **password** (string) - Required - Database password.
```

--------------------------------

### POST /api/traffic/capture

Source: https://github.com/pingcap/tiproxy/blob/main/docs/design/2024-08-27-traffic-replay.md

Starts a traffic capture job.

```APIDOC
## POST /api/traffic/capture

### Description
Starts the traffic capture process for a specified duration and output directory.

### Method
POST

### Endpoint
/api/traffic/capture

### Request Body
- **duration** (string) - Required - The duration of the capture (e.g., 1m).
- **output** (string) - Required - The directory path where traffic files will be stored.
```

--------------------------------

### Traffic Replay API

Source: https://context7.com/pingcap/tiproxy/llms.txt

APIs for starting, showing, and canceling traffic replay sessions.

```APIDOC
## Traffic Replay

### Description
Traffic replay executes previously captured SQL traffic against a TiDB cluster for validation testing.

### Method
POST, GET

### Endpoint
`/api/traffic/replay`, `/api/traffic/show`, `/api/traffic/cancel`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body (for POST /api/traffic/replay)
- **input** (string) - Required - Path to the captured traffic file.
- **username** (string) - Required - Username for replay.
- **password** (string) - Required - Password for replay.
- **speed** (string) - Optional - Replay speed multiplier (e.g., `2.0`).
- **readonly** (boolean) - Optional - Whether to perform replay in read-only mode.
- **command-start-time** (string) - Optional - Start time for replaying commands (ISO 8601 format).
- **bufsize** (integer) - Optional - Buffer size for replay.
- **ps-close** (string) - Optional - Prepared statement close behavior.

### Request Example
```bash
# Start traffic replay
curl -X POST http://127.0.0.1:3080/api/traffic/replay \
  -d "input=/data/traffic-capture" \
  -d "username=replay_user" \
  -d "password=secret" \
  -d "speed=2.0" \
  -d "readonly=false"

# Show replay status
curl -X GET http://127.0.0.1:3080/api/traffic/show

# Cancel replay
curl -X POST http://127.0.0.1:3080/api/traffic/cancel
```

### Response
#### Success Response (200)
- **(Varies)** - Response indicates success or provides status information.

#### Response Example
```json
{"status": "replay started"}
```
```

--------------------------------

### Traffic Capture API

Source: https://context7.com/pingcap/tiproxy/llms.txt

APIs for starting, showing, and canceling traffic capture sessions.

```APIDOC
## Traffic Capture

### Description
Traffic capture records SQL traffic for later replay, useful for testing upgrades or validating new TiDB versions.

### Method
POST, GET

### Endpoint
`/api/traffic/capture`, `/api/traffic/show`, `/api/traffic/cancel`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body (for POST /api/traffic/capture)
- **output** (string) - Required - Path to save the captured traffic.
- **duration** (string) - Optional - Duration for the capture (e.g., `1h`).
- **compress** (boolean) - Optional - Whether to compress the captured traffic.
- **encrypt-method** (string) - Optional - Encryption method to use (e.g., `aes256-ctr`).

### Request Example
```bash
# Start traffic capture
curl -X POST http://127.0.0.1:3080/api/traffic/capture \
  -d "output=/data/traffic-capture" \
  -d "duration=1h" \
  -d "compress=true" \
  -d "encrypt-method=aes256-ctr"

# Show current traffic jobs
curl -X GET http://127.0.0.1:3080/api/traffic/show

# Cancel traffic capture
curl -X POST http://127.0.0.1:3080/api/traffic/cancel
```

### Response
#### Success Response (200)
- **(Varies)** - Response indicates success or provides status information.

#### Response Example
```json
{"status": "capture started"}
```
```

--------------------------------

### Namespace Management API

Source: https://context7.com/pingcap/tiproxy/llms.txt

API endpoints for managing namespaces in TiProxy, including listing, getting, creating/updating, deleting, and committing namespace configurations.

```APIDOC
## Namespace Management API

Namespaces provide multi-tenant isolation by routing connections based on usernames to specific TiDB backend instances.

```bash
# List all namespaces
curl -X GET http://127.0.0.1:3080/api/admin/namespace/

# Get specific namespace configuration
curl -X GET http://127.0.0.1:3080/api/admin/namespace/production

# Create or update namespace
curl -X PUT http://127.0.0.1:3080/api/admin/namespace/production \
  -H "Content-Type: application/json" \
  -d '{
    "namespace": "production",
    "frontend": {
      "user": "app_user"
    },
    "backend": {
      "instances": ["tidb1:4000", "tidb2:4000", "tidb3:4000"]
    }
  }'

# Delete namespace
curl -X DELETE http://127.0.0.1:3080/api/admin/namespace/staging

# Commit namespace changes (reload routing)
curl -X POST "http://127.0.0.1:3080/api/admin/namespace/commit?namespace=production"
```
```

--------------------------------

### TiProxy Traffic Log Format

Source: https://github.com/pingcap/tiproxy/blob/main/docs/design/2024-08-27-traffic-replay.md

This format is used for storing traffic logs, similar to slow logs, to support future field additions. The 'Time' field indicates the start time for ordered replay.

```log
# Time: 2024-01-19T16:29:48.141142Z
# Query_time: 0.01
# Conn_ID: 123
# Cmd_type: 3
# Rows_sent: 1
# Result_size: 100
# Payload_len: 8
SELECT 1
```

--------------------------------

### TiProxy HTTP API for Traffic Management

Source: https://github.com/pingcap/tiproxy/blob/main/docs/design/2024-08-27-traffic-replay.md

Provides endpoints for controlling traffic capture and replay operations via HTTP POST requests. Use these to start, stop, and manage traffic analysis.

```http
curl -X POST "localhost:3080/api/traffic/capture" -d "duration=1m&output=/tmp/traffic"
curl -X POST "localhost:3080/api/traffic/replay" -d "input=/tmp/traffic&speed=1.0&username=root&password=123456"
curl -X POST "localhost:3080/api/traffic/cancel"
curl -X GET "localhost:3080/api/traffic/show"
```

--------------------------------

### Build TiProxy Binary

Source: https://github.com/pingcap/tiproxy/blob/main/README.md

Build the TiProxy binary locally using the make command.

```shell
$ make
```

--------------------------------

### GET /api/traffic/show

Source: https://github.com/pingcap/tiproxy/blob/main/docs/design/2024-08-27-traffic-replay.md

Retrieves the status of traffic jobs.

```APIDOC
## GET /api/traffic/show

### Description
Displays the progress of the current job or the status of the last finished job.

### Method
GET

### Endpoint
/api/traffic/show
```

--------------------------------

### Manage Namespaces with tiproxyctl

Source: https://context7.com/pingcap/tiproxy/llms.txt

Commands to list, retrieve, update, delete, and import namespace configurations.

```bash
tiproxyctl --host=127.0.0.1 --port=3080 namespace list
tiproxyctl --host=127.0.0.1 --port=3080 namespace get production
tiproxyctl --host=127.0.0.1 --port=3080 namespace put --ns=namespace.toml
tiproxyctl --host=127.0.0.1 --port=3080 namespace del staging
tiproxyctl --host=127.0.0.1 --port=3080 namespace import ./namespaces/
```

--------------------------------

### Build TiProxy Docker Image

Source: https://github.com/pingcap/tiproxy/blob/main/README.md

Build a Docker image for TiProxy using the make docker command.

```shell
$ make docker
```

--------------------------------

### Run All Unit Tests

Source: https://github.com/pingcap/tiproxy/blob/main/AGENTS.md

Execute all unit tests across the entire repository by running the `go test` command with the `./...` argument from the root directory.

```bash
go test ./...
```

--------------------------------

### Define Proxy and Backend Cluster Configuration Structures

Source: https://github.com/pingcap/tiproxy/blob/main/docs/design/2026-03-17-multi-cluster-cluster-scoped-runtime.md

Core configuration structs for the proxy server and individual backend clusters, including balance settings.

```go
type ProxyServer struct {
    Addr            string
    AdvertiseAddr   string
    PDAddrs         string
    PortRange       []int
    BackendClusters []BackendCluster
    ProxyServerOnline
}

type BackendCluster struct {
    Name      string
    PDAddrs   string
    NSServers []string
}

type Balance struct {
    LabelName     string
    RoutingRule   string
    Policy        string
    RoutingPolicy string
    ...
}
```

--------------------------------

### Etcd Client Initialization

Source: https://github.com/pingcap/tiproxy/blob/main/docs/design/2026-03-17-multi-cluster-cluster-scoped-runtime.md

Initializes an etcd client with a custom DNS dialer and performs an initial membership sync.

```go
func InitEtcdClientWithAddrsAndDialer(
    logger *zap.Logger,
    pdAddrs string,
    tlsConfig *tls.Config,
    dnsDialer *netutil.DNSDialer,
) (*clientv3.Client, error)
```

--------------------------------

### Managing TiProxy with tiproxyctl

Source: https://context7.com/pingcap/tiproxy/llms.txt

CLI commands for managing configuration, health checks, and TLS-authenticated requests.

```bash
# Check TiProxy health status
tiproxyctl --host=127.0.0.1 --port=3080 health

# Get current configuration
tiproxyctl --host=127.0.0.1 --port=3080 config get

# Update configuration from file
tiproxyctl --host=127.0.0.1 --port=3080 config set --input=new-config.toml

# With TLS authentication
tiproxyctl --host=127.0.0.1 --port=3080 \
  --ca=ca.pem --cert=client-cert.pem --key=client-key.pem \
  health

# Skip TLS verification (testing only)
tiproxyctl --host=127.0.0.1 --port=3080 -k health
```

--------------------------------

### Configure TiProxy

Source: https://github.com/pingcap/tiproxy/blob/main/README.md

Configure TiProxy by specifying the addresses of all PD instances in the proxy.toml file.

```toml
[proxy]
    pd-addrs = "127.0.0.1:2379"
```

--------------------------------

### Run Per-Package Unit Tests

Source: https://github.com/pingcap/tiproxy/blob/main/AGENTS.md

Execute unit tests for a specific package by navigating to its directory and using the `go test` command with the `-run` flag to filter by test name.

```bash
cd pkg/<package_name> && go test -run <TestName>
```

--------------------------------

### Manage Configuration via API and tiproxyctl

Source: https://context7.com/pingcap/tiproxy/llms.txt

Retrieve or update TiProxy settings dynamically without server restarts.

```bash
# Get current configuration (TOML format)
curl -X GET http://127.0.0.1:3080/api/admin/config/

# Get configuration as JSON
curl -X GET http://127.0.0.1:3080/api/admin/config/ \
  -H "Accept: application/json"

# Get configuration with format parameter
curl -X GET "http://127.0.0.1:3080/api/admin/config/?format=json"

# Update configuration (TOML format)
curl -X PUT http://127.0.0.1:3080/api/admin/config/ \
  -H "Content-Type: text/plain" \
  -d '
[log]
level = "debug"

[balance]
policy = "connection"
'

# Using tiproxyctl
tiproxyctl --host=127.0.0.1 --port=3080 config get
tiproxyctl --host=127.0.0.1 --port=3080 config set --input=updated-config.toml
cat config-update.toml | tiproxyctl --host=127.0.0.1 --port=3080 config set
```

--------------------------------

### TiProxy Configuration File

Source: https://context7.com/pingcap/tiproxy/llms.txt

The proxy.toml file defines proxy behavior, API settings, logging, security, and load balancing policies.

```toml
# Working directory for TiProxy data
workdir = "./work"

[proxy]
# SQL proxy listening address
addr = "0.0.0.0:6000"
# Advertise address for cluster communication
advertise-addr = ""
# PD addresses for TiDB cluster discovery
pd-addrs = "127.0.0.1:2379"
# Maximum client connections (0 = unlimited)
max-connections = 0
# Connection buffer size (1K to 16M, 0 = default)
conn-buffer-size = 0
# Proxy protocol support: "" (disabled) or "v2"
proxy-protocol = ""
# Seconds to wait before shutdown (for NLB drain)
graceful-wait-before-shutdown = 0
# Seconds to drain connections before force close
graceful-close-conn-timeout = 15

[api]
# HTTP API listening address
addr = "0.0.0.0:3080"
# Proxy protocol for HTTP: "" or "v2"
proxy-protocol = ""

[log]
# Log level: debug, info, warn, error
level = "info"
# Log format: tidb, json, console
encoder = "tidb"

[log.log-file]
filename = "/var/log/tiproxy/tiproxy.log"
max-size = 300    # MB
max-days = 3
max-backups = 3

[security]
# TLS for accessing TiDB/PD cluster
[security.cluster-tls]
# skip-ca = true

# TLS for connecting to TiDB SQL port
[security.sql-tls]
skip-ca = true

# TLS for proxy SQL port (server-side)
[security.server-tls]
# auto-certs = true
# cert = "server-cert.pem"
# key = "server-key.pem"

# TLS for proxy HTTP port
[security.server-http-tls]
# auto-certs = true

[balance]
# Balance policy: resource, location, connection
policy = "resource"
# Routing policy: prefer-idle, random
routing-policy = "prefer-idle"
```

--------------------------------

### Connect to TiProxy

Source: https://github.com/pingcap/tiproxy/blob/main/README.md

Connect to TiProxy using a MySQL client. The default port is 6000.

```shell
mysql -h127.0.0.1 -uroot -P6000
```

--------------------------------

### Configure Load Balancing

Source: https://context7.com/pingcap/tiproxy/llms.txt

Define load balancing policies in the configuration file.

```toml
[balance]
# Balance policy options:
# - "resource": Balance based on CPU, memory, and health (default)
# - "location": Balance based on geographic location labels
```

--------------------------------

### Monitor Health and Redirect Connections

Source: https://context7.com/pingcap/tiproxy/llms.txt

Check proxy readiness status and trigger connection redirects for maintenance.

```bash
# Check health status (returns 200 OK when healthy, 502 when unhealthy)
curl -X GET http://127.0.0.1:3080/api/debug/health

# Using tiproxyctl
tiproxyctl --host=127.0.0.1 --port=3080 health

# Trigger connection redirect (for testing/maintenance)
curl -X POST http://127.0.0.1:3080/debug/redirect
```

--------------------------------

### Namespace Management with tiproxyctl

Source: https://context7.com/pingcap/tiproxy/llms.txt

Commands for managing namespaces using the tiproxyctl utility.

```APIDOC
## Namespace Management with tiproxyctl

### Description
Commands for managing namespaces using the tiproxyctl utility.

### Method
N/A (CLI commands)

### Endpoints
N/A (CLI commands)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```bash
tiproxyctl --host=127.0.0.1 --port=3080 namespace list
tiproxyctl --host=127.0.0.1 --port=3080 namespace get production
tiproxyctl --host=127.0.0.1 --port=3080 namespace put --ns=namespace.toml
tiproxyctl --host=127.0.0.1 --port=3080 namespace del staging
tiproxyctl --host=127.0.0.1 --port=3080 namespace import ./namespaces/
```

### Response
N/A (CLI output varies)
```

--------------------------------

### TiProxy Balance Configuration

Source: https://context7.com/pingcap/tiproxy/llms.txt

Configure balancing strategies and rate limits for TiProxy. Adjust migrations-per-second for different balancing factors like status, health, memory, CPU, location, and connection count. The count-ratio-threshold is used for connection count-based balancing.

```toml
# connection: Balance based on connection count only
policy = "resource"

# Routing policy for new connections:
# - "prefer-idle": Route to least loaded backend (default)
# - "random": Random backend selection
routing-policy = "prefer-idle"

# Label-based routing (matches TiDB server labels)
label-name = "zone"

# Migration rate limits per factor
[balance.status]
migrations-per-second = 10

[balance.health]
migrations-per-second = 100

[balance.memory]
migrations-per-second = 5

[balance.cpu]
migrations-per-second = 5

[balance.location]
migrations-per-second = 10

[balance.conn-count]
migrations-per-second = 10
count-ratio-threshold = 1.5
```

--------------------------------

### Configure TiDB for Token Authentication

Source: https://github.com/pingcap/tiproxy/blob/main/README.md

Update TiDB's config.toml to enable auto-TLS and configure session token signing certificate and key paths. The graceful-wait-before-shutdown setting is also included.

```toml
security.auto-tls=true
security.session-token-signing-cert={path/to/cert.pem}
security.session-token-signing-key={path/to/key.pem}
graceful-wait-before-shutdown=10
```

--------------------------------

### TiDB Server Configuration for TiProxy Session Migration

Source: https://context7.com/pingcap/tiproxy/llms.txt

Configure TiDB server settings to enable seamless session migration with TiProxy. This includes enabling auto TLS, specifying session token signing certificates and keys, and setting a graceful wait period before shutdown.

```toml
# TiDB config.toml
# Enable auto TLS between TiDB instances
security.auto-tls = true
# Session token signing for migration authentication
security.session-token-signing-cert = "/path/to/cert.pem"
security.session-token-signing-key = "/path/to/key.pem"
# Grace period before shutdown (allows migration)
graceful-wait-before-shutdown = 10
```

--------------------------------

### TiProxy pprof Debugging Endpoints

Source: https://context7.com/pingcap/tiproxy/llms.txt

Access TiProxy's Go pprof endpoints for performance profiling and debugging. Use curl commands to fetch CPU profiles, heap profiles, goroutine dumps, or view all available endpoints.

```bash
# CPU profile
curl -X GET "http://127.0.0.1:3080/debug/pprof/profile?seconds=30" > cpu.prof

# Heap profile
curl -X GET http://127.0.0.1:3080/debug/pprof/heap > heap.prof

# Goroutine dump
curl -X GET http://127.0.0.1:3080/debug/pprof/goroutine?debug=1

# All available pprof endpoints
curl -X GET http://127.0.0.1:3080/debug/pprof/
```

--------------------------------

### Configuration Management API

Source: https://context7.com/pingcap/tiproxy/llms.txt

APIs for retrieving and updating TiProxy configuration dynamically.

```APIDOC
## Configuration Management API

### Description
The configuration API allows dynamic updates to TiProxy settings without restarting the server.

### Method
GET, PUT

### Endpoint
`/api/admin/config/`

### Parameters
#### Path Parameters
None

#### Query Parameters
- **format** (string) - Optional - Specifies the desired response format (e.g., `json`).

#### Request Body
- **(text/plain)** - Required for PUT requests - The configuration content in TOML format.

### Request Example
```bash
# Get current configuration (TOML format)
curl -X GET http://127.0.0.1:3080/api/admin/config/

# Get configuration as JSON
curl -X GET http://127.0.0.1:3080/api/admin/config/ -H "Accept: application/json"

# Get configuration with format parameter
curl -X GET "http://127.0.0.1:3080/api/admin/config/?format=json"

# Update configuration (TOML format)
curl -X PUT http://127.0.0.1:3080/api/admin/config/ -H "Content-Type: text/plain" -d '
[log]
level = "debug"

[balance]
policy = "connection"
'
```

### Response
#### Success Response (200)
- **(text/plain or application/json)** - The current or updated configuration in the requested format.

#### Response Example
```json
{
  "log": {
    "level": "info"
  },
  "balance": {
    "policy": "resource"
  }
}
```
```

--------------------------------

### BackendInst Interface

Source: https://github.com/pingcap/tiproxy/blob/main/docs/design/2026-03-17-multi-cluster-cluster-scoped-runtime.md

Exposes cluster identity and backend metadata for routing decisions.

```go
type BackendInst interface {
    ID() string
    Addr() string
    Healthy() bool
    Local() bool
    Keyspace() string
    ClusterName() string
}
```

--------------------------------

### Access Prometheus Metrics

Source: https://context7.com/pingcap/tiproxy/llms.txt

Retrieve performance and health metrics in Prometheus-compatible format.

```bash
# Get Prometheus metrics
curl -X GET http://127.0.0.1:3080/metrics/
```

--------------------------------

### TiProxy Multi-Cluster Backend Configuration

Source: https://context7.com/pingcap/tiproxy/llms.txt

Configure TiProxy to route connections to multiple TiDB backend clusters. Define each cluster with a name and its PD addresses. Optionally, specify DNS servers for service discovery.

```toml
[proxy]
addr = "0.0.0.0:6000"

# Multiple backend clusters
[[proxy.backend-clusters]]
name = "primary"
pd-addrs = "pd1:2379,pd2:2379,pd3:2379"

[[proxy.backend-clusters]]
name = "secondary"
pd-addrs = "pd4:2379,pd5:2379"
# Optional: DNS servers for service discovery
ns-servers = ["dns1:53", "dns2:53"]
```

--------------------------------

### Retrieve Backend Metrics

Source: https://context7.com/pingcap/tiproxy/llms.txt

Fetch JSON-formatted metrics regarding TiDB backend instances.

```bash
# Get backend metrics
curl -X GET http://127.0.0.1:3080/api/backend/metrics
```

--------------------------------

### TiProxy Control Commands for Traffic Management

Source: https://github.com/pingcap/tiproxy/blob/main/docs/design/2024-08-27-traffic-replay.md

Command-line interface commands for managing traffic capture and replay. These commands offer an alternative to the HTTP API for controlling TiProxy's traffic analysis features.

```shell
tiproxyctl --curls 127.0.0.1:3080 traffic capture --output="/tmp/traffic" --duration=1h encryption=true
tiproxyctl --curls 127.0.0.1:3080 traffic replay --speed=1.0 --username="u1" --password="123456" --input="/tmp/traffic" --encryption=true
tiproxyctl --curls 127.0.0.1:3080 traffic cancel
tiproxyctl --curls 127.0.0.1:3080 traffic show
```

--------------------------------

### Namespace Management API

Source: https://context7.com/pingcap/tiproxy/llms.txt

HTTP API endpoints for managing multi-tenant namespaces and routing configurations.

```bash
# List all namespaces
curl -X GET http://127.0.0.1:3080/api/admin/namespace/

# Get specific namespace configuration
curl -X GET http://127.0.0.1:3080/api/admin/namespace/production

# Create or update namespace
curl -X PUT http://127.0.0.1:3080/api/admin/namespace/production \
  -H "Content-Type: application/json" \
  -d '{
    "namespace": "production",
    "frontend": {
      "user": "app_user"
    },
    "backend": {
      "instances": ["tidb1:4000", "tidb2:4000", "tidb3:4000"]
    }
  }'

# Delete namespace
curl -X DELETE http://127.0.0.1:3080/api/admin/namespace/staging

# Commit namespace changes (reload routing)
curl -X POST "http://127.0.0.1:3080/api/admin/namespace/commit?namespace=production"
```

--------------------------------

### Configure TiProxy High Availability

Source: https://github.com/pingcap/tiproxy/blob/main/docs/design/2024-07-02-vip-management.md

Defines the virtual IP and network interface for TiProxy instances. Both parameters are required for the instance to preempt the VIP.

```yaml
[ha]
  vip="192.168.148.100"
  interface="eth0"
```

--------------------------------

### TiProxy SQL Statements for Traffic Management

Source: https://github.com/pingcap/tiproxy/blob/main/docs/design/2024-08-27-traffic-replay.md

SQL commands for controlling traffic capture and replay operations. These administrative commands provide a SQL-based interface for managing traffic analysis within TiProxy.

```sql
ADMIN TRAFFIC CAPTURE OUTPUT="/tmp/traffic" DURATION="1h" ENCRYPTION=true
ADMIN TRAFFIC REPLAY USERNAME="u1" PASSWORD="123456" INPUT="/tmp/traffic" SPEED=1.0 ENCRYPTION=true
ADMIN TRAFFIC CANCEL
ADMIN TRAFFIC SHOW
```

--------------------------------

### Generate Self-Signed Certificate

Source: https://github.com/pingcap/tiproxy/blob/main/README.md

Generate a self-signed certificate and key using openssl for token-based authentication between TiDB and TiProxy. Ensure all TiDB instances use the same certificate.

```shell
openssl req -x509 -newkey rsa:4096 -sha256 -days 3650 -nodes \
  -keyout key.pem -out cert.pem -subj "/CN=example.com"
```

--------------------------------

### Implement metricsreader.MetricsQuerier interface

Source: https://github.com/pingcap/tiproxy/blob/main/docs/design/2026-03-17-multi-cluster-cluster-scoped-runtime.md

Shows the `MetricsQuerier` struct implementing the `metricsreader.MetricsQuerier` interface. This struct acts as a fan-out and merge view over cluster-scoped metrics readers.

```go
type MetricsQuerier struct {
    manager *Manager
    mu      sync.RWMutex
    exprs   map[string]metricsreader.QueryExpr
    rules   map[string]metricsreader.QueryRule
}
```

```go
var _ metricsreader.MetricsQuerier = (*MetricsQuerier)(nil)
```

--------------------------------

### Capture SQL Traffic

Source: https://context7.com/pingcap/tiproxy/llms.txt

Record SQL traffic for replay or analysis using API or tiproxyctl.

```bash
# Start traffic capture
curl -X POST http://127.0.0.1:3080/api/traffic/capture \
  -d "output=/data/traffic-capture" \
  -d "duration=1h" \
  -d "compress=true" \
  -d "encrypt-method=aes256-ctr"

# Using tiproxyctl
tiproxyctl --host=127.0.0.1 --port=3080 traffic capture \
  --output=/data/traffic-capture \
  --duration=1h \
  --compress \
  --encryption-method=aes256-ctr

# Show current traffic jobs
curl -X GET http://127.0.0.1:3080/api/traffic/show
tiproxyctl --host=127.0.0.1 --port=3080 traffic show

# Cancel traffic capture
curl -X POST http://127.0.0.1:3080/api/traffic/cancel
tiproxyctl --host=127.0.0.1 --port=3080 traffic cancel
```

--------------------------------

### Add Secondary IP and Announce via ARP

Source: https://github.com/pingcap/tiproxy/blob/main/docs/design/2024-07-02-vip-management.md

These commands are used to bind a VIP to a TiProxy node and notify the network. The first command attaches a secondary IP to a specified network interface, and the second command broadcasts an ARP request to update the ARP cache on the subnet. Ensure the TiProxy user has root privileges or sudo access for these commands.

```shell
ip addr add 192.168.148.100/24 dev eth0
```

```shell
arping -q -c 1 -U -I eth0 192.168.148.100
```

--------------------------------

### TiProxy High Availability (Virtual IP)

Source: https://context7.com/pingcap/tiproxy/llms.txt

Configure TiProxy for high availability using a virtual IP address. Specify the virtual IP and the network interface it should use for failover.

```toml
[ha]
# Virtual IP address for HA failover
virtual-ip = "192.168.1.100"
# Network interface for VIP
interface = "eth0"
```

--------------------------------

### Define BackendDialer Interface

Source: https://github.com/pingcap/tiproxy/blob/main/docs/design/2026-03-17-multi-cluster-cluster-scoped-runtime.md

Interface used by the SQL proxy to establish connections to backend instances using cluster-aware routing.

```go
type BackendDialer interface {
    DialContext(ctx context.Context, network, addr, clusterName string) (net.Conn, error)
}
```

--------------------------------

### Prometheus Metrics Endpoint

Source: https://context7.com/pingcap/tiproxy/llms.txt

Endpoint exposing Prometheus-compatible metrics for TiProxy.

```APIDOC
## Prometheus Metrics Endpoint

### Description
TiProxy exposes Prometheus-compatible metrics for monitoring proxy performance and health.

### Method
GET

### Endpoint
`/metrics/`

### Parameters
None

### Request Example
```bash
curl -X GET http://127.0.0.1:3080/metrics/
```

### Response
#### Success Response (200)
- **(Text format)** - Prometheus exposition format metrics.

#### Response Example
```
tiproxy_server_connections{namespace="default"} 150
tiproxy_backend_connections{backend="tidb1:4000"} 50
tiproxy_query_duration_seconds_bucket{le="0.1"} 1000
```
```

--------------------------------

### Define backendcluster.Manager struct

Source: https://github.com/pingcap/tiproxy/blob/main/docs/design/2026-03-17-multi-cluster-cluster-scoped-runtime.md

Defines the `Manager` struct which is the sole owner of the backend-cluster lifecycle. It holds references to logger, TLS configuration, configuration getter, wait group, context cancellation, metrics querier, network router, and a map of active clusters.

```go
type Manager struct {
    lg         *zap.Logger
    clusterTLS func() *tls.Config
    cfgGetter  config.ConfigGetter

    wg      waitgroup.WaitGroup
    cancel  context.CancelFunc
    metrics *MetricsQuerier
    network *NetworkRouter

    mu struct {
        sync.RWMutex
        clusters map[string]*Cluster
    }
}
```

--------------------------------

### Define BackendNetwork Interface

Source: https://github.com/pingcap/tiproxy/blob/main/docs/design/2026-03-17-multi-cluster-cluster-scoped-runtime.md

Interface used by the observer stack to perform health checks and network operations for specific backend clusters.

```go
type BackendNetwork interface {
    HTTPClient(clusterName string) *http.Client
    DialContext(ctx context.Context, network, addr, clusterName string) (net.Conn, error)
}
```

--------------------------------

### Backend Metrics API

Source: https://context7.com/pingcap/tiproxy/llms.txt

API to retrieve performance metrics for backend TiDB instances.

```APIDOC
## Backend Metrics API

### Description
The backend metrics endpoint provides JSON-formatted metrics about TiDB backend instances for monitoring.

### Method
GET

### Endpoint
`/api/backend/metrics`

### Parameters
None

### Request Example
```bash
curl -X GET http://127.0.0.1:3080/api/backend/metrics
```

### Response
#### Success Response (200)
- **(JSON object)** - Contains metrics such as backend health, connection counts, and resource usage.

#### Response Example
```json
{
  "tidb1:4000": {
    "status": "healthy",
    "connections": 50,
    "cpu_usage": 0.25
  },
  "tidb2:4000": {
    "status": "healthy",
    "connections": 45,
    "cpu_usage": 0.30
  }
}
```
```

--------------------------------

### Replay SQL Traffic

Source: https://context7.com/pingcap/tiproxy/llms.txt

Execute captured SQL traffic against a TiDB cluster for validation.

```bash
# Start traffic replay
curl -X POST http://127.0.0.1:3080/api/traffic/replay \
  -d "input=/data/traffic-capture" \
  -d "username=replay_user" \
  -d "password=secret" \
  -d "speed=2.0" \
  -d "readonly=false"

# Using tiproxyctl
tiproxyctl --host=127.0.0.1 --port=3080 traffic replay \
  --input=/data/traffic-capture \
  --username=replay_user \
  --password=secret \
  --speed=2.0 \
  --read-only

# Replay with time filtering
tiproxyctl --host=127.0.0.1 --port=3080 traffic replay \
  --input=/data/traffic-capture \
  --username=replay_user \
  --command-start-time="2024-01-15T10:00:00Z" \
  --bufsize=100000 \
  --ps-close=directed

# Show replay status
tiproxyctl --host=127.0.0.1 --port=3080 traffic show

# Cancel replay
tiproxyctl --host=127.0.0.1 --port=3080 traffic cancel
```