pgEdge

https://docs.pgedge.com/
Admin
pgEdge provides advanced multi-master PostgreSQL distributions for the network edge, enabling...
Tokens:3,353,660
Snippets:39,242
Trust Score:9.6
Update:5 months ago
Show doc for...
Tokens:
Raw
### One-Step Quickstart Installation

Source: https://docs.pgedge.com/pgedge-rag-server/v1-0-0/quickstart_demo

This command downloads the necessary files, prompts for API keys, and starts all demo services automatically.

```APIDOC
## One-Step Quickstart

The single command option is the fastest way to get started. Execute the following command:

```bash
/bin/sh -c "$(curl -fsSL https://downloads.pgedge.com/quickstart/rag/pgedge-rag-demo.sh)"
```

This command:
  * Downloads _docker-compose.yml_ and _.env.example_ from the same location.
  * Prompts you for your API key(s) securely.
  * Starts all services automatically.
  * Displays connection details when ready.

Note
The installer creates a temporary workspace in _/var_ and runs the demo from that location.
```

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

### Setup Products Table

Source: https://docs.pgedge.com/pg-vectorize/v0-26-2/extension

Copies example data into a new products table. Ensure the vectorize extension is installed.

```sql
CREATE TABLE products (LIKE vectorize.example_products INCLUDING ALL);
INSERT INTO products SELECT * FROM vectorize.example_products;

```

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

### Launch guided terminal experience

Source: https://docs.pgedge.com/control-plane/v0-8/walkthrough

Execute this command to start an interactive guide that walks you through the setup process with prompts.

```bash
bash examples/walkthrough/guide.sh

```

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

### Example pgEdge Setup Command

Source: https://docs.pgedge.com/platform/pgedge_commands/doc/setup

An example of how to use the pgEdge setup command with required flags for user, password, database name, and PostgreSQL version.

```bash
Example: ./pgedge setup -U user -P passwd -d test --pg_ver 16

```

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

### Configure and Start Server

Source: https://docs.pgedge.com/ai-dba-workbench/v1-0-0-beta1/getting-started/quick-start

Copies the example server configuration and sets minimum settings for a development environment. A user account must be created before starting the server.

```yaml
http:
  address: ":8080"
  auth:
    enabled: true

connection_security:
  allow_internal_networks: true

database:
  host: localhost
  port: 5432
  database: ai_workbench
  user: ai_workbench
  sslmode: disable

secret_file: /path/to/ai-dba-server.secret

```

```bash
/opt/ai-workbench/ai-dba-server \
    -add-user -username admin

```

```bash
/opt/ai-workbench/ai-dba-server \
    -config /etc/pgedge/ai-dba-server.yaml

```

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

### Verify CLI Setup

Source: https://docs.pgedge.com/pgedge-postgres-mcp-server/v1-0-0/guide/quickstart

Example interaction to verify the CLI setup by asking a question about database tables.

```text
You: What tables are in my database?
```

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

### PostgreSQL Source Build and Installation

Source: https://docs.pgedge.com/postgresql/v18/server-administration/installation-from-source-code/building-and-installation-with-autoconf-and-make

This sequence of commands outlines the short version of building and installing PostgreSQL from source. It includes configuration, compilation, installation, user creation, data directory setup, initialization, starting the server, and creating a test database.

```bash
./configure
make
su
make install
adduser postgres
mkdir -p /usr/local/pgsql/data
chown postgres /usr/local/pgsql/data
su - postgres
/usr/local/pgsql/bin/initdb -D /usr/local/pgsql/data
/usr/local/pgsql/bin/pg_ctl -D /usr/local/pgsql/data -l logfile start
/usr/local/pgsql/bin/createdb test
/usr/local/pgsql/bin/psql test
```

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

### PostgreSQL BEGIN Transaction Example

Source: https://docs.pgedge.com/postgresql/v18/reference/sql-commands/begin

A simple example demonstrating how to start a transaction block using the BEGIN command.

```sql
BEGIN;
```

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

### Install Project Dependencies

Source: https://docs.pgedge.com/ai-dba-workbench/v1-0-0-beta1/getting-started/configuration/client

Before starting development, navigate to the client directory and run this command to install all necessary Node.js dependencies. Ensure you have Node.js 18+ and npm 9+ installed.

```bash
cd client
npm install

```

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

### Configure FreeBSD PostgreSQL Autostart

Source: https://docs.pgedge.com/postgresql/v18/server-administration/server-setup-and-operation/starting-the-database-server

Example script snippet for starting PostgreSQL on FreeBSD systems by adding lines to `/etc/rc.local`.

```bash
if [ -x /usr/local/pgsql/bin/pg_ctl -a -x /usr/local/pgsql/bin/postgres ]; then
    su -l postgres -c '/usr/local/pgsql/bin/pg_ctl start -s -l /var/postgresql/log -D /usr/local/pgsql/data'
    echo -n ' postgresql'
fi

```

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

### Start CLI in HTTP Mode with Authentication

Source: https://docs.pgedge.com/pgedge-postgres-mcp-server/v1-0-0/guide/cli-client

This example shows the easiest way to start the CLI in HTTP mode using a startup script, which automatically handles server startup and authentication.

```bash
./start_cli_http.sh

```

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

### Configure and Start Collector

Source: https://docs.pgedge.com/ai-dba-workbench/v1-0-0-beta1/getting-started/quick-start

Copies the example collector configuration and sets minimum settings for a local development environment. The collector must be started with the correct configuration file path.

```yaml
datastore:
  host: localhost
  database: ai_workbench
  username: ai_workbench
  password_file: /path/to/db-password.txt
  port: 5432
  sslmode: disable

secret_file: /path/to/ai-dba-server.secret

```

```bash
/opt/ai-workbench/ai-dba-collector \
    -config /etc/pgedge/ai-dba-collector.yaml

```

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

### Ansible Playbook to Install and Setup etcd

Source: https://docs.pgedge.com/ansible/roles/setup_etcd

This example shows how to invoke the `setup_etcd` role after installing etcd in an Ansible playbook. It assumes a high availability setup.

```yaml
- hosts: pgedge
  collections:
    - pgedge.platform
  roles:
    - install_etcd
    - setup_etcd

```

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

### Complete pgEdge Deployment with PgBackRest Installation

Source: https://docs.pgedge.com/ansible/roles/install_backrest

This example shows how to install PgBackRest as part of a comprehensive pgEdge deployment. It includes roles for server initialization, repository setup, pgEdge installation, Postgres setup, and PgBackRest configuration.

```yaml
- hosts: pgedge
  collections:
    - pgedge.platform
  roles:
    - init_server
    - install_repos
    - install_pgedge
    - install_backrest
    - setup_postgres
    - setup_backrest

```

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

### Create and Navigate to Demo Directory

Source: https://docs.pgedge.com/pgedge-postgres-mcp-server/v1-0-0/guide/quickstart_demo

Creates a new directory for the demo and changes into it. This is the first step in setting up the quickstart environment.

```bash
mkdir ~/pgedge-ait-demo
cd ~/pgedge-ait-demo
```

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

### Create Working Directory and Navigate

Source: https://docs.pgedge.com/pgedge-rag-server/v1-0-0/quickstart_demo

Sets up the necessary directory for the demo and navigates into it.

```bash
mkdir ~/pgedge-rag-demo
cd ~/pgedge-rag-demo
```

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

### Install PgBackRest on Postgres Nodes and Backup Servers

Source: https://docs.pgedge.com/ansible/roles/install_backrest

This example demonstrates installing PgBackRest on both Postgres nodes and dedicated backup servers. It includes the necessary roles for repository setup and installation.

```yaml
# Install on Postgres nodes
- hosts: pgedge
  collections:
    - pgedge.platform
  roles:
    - install_repos
    - install_backrest

# Install on dedicated backup servers
- hosts: backup
  collections:
    - pgedge.platform
  roles:
    - install_repos
    - install_backrest

```

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

### Create and Edit Configuration File

Source: https://docs.pgedge.com/pgedge-postgres-mcp-server/v1-0-0/guide/provider_config

Copy the example configuration file, edit it with your settings, and then run the server. The server automatically loads the configuration.

```bash
# Copy the example to the binary directory
cp configs/postgres-mcp.yaml.example bin/postgres-mcp.yaml

# Edit with your settings
vim bin/postgres-mcp.yaml

# Run the server (automatically loads config from default location)
./bin/pgedge-postgres-mcp

```

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

### Run pgedge-postgres-mcp Quickstart Demo

Source: https://docs.pgedge.com/pgedge-postgres-mcp-server/v1-0-0/guide/quickstart_demo

Execute this command to automatically download, set up, and start the pgedge-postgres-mcp demo environment. It prompts for API keys and displays connection details upon completion.

```bash
/bin/sh -c "$(curl -fsSL https://raw.githubusercontent.com/pgEdge/pgedge-postgres-mcp/main/examples/quickstart-demo/pgedge-ait-demo.sh)"
```

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

### Query Huge Page Requirements

Source: https://docs.pgedge.com/postgresql/v18/server-administration/server-setup-and-operation/managing-kernel-resources

Before starting the PostgreSQL server, you can query the number of huge pages required based on your configuration. This example shows how to get the value and check system huge page information.

```bash
$ postgres -D $PGDATA -C shared_memory_size_in_huge_pages
3170
```

```bash
$ grep ^Hugepagesize /proc/meminfo
Hugepagesize:       2048 kB
```

```bash
$ ls /sys/kernel/mm/hugepages
hugepages-1048576kB  hugepages-2048kB
```

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

### Run pgEdge RAG Server Demo (One-Step Quickstart)

Source: https://docs.pgedge.com/pgedge-rag-server/v1-0-0/quickstart_demo

Execute this command to download, configure, and start the RAG Server demo with default settings. It prompts for API keys and automatically launches all services.

```bash
/bin/sh -c "$(curl -fsSL https://downloads.pgedge.com/quickstart/rag/pgedge-rag-demo.sh)"
```

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

### GET /oauth/authorize Request Example

Source: https://docs.pgedge.com/pgedge-mcp-bridge/v1-0-0-alpha5/reference/api

Example of a GET request to the authorization endpoint, including parameters for initiating the OAuth 2.0 authorization code flow with PKCE.

```http
GET /oauth/authorize?response_type=code&client_id=my-client&redirect_uri=https://claude.ai/api/mcp/auth_callback&state=abc123&code_challenge=E9Melhoa...&code_challenge_method=S256
```

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

### CLI Example: Setup Semantic Search

Source: https://docs.pgedge.com/pgedge-postgres-mcp-server/v1-0-0/reference/prompts

Demonstrates how to set up semantic search using the `setup-semantic-search` prompt from the CLI to find information about a specific topic.

```bash
/prompt setup-semantic-search query_text="What is pgAgent?"

```

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

### Install and verify golangci-lint v1.x

Source: https://docs.pgedge.com/pgedge-postgres-mcp-server/v1-0-0/contributing/ci-cd

Install the latest v1.x version of golangci-lint. Verify the installation by checking the version, which should start with 'v1.x.x'.

```bash
# Install latest v1.x version
go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest

# Verify installation
golangci-lint version
# Should show: golangci-lint has version v1.x.x
```

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

### Start Ollama Service

Source: https://docs.pgedge.com/pgedge-postgres-mcp-server/v1-0-0/developers/http-ollama-chatbot

Start the Ollama background service. This usually runs automatically after installation.

```bash
ollama serve

```

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

### Show Example Configuration

Source: https://docs.pgedge.com/postgrest/v14-10/references/cli

Displays an example configuration file for PostgREST. This is helpful for setting up your own configuration.

```bash
$ postgrest --example

```

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

### createdb Example with Options

Source: https://docs.pgedge.com/postgresql/v18/reference/postgresql-client-applications/createdb

Demonstrates creating a database with a specific encoding, locale, and owner.

```bash
createdb -E UTF8 -l en_US.UTF-8 -O user1 mydatabase "My database description"
```

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

### Install Python Requests Library

Source: https://docs.pgedge.com/pgedge-postgres-mcp-server/v1-0-0/developers/client-examples

Installs the 'requests' library, which is a prerequisite for the Python client examples.

```bash
pip install requests

```

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

### Start Ollama Server

Source: https://docs.pgedge.com/pg-vectorize/v0-26-2/extension/models

Starts the Ollama server in detached mode. Ensure Docker is installed and running.

```bash
docker compose up ollama-serve -d

```

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

### Start psql and Load Tutorial Script

Source: https://docs.pgedge.com/postgresql/v18/tutorial/the-sql-language/introduction

Connect to your database using 'psql' in single-step mode and load commands from a SQL file using the '\i' meta-command.

```bash
$ psql -s mydb

... 

mydb=> \i basics.sql

```

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

### Install Documentation

Source: https://docs.pgedge.com/postgresql/v18/server-administration/installation-from-source-code/building-and-installation-with-autoconf-and-make

Install the HTML and man page documentation.

```bash
make install-docs
```

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

### GET /api/conversations Response Example

Source: https://docs.pgedge.com/pgedge-postgres-mcp-server/v1-0-0/developers/api-reference

Example JSON response from the /api/conversations endpoint, listing conversations with their metadata.

```json
{
    "conversations": [
        {
            "id": "conv_abc123",
            "title": "Database schema exploration",
            "connection": "production",
            "created_at": "2025-01-15T10:30:00Z",
            "updated_at": "2025-01-15T11:45:00Z",
            "preview": "Show me the users table..."
        }
    ]
}


```

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

### createdb Example with Template

Source: https://docs.pgedge.com/postgresql/v18/reference/postgresql-client-applications/createdb

Shows how to create a database using a specific template database.

```bash
createdb -T template0 mydatabase
```

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

### Basic Build

Source: https://docs.pgedge.com/postgresql/v18/server-administration/installation-from-source-code/building-and-installation-with-autoconf-and-make

Start the build process for the server and utilities. Ensure you are using GNU make.

```bash
make
make all
```

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

### Get Row Count with GET DIAGNOSTICS

Source: https://docs.pgedge.com/postgresql/v18/server-programming/pl-pgsql-sql-procedural-language/basic-statements

An example of using GET DIAGNOSTICS to retrieve the number of rows processed by the most recent SQL command into an integer variable.

```sql
GET DIAGNOSTICS integer_var = ROW_COUNT;

```

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

### Build and Start CLI (Stdio)

Source: https://docs.pgedge.com/pgedge-postgres-mcp-server/v1-0-0/guide/quickstart

Builds the server and CLI client, sets the LLM API key, and starts the CLI in stdio mode using binaries from the bin/ directory.

```bash
make build
export PGEDGE_ANTHROPIC_API_KEY=sk-ant-...

./bin/pgedge-nla-cli \
    -mcp-mode stdio \
    -mcp-server-path ./bin/pgedge-postgres-mcp \
    -mcp-server-config ./bin/postgres-mcp.yaml
```

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

### Get User Info Response

Source: https://docs.pgedge.com/pgedge-postgres-mcp-server/v1-0-0/developers/api-reference

Example JSON response from the GET /api/user/info endpoint, containing the username of the authenticated user.

```json
{
  "username": "alice"
}
```

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

### Setup PostgreSQL Extensions

Source: https://docs.pgedge.com/pg-semantic-cache

Install the 'vector' and 'pg_semantic_cache' extensions in your PostgreSQL database. Verify the installation by checking the cache health.

```sql
CREATE EXTENSION IF NOT EXISTS vector;
CREATE EXTENSION IF NOT EXISTS pg_semantic_cache;

-- Verify installation
SELECT * FROM semantic_cache.cache_health;

```

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

### Example Cluster Configuration Creation with Prompts

Source: https://docs.pgedge.com/platform/installing_pgedge/json

This example demonstrates the interactive prompts that appear when creating a cluster configuration file without the `--force` flag. It includes prompts for PostgreSQL and Spock versions, pgBackRest enablement, and detailed node configuration including IP addresses and ports.

```bash
./pgedge cluster json-create demo 2 lcdb admin password --port=6432

PostgreSQL version ['15', '16', '17'] (default: '16'): 
Spock version ['3.3.6', '3.3.5', '4.0.10', '4.0.9', '4.0.8'] (default: '4.0.10'): 
Enable pgBackRest? (Y/N) (default: 'N'): Y
   pgBackRest storage path (default: '/var/lib/pgbackrest'): 
   pgBackRest archive mode (on/off) (default: 'on'): 
   pgBackRest repository type (posix/s3) (default: 'posix'): 

Configuring Node 1
  Public IP address for Node 1 (default: '127.0.0.1'): 
  Private IP address for Node 1 (default: '127.0.0.1'): 
  Using port 6432 for Node 1 

Configuring Node 2
  Public IP address for Node 2 (default: '127.0.0.1'): 
  Private IP address for Node 2 (default: '127.0.0.1'): 
  Using port 6433 for Node 2 

Configuring Node 3
  Public IP address for Node 3 (default: '127.0.0.1'): 
  Private IP address for Node 3 (default: '127.0.0.1'): 
  Using port 6434 for Node 3 

################################################################################
# Cluster Name       : demo
# PostgreSQL Version : 16
# Spock Version      : 4.0.10
# Number of Nodes    : 3
# Database Name      : lcdb
# User               : lcusr
# pgBackRest Enabled : Yes
#    Storage Path    : /var/lib/pgbackrest
#    Archive Mode    : on
#    Repository Type : posix
# Node 1
#    Public IP       : 127.0.0.1
#    Private IP      : 127.0.0.1
#    Port            : 6432
# Node 2

```

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

### Navigate to Example Directory

Source: https://docs.pgedge.com/pgedge-postgres-mcp-server/v1-0-0/developers/http-ollama-chatbot

Change the current directory to the http-ollama-chatbot example folder.

```bash
cd examples/http-ollama-chatbot

```

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

### Install Go Linter

Source: https://docs.pgedge.com/ai-dba-workbench/v1-0-0-beta1/developer-guide

Installs the golangci-lint tool, a Go linter, to ensure code quality. Run this command before starting development.

```bash
go install \
  github.com/golangci/golangci-lint/cmd/golangci-lint@latest

```

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

### createdb Example with Connection Options

Source: https://docs.pgedge.com/postgresql/v18/reference/postgresql-client-applications/createdb

Demonstrates connecting to a remote host and specifying a username for database creation.

```bash
createdb -h host.example.com -p 5432 -U dbuser mydatabase
```

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

### Build and Start MCP Server

Source: https://docs.pgedge.com/pgedge-postgres-mcp-server/v1-0-0/developers/http-ollama-chatbot

Build the pgEdge MCP server binary and start it in HTTP mode. Authentication is disabled for this example.

```bash
cd ../..
go build -o bin/pgedge-postgres-mcp ./cmd/pgedge-pg-mcp-svr
./bin/pgedge-postgres-mcp -http -addr :8080 -no-auth

```

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

### Start MCP Bridge in Server Mode

Source: https://docs.pgedge.com/pgedge-mcp-bridge/v1-0-0-alpha5/reference/cli

Example of starting the MCP Bridge in server mode using a specified configuration file.

```bash
mcp-bridge -c server-config.yaml
```

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

### Create and Populate Example Table

Source: https://docs.pgedge.com/pg-vectorize/v0-26-2/extension/examples/openai_embeddings

Create a 'products' table by copying the schema and data from the 'vectorize.example_products' table. This sets up sample data for vectorization.

```sql
CREATE TABLE products (LIKE vectorize.example_products INCLUDING ALL);
INSERT INTO products SELECT * FROM vectorize.example_products;
```

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

### Install an Extension using Update Manager

Source: https://docs.pgedge.com/platform/managing/supported_extensions

Use the `um install` command followed by the component name to install an extension. This example demonstrates installing the PostGIS extension, which includes updating `shared_preload_libraries`, restarting the server, and creating the extension.

```bash
./pgedge um install component_name
```

```bash
./pgedge um install postgis
```

```bash
pg17/bin/psql -p 6432 -c "CREATE EXTENSION IF NOT EXISTS postgis CASCADE" postgres
```

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

### Navigate to Example Directory

Source: https://docs.pgedge.com/pgedge-postgres-mcp-server/v1-0-0/developers/stdio-anthropic-chatbot

Change directory to the stdio-anthropic-chatbot example.

```bash
cd examples/stdio-anthropic-chatbot
```

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

### Install Web Client

Source: https://docs.pgedge.com/ai-dba-workbench/v1-0-0-beta1/getting-started/installation

Creates a directory for the web client and extracts the pre-built web client archive into it.

```bash
sudo mkdir -p /opt/ai-workbench/client
sudo tar xzf ai-dba-client.tar.gz \
    -C /opt/ai-workbench/client

```

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

### Get Postgres Version

Source: https://docs.pgedge.com/enterprise/debian/installing

Retrieves the installed PostgreSQL version.

```bash
pg_config --version
```

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

### Install etcd with Default Settings

Source: https://docs.pgedge.com/ansible/roles/install_etcd

Example playbook to install etcd using its default configuration parameters. This role is idempotent and safe to re-run.

```yaml
- hosts: pgedge
  collections:
    - pgedge.platform
  roles:
    - install_etcd

```

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

### Connect to Postgres for SQL Examples

Source: https://docs.pgedge.com/pgmq

Establishes a connection to a PostgreSQL instance on 0.0.0.0:5432 for executing SQL examples.

```bash
# Connect to Postgres
psql postgres://postgres:postgres@0.0.0.0:5432/postgres

```

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

### Original Error Message Example

Source: https://docs.pgedge.com/postgresql/v18/internals/postgresql-coding-conventions/error-message-style-guide

An example of an error message before applying the style guide, showing a long primary message with implementation details.

```text
IpcMemoryCreate: shmget(key=%d, size=%u, 0%o) failed: %m
(plus a long addendum that is basically a hint)
```

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

### pgedge-ait-demo.sh Script Output

Source: https://docs.pgedge.com/pgedge-postgres-mcp-server/v1-0-0/guide/quickstart_demo

Sample output from the quickstart demo script, showing the download process, API key prompts, service startup, and final connection details for the Web Client, PostgreSQL, and MCP Server.

```text
$ /bin/sh -c "$(curl -fsSL https://raw.githubusercontent.com/pgEdge/pgedge-postgres-mcp/main/examples/quickstart-demo/pgedge-ait-demo.sh)"
ℹ  Creating workspace: /tmp/pgedge-download.28085
ℹ  Downloading files
ℹ  → docker-compose.yml
ℹ  → .env.example
✓  Downloads complete

pgEdge AI Toolkit Demo setup
You need to specify an API key for Anthropic or OpenAI (or both)

Anthropic API key
(Leave blank to skip)
›
OpenAI API key
(Leave blank to skip)
›
✓  Wrote .env
ℹ  Starting services
[+] Running 22/22
 ✔ web-client Pulled                                                                                                                                                                                          15.4s
 ✔ postgres Pulled                                                                                                                                                                                            17.5s
 ✔ postgres-mcp Pulled                                                                                                                                                                                         8.7s
[+] Running 6/6
 ✔ Network pgedge-download28085_pgedge-quickstart  Created                                                                                                                                                     0.0s
 ✔ Volume pgedge-download28085_postgres-data       Created                                                                                                                                                     0.0s
 ✔ Volume pgedge-download28085_mcp-data            Created                                                                                                                                                     0.0s
 ✔ Container pgedge-quickstart-db                  Healthy                                                                                                                                                     6.4s
 ✔ Container pgedge-quickstart-mcp                 Healthy                                                                                                                                                    11.2s
 ✔ Container pgedge-quickstart-web                 Started                                                                                                                                                    11.3s
ℹ  Waiting for services to be healthy (this may take up to 60 seconds)...
✓  Services are ready

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  pgEdge AI Toolkit Demo is running!
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Web Client Interface:
  http://localhost:8081
  Login: demo / demo123

PostgreSQL Database:
  Database: northwind
  User: demo / demo123
  Connect: docker exec -it pgedge-quickstart-db psql -U demo -d northwind

MCP Server API:
  http://localhost:8080
  Bearer Token: demo-token-12345

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Workspace: /tmp/pgedge-download.28085
To stop: cd /tmp/pgedge-download.28085 && docker compose down -v

For more information: https://github.com/pgEdge/pgedge-postgres-mcp

```

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

### Copy Example Configuration File

Source: https://docs.pgedge.com/pgedge-postgres-mcp-server/v1-0-0/guide/deploy_source

Copy the example environment file to create a new configuration file for your deployment. This preserves the original example.

```bash
cp .env.example bin/postgres-mcp.yaml
```

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

### Generate Operator Installation Manifest

Source: https://docs.pgedge.com/cloudnativepg/v1-29/kubectl-plugin

Generates a YAML manifest to install the CloudNativePG operator. This example specifies the installation namespace, operator version, number of replicas, and namespaces to watch. The output is redirected to `operator.yaml`.

```bash
kubectl cnpg install generate \
  -n king \
  --version 1.23 \
  --replicas 3 \
  --watch-namespace "albert, bb, freddie" \
  > operator.yaml
```

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

### createdb Example with Tablespace

Source: https://docs.pgedge.com/postgresql/v18/reference/postgresql-client-applications/createdb

Illustrates creating a database with a specified default tablespace.

```bash
createdb -D my_tablespace mydatabase
```

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

### Start MCP Bridge in Client Mode

Source: https://docs.pgedge.com/pgedge-mcp-bridge/v1-0-0-alpha5/reference/cli

Example of starting the MCP Bridge in client mode, with the authentication token set via an environment variable.

```bash
export MCP_AUTH_TOKEN="my-token"
mcp-bridge -c client-config.yaml
```

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

### Install etcd with Patroni

Source: https://docs.pgedge.com/ansible/roles/install_etcd

Example playbook to install etcd and Patroni for a high availability cluster. Execute this role on pgedge hosts before configuring Patroni.

```yaml
- hosts: pgedge
  collections:
    - pgedge.platform
  roles:
    - install_etcd
    - install_patroni

```

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

### Copy Example Configuration

Source: https://docs.pgedge.com/ai-dba-workbench/v1-0-0-beta1/developer-guide/collector/testing

Copies the example configuration file to a new file for development use.

```bash
cp ../examples/ai-dba-collector.yaml \
    ai-dba-collector-dev.yaml
```

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

### Get User Info Request

Source: https://docs.pgedge.com/pgedge-postgres-mcp-server/v1-0-0/developers/api-reference

Example HTTP request to the GET /api/user/info endpoint to retrieve information about the authenticated user. Requires an Authorization header.

```http
GET /api/user/info HTTP/1.1
Authorization: Bearer <session-token>
```

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

### View and Configure Custom Definitions Example

Source: https://docs.pgedge.com/pgedge-postgres-mcp-server/v1-0-0/advanced/custom-definitions

View the example custom definitions file and specify its path in your server configuration.

```bash
# View the example file
cat examples/pgedge-postgres-mcp-custom.yaml
```

```yaml
custom_definitions_path: "./examples/pgedge-postgres-mcp-custom.yaml"
```

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

### Get Installed PostGIS Scripts Version

Source: https://docs.pgedge.com/postgis/v3-6-3/postgis-reference/version-functions

Retrieves the version of the PostGIS scripts currently installed in the database. Important for verifying database schema upgrades.

```sql
SELECT PostGIS_Scripts_Installed();
```

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

### Install World Components

Source: https://docs.pgedge.com/postgresql/v18/server-administration/installation-from-source-code/building-and-installation-with-autoconf-and-make

Install all components, including documentation, if `make world` was used.

```bash
make install-world
```

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

### Get Help for Install Generate Command

Source: https://docs.pgedge.com/cloudnativepg/v1-29/kubectl-plugin

Use this command to display help information and available options for generating installation manifests with the `cnpg` plugin.

```bash
kubectl cnpg install generate --help
```

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

### Compile Tutorial Files

Source: https://docs.pgedge.com/postgresql/v18/tutorial/the-sql-language/introduction

Navigate to the tutorial directory in the PostgreSQL source distribution and run 'make' to compile C files and create tutorial scripts.

```bash
$ cd .../src/tutorial
$ make

```

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

### Example Connection Strings: With Authentication

Source: https://docs.pgedge.com/pgedge-postgres-mcp-server/v1-0-0/guide/querying

Connection strings demonstrating how to include username and password for authentication.

```plaintext
postgres://username:password@localhost:5432/production
```

```plaintext
postgres://dbuser:secretpass@db-server/analytics
```

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

### Setup pg_semantic_cache Extension

Source: https://docs.pgedge.com/pg-semantic-cache/v0-1-0-beta4

Install the necessary PostgreSQL extensions, vector and pg_semantic_cache, using CREATE EXTENSION. Verify the installation by querying the cache_health view.

```sql
CREATE EXTENSION IF NOT EXISTS vector;
CREATE EXTENSION IF NOT EXISTS pg_semantic_cache;

SELECT * FROM semantic_cache.cache_health;
```

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

### Install etcd with Custom Paths

Source: https://docs.pgedge.com/ansible/roles/install_etcd

Example playbook to install etcd with custom data and configuration directory paths. The role prepares the service for later configuration.

```yaml
- hosts: pgedge
  collections:
    - pgedge.platform
  vars:
    etcd_data_dir: /data/etcd
    etcd_config_dir: /opt/etcd/config
  roles:
    - install_etcd

```

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

### Server Configuration Example

Source: https://docs.pgedge.com/pgedge-postgres-mcp-server/v1-0-0/reference/config-examples/server

This is a comprehensive example of the server configuration file. It demonstrates how to enable and configure HTTP/HTTPS, TLS, and authentication settings. It also shows the structure for database configuration.

```yaml
# Natural Language Agent Configuration File
#
# Configuration Priority (highest to lowest):
#   1. Command line flags
#   2. Environment variables
#   3. Configuration file values (this file)
#   4. Hard-coded defaults
#
# Copy this file to postgres-mcp.yaml and customize as needed.
# By default, the server looks for config in the same directory as the binary.

# ============================================================================ 
# HTTP/HTTPS SERVER CONFIGURATION (Optional - only needed for API access)
# ============================================================================ 
# By default, the server runs in stdio mode for Claude Desktop.
# Enable HTTP mode for direct API access or web integrations.
http:
    # Enable HTTP transport mode
    # If false, server runs in stdio mode (for Claude Desktop)
    # Default: false
    # Environment variable: PGEDGE_HTTP_ENABLED
    # Command line flag: -http
    enabled: false

    # HTTP server address
    # Format: host:port or :port
    # Default: :8080
    # Environment variable: PGEDGE_HTTP_ADDRESS
    # Command line flag: -addr
    address: ":8080"

    # -------------------------
    # TLS/HTTPS Configuration
    # -------------------------
    tls:
        # Enable HTTPS (requires http.enabled: true)
        # Default: false
        # Environment variable: PGEDGE_TLS_ENABLED
        # Command line flag: -tls
        enabled: false

        # Path to TLS certificate file
        # Default: ./server.crt
        # Environment variable: PGEDGE_TLS_CERT_FILE
        # Command line flag: -cert
        cert_file: "./server.crt"

        # Path to TLS private key file
        # Default: ./server.key
        # Environment variable: PGEDGE_TLS_KEY_FILE
        # Command line flag: -key
        key_file: "./server.key"

        # Path to TLS certificate chain file (optional)
        # Default: "" (empty)
        # Environment variable: PGEDGE_TLS_CHAIN_FILE
        # Command line flag: -chain
        chain_file: ""

    # -------------------------
    # Authentication
    # -------------------------
    auth:
        # Enable API token authentication (requires http.enabled: true)
        # Default: true (authentication is enabled by default)
        # Environment variable: PGEDGE_AUTH_ENABLED
        # Command line flag: -no-auth (to disable)
        enabled: true

        # Path to API token configuration file
        # Default: Same directory as binary (postgres-mcp-tokens.yaml)
        # Environment variable: PGEDGE_AUTH_TOKEN_FILE
        # Command line flag: -token-file
        token_file: ""

        # Path to user authentication file
        # Default: Same directory as binary (postgres-mcp-users.yaml)
        # Environment variable: PGEDGE_AUTH_USER_FILE
        # Command line flag: -user-file
        user_file: ""

        # Rate limiting and account lockout (prevents brute force attacks)
        # Lock account after N failed attempts (0 = disabled)
        # Default: 0 (disabled)
        # Environment variable: PGEDGE_AUTH_MAX_FAILED_ATTEMPTS_BEFORE_LOCKOUT
        max_failed_attempts_before_lockout: 5

        # Time window for rate limiting in minutes
        # Default: 15
        # Environment variable: PGEDGE_AUTH_RATE_LIMIT_WINDOW_MINUTES
        rate_limit_window_minutes: 15

        # Maximum failed attempts per IP per time window
        # Default: 10
        # Environment variable: PGEDGE_AUTH_RATE_LIMIT_MAX_ATTEMPTS
        rate_limit_max_attempts: 10

        # Token management commands (no database connection required):
        # - Create token: ./bin/pgedge-postgres-mcp -add-token
        # - List tokens:  ./bin/pgedge-postgres-mcp -list-tokens
        # - Remove token: ./bin/pgedge-postgres-mcp -remove-token <id>

# ============================================================================ 
# ENCRYPTION SECRET FILE (Optional)
# ============================================================================ 
# Path to encryption secret file used for encrypting database passwords
# Default: postgres-mcp.secret in the same directory as the binary
# If the file does not exist, it will be automatically generated on first run
# IMPORTANT: The secret file must have 0600 permissions (owner read/write only)
#            The server will refuse to start if permissions are incorrect
# Environment variable: PGEDGE_SECRET_FILE
# Command line flag: N/A (not available)
secret_file: ""

# ============================================================================ 
# DATABASE CONFIGURATION
# ============================================================================ 
# Database connections are configured at server startup via:
#   1. Config file (database section below)
#   2. Environment variables (PGEDGE_DB_* or PG*)
#   3. Command-line flags (-host, -port, -database, -user, -password)
#

```

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

### Get Host Task Response Example

Source: https://docs.pgedge.com/control-plane/v0-8/api/reference

Example JSON response for retrieving details of a specific host task. Includes timestamps, status, and entity information.

```json
{
  "completed_at": "2025-06-18T16:52:35Z",
  "created_at": "2025-06-18T16:52:05Z",
  "database_id": "storefront",
  "entity_id": "storefront",
  "scope": "database",
  "status": "completed",
  "task_id": "019783f4-75f4-71e7-85a3-c9b96b345d77",
  "type": "create"
}
```
Tokens:
Raw