From 3c53bc394e7cff3f0a5f22cae20a8541a89dcbe8 Mon Sep 17 00:00:00 2001 From: Antony Pegg Date: Fri, 13 Mar 2026 12:55:51 -0400 Subject: [PATCH 01/13] Reorganize navigation menu and redesign welcome page Replace Products dropdown with user-focused categories: VM / Bare Metal, Containers, pgEdge Cloud (direct link), AI Toolkit, Extensions, Tools. Redesign welcome page with card-based layout and add Ansible placeholder. Simplify tabs template dropdown macro by removing unused nav_items parameter. --- docs/ansible/index.md | 23 ++ docs/index.md | 439 ++++++++++++++++++++++++++++++++--- mkdocs.yml | 56 ++--- overrides/partials/tabs.html | 72 +++--- 4 files changed, 488 insertions(+), 102 deletions(-) create mode 100644 docs/ansible/index.md diff --git a/docs/ansible/index.md b/docs/ansible/index.md new file mode 100644 index 00000000..c4004fbb --- /dev/null +++ b/docs/ansible/index.md @@ -0,0 +1,23 @@ +# Ansible + +pgEdge provides an Ansible collection for deploying and managing PostgreSQL clusters on VMs and bare metal servers. + +## Overview + +The pgEdge Ansible collection includes roles for: + +- Deploying pgEdge Enterprise Postgres +- Configuring pgEdge Distributed Postgres clusters +- Managing Spock replication setup + +## Documentation + +For complete documentation, installation instructions, and sample playbooks, see the GitHub repository: + +**[pgEdge Ansible Collection on GitHub](https://github.com/pgEdge/pgedge-ansible)** + +## Related Resources + +- [Distributed CLI documentation](../platform/) - Manual VM deployments +- [Control Plane documentation](../control-plane/) - Declarative API for cluster management +- [pgEdge Cloud documentation](../cloud/) - Managed cloud deployments diff --git a/docs/index.md b/docs/index.md index cb0d73ac..74bc85db 100644 --- a/docs/index.md +++ b/docs/index.md @@ -4,52 +4,419 @@ hide: - navigation --- -# Welcome to pgEdge Documentation + + + +
+

Welcome to pgEdge Documentation

+

+ Enterprise-ready PostgreSQL that scales with your needs—from a single database to globally distributed multi-master deployments. +

+

+ pgEdge delivers hardened, production-grade PostgreSQL with a seamless path from day one through global scale. +

+
+ + +
+

Getting Started - Choose your Deployment

+
+ +
+ + +
+
+
+

VMs & Bare Metal

+ +
+
+

Direct installs on servers.

+ View Documentation → +
+ + +
+
+
+

Containers

+ +
+
+

Helm + CloudNativePG deployments.

+ View Documentation → +
+ + +
+
+
+

pgEdge Cloud

+ +
+
+

Fully managed PostgreSQL service.

+ View Documentation → +
+ +
+ + + +
+

Key Components

+
+ +
+ +
+
+
+

Control Plane

+ +
+
+

Lifecycle management API.

+ View Documentation → +
+ +
+
+
+

Enterprise Repository

+ +
+
+

Hardened PostgreSQL packages.

+ View Documentation → +
+ +
+
+
+

AI Toolkit

+ +
+
+

MCP, RAG, Vectorizer.

+ View Documentation → +
+ +
+ + +
+

Extensions & Components

+

Purpose-built extensions that enable pgEdge's advanced capabilities.

+
+ +
+
+

Replication & Distribution

+
    +
  • + Spock v5 + Logical multi-master replication with bi-directional data flow and conflict resolution +
    • +
  • + LOLOR + Large object replication for handling BLOBs in distributed environments +
    • +
  • + Snowflake + Distributed sequence generation for cluster-wide unique IDs +
    • +
+
+ +
+

AI & Agentic Capabilities

+
    +
  • + MCP Server + Model Context Protocol server for LLM and AI agent access to PostgreSQL +
    • +
  • + Vectorizer + Automatic document chunking and vector embedding generation +
    • +
  • + RAG Server + High-performance Retrieval-Augmented Generation API with hybrid search +
    • +
  • + DocLoader + Command-line utility for loading documents into PostgreSQL for AI applications +
    • +
+
+ +
+

Operations & Utilities

+
    +
  • + ACE (Active Consistency Engine) + Automated data integrity verification and repair across replicated clusters +
    • +
  • + Control Plane + Declarative API for database lifecycle management and orchestration +
    • +
  • + Radar + Agentless diagnostic data collection for PostgreSQL and system metrics +
    • +
  • + Anonymizer + PII replacement for safe dev/test database copies +
    • +
  • + Loadgen + Realistic workload generation and performance testing +
    • +
+
+
+ + +
+ +
+

+ Resources: + GitHub • + Website • + Support • + Discord +

+

+ pgEdge is built by industry veterans with decades of PostgreSQL expertise. Founded in 2022 and headquartered in Northern Virginia, pgEdge serves prominent enterprises including Bertelsmann, Qube RT, European Parliament, and multiple U.S. government agencies. +

+
diff --git a/mkdocs.yml b/mkdocs.yml index 757667fe..d9e8fb7d 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -156,21 +156,25 @@ extra: # Navigation dropdown categories - maps nav item titles to dropdown menus # Use simple string for auto-detected URLs, or {title: url} for explicit URLs nav_categories: - Products: - - pgEdge Cloud - - title: pgEdge Container - url: pgedge-container/ - - pgEdge Distributed Postgres - - pgEdge Enterprise Postgres + VM / Bare Metal: + - title: Control Plane + url: control-plane/ + - title: Distributed CLI + url: platform/ + - title: pgEdge Package Repository + url: enterprise/ - title: PostgreSQL url: postgresql/ - - title: pgAdmin 4 - url: pgadmin-4/ + - title: Ansible + url: ansible/ + Containers: + - title: pgEdge Container + url: pgedge-container/ + - title: Container Registry + url: container-images/ AI Toolkit: - title: pgEdge Postgres MCP Server url: pgedge-postgres-mcp-server/ - - title: pgEdge Anonymizer - url: pgedge-anonymizer/ - title: pgEdge RAG Server url: pgedge-rag-server/ - title: pgEdge Docloader @@ -178,43 +182,19 @@ extra: - title: pgEdge Vectorizer url: pgedge-vectorizer/ Extensions: - - title: lolor + - title: Spock v5 + url: spock-v5/ + - title: LOLOR url: lolor/ - - title: pgEdge Vectorizer - url: pgedge-vectorizer/ - title: Snowflake url: snowflake/ - - title: Spock v5 - url: spock-v5/ - - title: psycopg2 - url: psycopg2/ - - title: pgvector - url: pgvector/ - - title: pgAudit - url: pgaudit/ - - title: pgBackRest - url: pgbackrest/ - - title: PgBouncer - url: pgbouncer/ - - title: PostGIS - url: postgis/ Tools: - title: ACE url: ace/ - - title: Control Plane - url: control-plane/ - - title: pgEdge Helm - url: pgedge-helm/ - title: pgEdge Anonymizer url: pgedge-anonymizer/ - - title: pgEdge Docloader - url: pgedge-docloader/ - title: pgEdge Loadgen url: pgedge-loadgen/ - - title: pgEdge Postgres MCP Server - url: pgedge-postgres-mcp-server/ - - title: pgEdge RAG Server - url: pgedge-rag-server/ - title: Radar url: radar/ @@ -225,6 +205,8 @@ repo_url: https://github.com/pgEdge nav: - Welcome: index.md + - Ansible: ansible/index.md + - pgEdge Enterprise Postgres: - Enterprise Edition: enterprise/index.md - Enterprise Linux 9 & 10: diff --git a/overrides/partials/tabs.html b/overrides/partials/tabs.html index a46f79c8..b636a2d2 100644 --- a/overrides/partials/tabs.html +++ b/overrides/partials/tabs.html @@ -7,7 +7,7 @@ {% set nav_categories = config.extra.nav_categories or {} %} {# Macro to render a dropdown menu #} -{% macro dropdown_menu(label, category_items, nav_items, dropdown_id) %} +{% macro dropdown_menu(label, category_items, dropdown_id) %}
    • @@ -66,10 +49,41 @@ {% endif %} {% endfor %} - {# Dropdown menus from config.extra.nav_categories #} - {% for category_name, category_items in nav_categories.items() %} - {{ dropdown_menu(category_name, category_items, nav, category_name | lower | replace(' ', '-')) }} + {# VM / Bare Metal dropdown #} + {% if 'VM / Bare Metal' in nav_categories %} + {{ dropdown_menu('VM / Bare Metal', nav_categories['VM / Bare Metal'], 'vm-bare-metal') }} + {% endif %} + + {# Containers dropdown #} + {% if 'Containers' in nav_categories %} + {{ dropdown_menu('Containers', nav_categories['Containers'], 'containers') }} + {% endif %} + + {# pgEdge Cloud - direct link, no dropdown #} + {% for nav_item in nav %} + {% if nav_item.title | striptags | trim == 'pgEdge Cloud' %} +
  • + + pgEdge Cloud + +
    • + {% endif %} {% endfor %} + + {# AI Toolkit dropdown #} + {% if 'AI Toolkit' in nav_categories %} + {{ dropdown_menu('AI Toolkit', nav_categories['AI Toolkit'], 'ai-toolkit') }} + {% endif %} + + {# Extensions dropdown #} + {% if 'Extensions' in nav_categories %} + {{ dropdown_menu('Extensions', nav_categories['Extensions'], 'extensions') }} + {% endif %} + + {# Tools dropdown #} + {% if 'Tools' in nav_categories %} + {{ dropdown_menu('Tools', nav_categories['Tools'], 'tools') }} + {% endif %} From 7a7a3a72ad8b0be74e1f5f39d7896ffeb072497a Mon Sep 17 00:00:00 2001 From: Antony Pegg Date: Tue, 17 Mar 2026 08:34:22 -0400 Subject: [PATCH 02/13] Replace custom SVG icons with Lucide icons for light/dark mode support Use stroke="currentColor" via CSS var(--md-default-fg-color--light) so icons automatically adapt to the active color scheme. Icons: server, container, cloud, network, package, sparkles. --- docs/index.md | 77 ++++++++++++++++++++++++--------------------------- 1 file changed, 36 insertions(+), 41 deletions(-) diff --git a/docs/index.md b/docs/index.md index 74bc85db..16a7fef5 100644 --- a/docs/index.md +++ b/docs/index.md @@ -88,34 +88,23 @@ hide: line-height: 1.2; } -/* ICON SIZE — adjust this */ +/* ICON SIZE — Lucide icons at 56px */ .card-icon { - width: 56px !important; - height: 56px !important; - flex: 0 0 56px !important; + width: 48px !important; + height: 48px !important; + flex: 0 0 48px !important; display: block !important; + stroke: var(--md-default-fg-color--light); + stroke-width: 1.5; + stroke-linecap: round; + stroke-linejoin: round; + fill: none; /* defeat theme/global svg sizing rules */ max-width: none !important; max-height: none !important; } -.card-icon .stroke { - stroke: #2b2b2b; - stroke-width: 1.4; /* lighter at this size */ - fill: none; - stroke-linecap: round; - stroke-linejoin: round; -} - -.card-icon .accent { - stroke: #00bcd4; - stroke-width: 1.8; /* lighter at this size */ - fill: none; - stroke-linecap: round; - stroke-linejoin: round; -} - .card-description { color: var(--md-default-fg-color--light); font-size: 0.875rem; @@ -233,10 +222,11 @@ hide:

    VMs & Bare Metal

    -
    @@ -249,9 +239,12 @@ hide:

    Containers

    -
    @@ -265,10 +258,7 @@ hide:

    pgEdge Cloud

    @@ -290,10 +280,12 @@ hide:

    Control Plane

    -
    @@ -305,9 +297,11 @@ hide:

    Enterprise Repository

    -
    @@ -319,9 +313,10 @@ hide:

    AI Toolkit

    -
    From b4f369aac7266ee87e1a2bfe8a59a3f5fd400e00 Mon Sep 17 00:00:00 2001 From: Antony Pegg Date: Tue, 17 Mar 2026 09:17:45 -0400 Subject: [PATCH 03/13] Update VMs & Bare Metal card link to point to Control Plane docs Control Plane is the primary entry point for VM/bare metal deployments as the CLI/Platform tooling is being deprecated. --- docs/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/index.md b/docs/index.md index 16a7fef5..d6d5228a 100644 --- a/docs/index.md +++ b/docs/index.md @@ -231,7 +231,7 @@ hide:

    Direct installs on servers.

    - View Documentation → + View Documentation → From a49c479fe0e3765319b9e3f705406bb8e65d96f6 Mon Sep 17 00:00:00 2001 From: Antony Pegg Date: Wed, 18 Mar 2026 18:49:57 -0400 Subject: [PATCH 04/13] Restructure nav with dropdown sub-headings, add community docs - Replace VM/Bare Metal + Containers + Cloud with single Deployment dropdown - Rename Extensions to Database with pgEdge/Community sub-sections - Add sub-headings and HR dividers to dropdown menus - Add community docs: pgVector, PostGIS, pgAudit, pgAdmin, pgBouncer, PostgREST, psycopg2 (from postgresql-docs repo) - Update welcome page: new hero text, 4-column All Documentation section with sub-headings matching nav structure - Update Key Components cards to AI Toolkit, Enterprise Repository, Spock --- .gitignore | 9 ++ docs/index.md | 197 +++++++++++++++++++++++++++-------- docs/stylesheets/extra.css | 43 ++++++++ mkdocs.yml | 103 ++++++++++++------ overrides/partials/tabs.html | 54 +++++----- 5 files changed, 297 insertions(+), 109 deletions(-) diff --git a/.gitignore b/.gitignore index 0e17121d..7d4f5082 100644 --- a/.gitignore +++ b/.gitignore @@ -22,7 +22,16 @@ docs/pgedge-vectorizer/index.md docs/radar/index.md docs/snowflake/index.md docs/spock-v5/index.md +docs/pgadmin-4/index.md +docs/pgaudit/index.md +docs/pgbackrest/index.md +docs/pgbouncer/index.md +docs/pgvector/index.md +docs/postgis/index.md +docs/postgrest/index.md +docs/psycopg2/index.md # Ansible vault password file ansible/.pgedge-docs-vault-pass .vscode/settings.json +.superpowers/ diff --git a/docs/index.md b/docs/index.md index d6d5228a..71203fb6 100644 --- a/docs/index.md +++ b/docs/index.md @@ -145,15 +145,21 @@ hide: font-size: 0.95rem; } -/* Extensions Grid */ +/* Extensions Grid - 4 columns */ .extensions-grid { display: grid; - grid-template-columns: repeat(3, 1fr); + grid-template-columns: repeat(4, 1fr); gap: 2rem; margin: 2rem 0; } -@media (max-width: 768px) { +@media (max-width: 900px) { + .extensions-grid { + grid-template-columns: repeat(2, 1fr); + } +} + +@media (max-width: 600px) { .extensions-grid { grid-template-columns: 1fr; } @@ -197,16 +203,37 @@ hide: margin-top: 0.15rem; } +/* Sub-headings within extension lists */ +.extension-list .ext-subheading { + font-size: 0.7rem; + font-weight: 700; + text-transform: uppercase; + letter-spacing: 0.5px; + color: var(--md-default-fg-color--light); + padding: 0.6rem 0 0.2rem; + border-bottom: none; +} + +.extension-list .ext-subheading:first-child { + padding-top: 0; +} + +/* Dividers within extension lists */ +.extension-list .ext-divider { + padding: 0; + border-bottom: 1px solid var(--md-default-fg-color--lightest); +} +

    Welcome to pgEdge Documentation

    - Enterprise-ready PostgreSQL that scales with your needs—from a single database to globally distributed multi-master deployments. + Enterprise-grade PostgreSQL for distributed data and agentic AI.

    - pgEdge delivers hardened, production-grade PostgreSQL with a seamless path from day one through global scale. + pgEdge delivers hardened, production-grade PostgreSQL with a complete AI toolkit and a seamless path from a single database through highly available, globally distributed deployments — self-hosted, in your cloud, or fully managed.

    @@ -276,23 +303,23 @@ hide:
    +
    -

    Control Plane

    +

    AI Toolkit

    -

    Lifecycle management API.

    - View Documentation → +

    MCP, RAG, Vectorizer.

    + View Documentation →
    +
    @@ -309,92 +336,172 @@ hide: View Documentation →
    +
    -

    AI Toolkit

    +

    Spock

    -

    MCP, RAG, Vectorizer.

    - View Documentation → +

    Multi-master replication for PostgreSQL.

    + View Documentation →
    - +
    -

    Extensions & Components

    -

    Purpose-built extensions that enable pgEdge's advanced capabilities.

    +

    All Documentation

    -

    Replication & Distribution

    +

    Deployment

      +
    • VM / Bare Metal
    • - Spock v5 - Logical multi-master replication with bi-directional data flow and conflict resolution + Control Plane + Declarative API for deploying and managing PostgreSQL clusters on VMs and bare metal
    • - LOLOR - Large object replication for handling BLOBs in distributed environments + Enterprise Repository + Hardened, tested PostgreSQL packages for enterprise Linux and Debian/Ubuntu
    • - Snowflake - Distributed sequence generation for cluster-wide unique IDs + Ansible + Automated cluster deployment and configuration management with Ansible playbooks +
      • +
    • +
    • + Containers + Deploy pgEdge Enterprise Postgres on Kubernetes with Helm and CloudNativePG +
      • +
    • +
    • + pgEdge Cloud + Fully managed, globally distributed PostgreSQL as a service
    -

    AI & Agentic Capabilities

    +

    AI Toolkit

      +
    • pgEdge Components
    • MCP Server - Model Context Protocol server for LLM and AI agent access to PostgreSQL + Connect LLMs and AI agents directly to PostgreSQL via the Model Context Protocol +
      • +
    • + RAG Server + High-performance retrieval-augmented generation API with hybrid vector and keyword search +
      • +
    • + Docloader + CLI tool for loading and chunking documents into PostgreSQL for AI applications
    • Vectorizer - Automatic document chunking and vector embedding generation + Automatic document chunking and vector embedding generation inside PostgreSQL
      • +
    • +
    • Community Components
    • - RAG Server - High-performance Retrieval-Augmented Generation API with hybrid search + pgVector + Open-source vector similarity search for PostgreSQL +
      • +
    +
    + +
    +

    Database

    +
      +
    • + PostgreSQL + Reference documentation for PostgreSQL 16, 17, and 18 +
      • +
    • +
    • pgEdge Extensions
      • +
    • + Spock + Multi-master logical replication with conflict resolution for globally distributed clusters +
      • +
    • + LOLOR + Large object replication for handling BLOBs across distributed PostgreSQL nodes +
      • +
    • + Snowflake + Cluster-wide unique sequence generation without node coordination
    • - DocLoader - Command-line utility for loading documents into PostgreSQL for AI applications + Vectorizer + Automatic document chunking and vector embedding generation inside PostgreSQL +
      • +
    • +
    • Community Extensions
      • +
    • + pgVector + Open-source vector similarity search for PostgreSQL +
      • +
    • + PostGIS + Spatial and geographic object support for PostgreSQL +
      • +
    • + pgAudit + Detailed session and object audit logging for PostgreSQL
    -

    Operations & Utilities

    +

    Tools

      +
    • pgEdge Tools
    • - ACE (Active Consistency Engine) - Automated data integrity verification and repair across replicated clusters + ACE + Automated data integrity verification and repair across replicated cluster nodes
    • - Control Plane - Declarative API for database lifecycle management and orchestration + Anonymizer + Replace PII with realistic fake data for safe dev/test database copies +
      • +
    • + Loadgen + Generate realistic PostgreSQL workloads for performance testing and benchmarking
    • Radar Agentless diagnostic data collection for PostgreSQL and system metrics
      • +
    • +
    • Community Tools
    • - Anonymizer - PII replacement for safe dev/test database copies + pgAdmin 4 + Web-based administration and management tool for PostgreSQL
    • - Loadgen - Realistic workload generation and performance testing + pgBouncer + Lightweight connection pooler for PostgreSQL +
      • +
    • + pgBackRest + Reliable PostgreSQL backup and restore +
      • +
    • + PostgREST + RESTful API server for any PostgreSQL database +
      • +
    • + psycopg2 + PostgreSQL database adapter for Python
    diff --git a/docs/stylesheets/extra.css b/docs/stylesheets/extra.css index d64116e5..54438521 100644 --- a/docs/stylesheets/extra.css +++ b/docs/stylesheets/extra.css @@ -167,6 +167,49 @@ opacity: 1; } +/* Dropdown sub-headings - non-clickable labels */ +.md-tabs__dropdown-heading { + padding: 0.5rem 1rem 0.2rem; + font-size: 0.6rem; + font-weight: 700; + text-transform: uppercase; + letter-spacing: 0.5px; + list-style: none; + pointer-events: none; +} + +.md-tabs__dropdown-heading:first-child { + padding-top: 0.2rem; +} + +[data-md-color-scheme="default"] .md-tabs__dropdown-heading { + color: var(--md-default-fg-color); + opacity: 0.5; +} + +[data-md-color-scheme="slate"] .md-tabs__dropdown-heading { + color: var(--md-primary-bg-color); + opacity: 0.5; +} + +/* Dropdown horizontal rule dividers */ +.md-tabs__dropdown-divider { + margin: 0.3rem 1rem; + border: 0; + height: 1px; + list-style: none; +} + +[data-md-color-scheme="default"] .md-tabs__dropdown-divider { + background: var(--md-default-fg-color); + opacity: 0.15; +} + +[data-md-color-scheme="slate"] .md-tabs__dropdown-divider { + background: var(--md-primary-bg-color); + opacity: 0.2; +} + /* ========================================================================== Version Selector Styles ========================================================================== */ diff --git a/mkdocs.yml b/mkdocs.yml index d9e8fb7d..82b4c802 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -153,26 +153,28 @@ extra: - pgaudit - postgis - # Navigation dropdown categories - maps nav item titles to dropdown menus - # Use simple string for auto-detected URLs, or {title: url} for explicit URLs + # Navigation dropdown categories + # Supported item types: + # - title/url: clickable link + # - heading: non-clickable sub-heading label + # - hr: horizontal rule divider nav_categories: - VM / Bare Metal: + Deployment: + - heading: "VM / Bare Metal" - title: Control Plane url: control-plane/ - - title: Distributed CLI - url: platform/ - - title: pgEdge Package Repository + - title: Enterprise Repository url: enterprise/ - - title: PostgreSQL - url: postgresql/ - title: Ansible url: ansible/ - Containers: - - title: pgEdge Container + - hr: true + - title: Containers url: pgedge-container/ - - title: Container Registry - url: container-images/ + - hr: true + - title: pgEdge Cloud + url: cloud/ AI Toolkit: + - heading: "pgEdge Components" - title: pgEdge Postgres MCP Server url: pgedge-postgres-mcp-server/ - title: pgEdge RAG Server @@ -181,14 +183,33 @@ extra: url: pgedge-docloader/ - title: pgEdge Vectorizer url: pgedge-vectorizer/ - Extensions: + - hr: true + - heading: "Community Components" + - title: pgVector + url: pgvector/ + Database: + - title: PostgreSQL + url: postgresql/ + - hr: true + - heading: "pgEdge Extensions" - title: Spock v5 url: spock-v5/ - title: LOLOR url: lolor/ - title: Snowflake url: snowflake/ + - title: pgEdge Vectorizer + url: pgedge-vectorizer/ + - hr: true + - heading: "Community Extensions" + - title: pgVector + url: pgvector/ + - title: PostGIS + url: postgis/ + - title: pgAudit + url: pgaudit/ Tools: + - heading: "pgEdge Tools" - title: ACE url: ace/ - title: pgEdge Anonymizer @@ -197,6 +218,18 @@ extra: url: pgedge-loadgen/ - title: Radar url: radar/ + - hr: true + - heading: "Community Tools" + - title: pgAdmin 4 + url: pgadmin-4/ + - title: pgBouncer + url: pgbouncer/ + - title: pgBackRest + url: pgbackrest/ + - title: PostgREST + url: postgrest/ + - title: psycopg2 + url: psycopg2/ copyright: Copyright © 2023 - 2026, pgEdge, Inc – Change cookie settings @@ -504,21 +537,39 @@ nav: - v16: '!import https://github.com/pgEdge/3rd-party-docs.git?branch=pg16' - Development: '!import https://github.com/pgEdge/3rd-party-docs.git?branch=pg19' + # Community Extensions (from 3rd-party-docs repo) + - pgvector: + - v0.8.1: '!import https://github.com/pgEdge/3rd-party-docs.git?branch=pgvector081' + - v0.8.0: '!import https://github.com/pgEdge/3rd-party-docs.git?branch=pgvector080' + - Development: '!import https://github.com/pgEdge/3rd-party-docs.git?branch=pgvectormaster' + + - postgis: + - v3.6.2: '!import https://github.com/pgEdge/3rd-party-docs.git?branch=postgis362' + - v3.5.5: '!import https://github.com/pgEdge/3rd-party-docs.git?branch=postgis355' + - Development: '!import https://github.com/pgEdge/3rd-party-docs.git?branch=postgismaster' + + - pgAudit: + - v18.0: '!import https://github.com/pgEdge/3rd-party-docs.git?branch=pgaudit180' + - v17.1: '!import https://github.com/pgEdge/3rd-party-docs.git?branch=pgaudit171' + - v16.1: '!import https://github.com/pgEdge/3rd-party-docs.git?branch=pgaudit161' + - Development: '!import https://github.com/pgEdge/3rd-party-docs.git?branch=pgauditmaster' + + # Community Tools (from 3rd-party-docs repo) - pgAdmin 4: - v9.13: '!import https://github.com/pgEdge/3rd-party-docs.git?branch=pgadmin913' - v9.12: '!import https://github.com/pgEdge/3rd-party-docs.git?branch=pgadmin912' - v9.11: '!import https://github.com/pgEdge/3rd-party-docs.git?branch=pgadmin911' - Development: '!import https://github.com/pgEdge/3rd-party-docs.git?branch=pgadminmaster' + - PgBouncer: + - v1.25: '!import https://github.com/pgEdge/3rd-party-docs.git?branch=pgbouncer125' + - v1.24: '!import https://github.com/pgEdge/3rd-party-docs.git?branch=pgbouncer124' + - Development: '!import https://github.com/pgEdge/3rd-party-docs.git?branch=pgbouncermaster' + - postgrest: - v14.5: '!import https://github.com/pgEdge/3rd-party-docs.git?branch=postgrest145' - Development: '!import https://github.com/pgEdge/3rd-party-docs.git?branch=postgrestmaster' - - postgis: - - v3.6.2: '!import https://github.com/pgEdge/3rd-party-docs.git?branch=postgis362' - - v3.5.5: '!import https://github.com/pgEdge/3rd-party-docs.git?branch=postgis355' - - Development: '!import https://github.com/pgEdge/3rd-party-docs.git?branch=postgismaster' - - psycopg2: - v2.9.10: '!import https://github.com/pgEdge/3rd-party-docs.git?branch=psycopg2910' - Development: '!import https://github.com/pgEdge/3rd-party-docs.git?branch=psycopg2master' @@ -527,19 +578,3 @@ nav: - v2.58.0: '!import https://github.com/pgEdge/3rd-party-docs.git?branch=pgbackrest258' - v2.57.0: '!import https://github.com/pgEdge/3rd-party-docs.git?branch=pgbackrest257' - Development: '!import https://github.com/pgEdge/3rd-party-docs.git?branch=pgbackrestmaster' - - - PgBouncer: - - v1.25: '!import https://github.com/pgEdge/3rd-party-docs.git?branch=pgbouncer125' - - v1.24: '!import https://github.com/pgEdge/3rd-party-docs.git?branch=pgbouncer124' - - Development: '!import https://github.com/pgEdge/3rd-party-docs.git?branch=pgbouncermaster' - - - pgvector: - - v0.8.1: '!import https://github.com/pgEdge/3rd-party-docs.git?branch=pgvector081' - - v0.8.0: '!import https://github.com/pgEdge/3rd-party-docs.git?branch=pgvector080' - - Development: '!import https://github.com/pgEdge/3rd-party-docs.git?branch=pgvectormaster' - - - pgAudit: - - v18.0: '!import https://github.com/pgEdge/3rd-party-docs.git?branch=pgaudit180' - - v17.1: '!import https://github.com/pgEdge/3rd-party-docs.git?branch=pgaudit171' - - v16.1: '!import https://github.com/pgEdge/3rd-party-docs.git?branch=pgaudit161' - - Development: '!import https://github.com/pgEdge/3rd-party-docs.git?branch=pgauditmaster' diff --git a/overrides/partials/tabs.html b/overrides/partials/tabs.html index b636a2d2..b0d78262 100644 --- a/overrides/partials/tabs.html +++ b/overrides/partials/tabs.html @@ -6,7 +6,7 @@ {# Get nav categories from mkdocs.yml extra section #} {% set nav_categories = config.extra.nav_categories or {} %} -{# Macro to render a dropdown menu #} +{# Macro to render a dropdown menu with support for headings and dividers #} {% macro dropdown_menu(label, category_items, dropdown_id) %}
    • - {# Process each category item - render directly using title and url #} {% for cat_item in category_items %} - {% if cat_item is string %} + {% if cat_item.heading is defined %} + {# Non-clickable sub-heading #} +
    • {{ cat_item.heading }}
      • + {% elif cat_item.hr is defined %} + {# Horizontal rule divider #} +
    • + {% elif cat_item is string %} {% set cat_title = cat_item %} {% set cat_url = "." %} +
    • + + {{ cat_title }} + +
      • {% else %} {% set cat_title = cat_item.title %} {% set cat_url = cat_item.url | default(".") %} +
    • + + {{ cat_title }} + +
      • {% endif %} -
    • - - {{ cat_title }} - -
      • {% endfor %}
    • @@ -49,35 +59,19 @@ {% endif %} {% endfor %} - {# VM / Bare Metal dropdown #} - {% if 'VM / Bare Metal' in nav_categories %} - {{ dropdown_menu('VM / Bare Metal', nav_categories['VM / Bare Metal'], 'vm-bare-metal') }} + {# Deployment dropdown #} + {% if 'Deployment' in nav_categories %} + {{ dropdown_menu('Deployment', nav_categories['Deployment'], 'deployment') }} {% endif %} - {# Containers dropdown #} - {% if 'Containers' in nav_categories %} - {{ dropdown_menu('Containers', nav_categories['Containers'], 'containers') }} - {% endif %} - - {# pgEdge Cloud - direct link, no dropdown #} - {% for nav_item in nav %} - {% if nav_item.title | striptags | trim == 'pgEdge Cloud' %} -
  • - - pgEdge Cloud - -
    • - {% endif %} - {% endfor %} - {# AI Toolkit dropdown #} {% if 'AI Toolkit' in nav_categories %} {{ dropdown_menu('AI Toolkit', nav_categories['AI Toolkit'], 'ai-toolkit') }} {% endif %} - {# Extensions dropdown #} - {% if 'Extensions' in nav_categories %} - {{ dropdown_menu('Extensions', nav_categories['Extensions'], 'extensions') }} + {# Database dropdown #} + {% if 'Database' in nav_categories %} + {{ dropdown_menu('Database', nav_categories['Database'], 'database') }} {% endif %} {# Tools dropdown #} From 02ef0bf7100007aa6ddba369dfd8bc36af13eba8 Mon Sep 17 00:00:00 2001 From: Antony Pegg Date: Thu, 19 Mar 2026 12:58:57 -0400 Subject: [PATCH 05/13] Add AI Toolkit overview page, update MCP Server card and nav --- docs/ai-toolkit/index.md | 122 +++++++++++++++++++++++++++++++++++++++ docs/index.md | 11 +++- mkdocs.yml | 5 ++ 3 files changed, 135 insertions(+), 3 deletions(-) create mode 100644 docs/ai-toolkit/index.md diff --git a/docs/ai-toolkit/index.md b/docs/ai-toolkit/index.md new file mode 100644 index 00000000..3875c792 --- /dev/null +++ b/docs/ai-toolkit/index.md @@ -0,0 +1,122 @@ +# AI Toolkit + +The pgEdge AI Toolkit connects AI agents and LLMs to PostgreSQL through two independent capabilities: **secure database access** and **retrieval-augmented generation (RAG)**. + +The **pgEdge Postgres MCP Server** gives AI agents autonomous, structured access to your database through the Model Context Protocol — with built-in security, PostgreSQL-specific knowledge, and support for multiple LLM providers. It works standalone and requires no additional toolkit components. + +For applications that need to answer questions over a document corpus, the remaining components form a **complete RAG pipeline**: Docloader ingests documents, the Vectorizer chunks and embeds them, and the RAG Server answers questions over the resulting knowledge base. + +Both capabilities share **[pgVector](../pgvector/)** as a foundation — it provides the vector similarity search that powers the MCP Server's semantic search tools and the RAG pipeline's hybrid retrieval. + +## Components + +| Component | Description | +|-----------|-------------| +| **[pgEdge Postgres MCP Server](../pgedge-postgres-mcp-server/)** | Secure, structured PostgreSQL access for AI agents via the Model Context Protocol | +| **[pgEdge RAG Server](../pgedge-rag-server/)** | HTTP API for retrieval-augmented generation with hybrid vector and keyword search | +| **[pgEdge Docloader](../pgedge-docloader/)** | CLI tool for loading documents into PostgreSQL from files, directories, and Git repos | +| **[pgEdge Vectorizer](../pgedge-vectorizer/)** | PostgreSQL extension for automatic text chunking and vector embedding generation | +| **[pgVector](../pgvector/)** | Open-source vector similarity search for PostgreSQL (shared dependency) | + +## Connecting AI agents with the MCP Server + +Rather than giving an LLM raw database credentials — uncontrolled access to every table, no guardrails on query complexity, no visibility into what the model is doing — the [MCP Server](../pgedge-postgres-mcp-server/) acts as a controlled gateway. It exposes a defined set of tools that an agent can invoke (schema inspection, SQL execution, similarity search, embedding generation, query plan analysis, and knowledgebase search), while enforcing read-only transactions by default with token authentication, TLS, and PostgreSQL row-level security. + +This is not a generic database access tool. The MCP Server is purpose-built for PostgreSQL and ships with a **built-in PostgreSQL knowledgebase**. When an agent needs to understand a PostgreSQL feature, diagnose a configuration issue, or write correct syntax for an extension, it queries the knowledgebase directly rather than relying on the LLM's training data (which may be outdated or imprecise). This is the difference between a thin SQL proxy and an enterprise-grade database assistant that understands PostgreSQL deeply. + +The server supports **Anthropic Claude**, **OpenAI**, and **Ollama** as LLM providers, and offers two connection modes: + +- **stdio** — For desktop clients (Claude Desktop, Cursor, VS Code Copilot, Windsurf) where the server runs as a local subprocess. +- **HTTP + SSE** — For multi-user and remote deployments where the server runs as a long-lived service. The built-in **Go CLI client** and **React web chat interface** both connect via this mode. + +```mermaid +flowchart LR + subgraph clients ["Clients"] + direction TB + CD[Claude Desktop] + CU[Cursor] + VS[VS Code Copilot] + WS[Windsurf] + CA[Custom Agents] + CLI[Go CLI] + WEB[Web Chat] + end + + subgraph server ["pgEdge Postgres MCP Server"] + direction TB + STDIO[stdio] + HTTP[HTTP + SSE] + AUTH[Auth · TLS · RLS] + end + + subgraph data [" "] + direction TB + DB[(PostgreSQL
    + pgVector)] + KB[(PostgreSQL
    Knowledgebase)] + end + + CD & CU & VS & WS -->|stdio| STDIO + CA & CLI & WEB -->|HTTP| HTTP + server --> DB + server --> KB +``` + +### Security model + +AI agents never interact with your database unguarded: + +- **Read-only by default** — All queries run inside read-only transactions unless explicitly configured otherwise. +- **Authentication** — Token-based and user-based authentication control which agents can connect. +- **TLS** — All HTTP connections can be encrypted in transit. +- **Row-level security** — PostgreSQL's native RLS policies are respected, so different agents or users see only the data they're authorized to access. +- **Defined tool surface** — Agents can only perform operations the MCP Server exposes. There is no open-ended SQL access unless the administrator enables it. + +## Building a RAG pipeline + +```mermaid +flowchart TB + subgraph Ingestion + direction LR + A[Source Documents] --> B[pgEdge Docloader] + end + + subgraph db ["PostgreSQL + pgVector"] + direction LR + C[(Document Tables)] ~~~ D[(Chunk Tables
    with Embeddings)] + end + + subgraph bottom [" "] + direction LR + E[pgEdge Vectorizer] ~~~ F[pgEdge RAG Server] + end + + B -->|load & convert| C + C -->|trigger on insert/update| E + E -->|chunk + embed| D + D -->|hybrid search| F + F -->|context + LLM| H[AI Responses] +``` + +### Ingestion: Docloader → PostgreSQL + +**[pgEdge Docloader](../pgedge-docloader/)** reads source content — local files, directories, glob patterns, or Git repositories — and loads it into a PostgreSQL table. Each document is converted to Markdown and stored with metadata (title, filename, timestamps). Loading is transactional (a batch fully commits or rolls back), and UPSERT mode allows re-running the same load to pick up changes without duplicating rows. + +At this stage, the data is plain text in standard PostgreSQL tables. No vectors or chunking are involved yet. + +### Processing: Vectorizer + pgVector + +**[pgEdge Vectorizer](../pgedge-vectorizer/)** watches configured tables for `INSERT` and `UPDATE` operations via triggers. Changed rows are queued, and background workers handle the rest: + +1. **Chunking** — Text is split into segments sized for embedding models. Strategies include fixed token windows, Markdown-aware splitting that respects document structure, and a hybrid two-pass approach. + +2. **Embedding** — Each chunk is sent to a configured provider (OpenAI, Voyage AI, or Ollama) and the resulting vector is stored in a chunk table using **[pgVector](../pgvector/)** column types. + +3. **Queue management** — Workers process batches with retry logic and exponential backoff. Completed items are cleaned up automatically. + +The result is a set of chunk tables where each row contains a text fragment, its vector embedding, and a foreign key back to the source document, indexed by pgVector for fast similarity search. + +### Serving: RAG Server + +Pointing an LLM directly at your chunk tables is both a security risk and a retrieval quality problem. The LLM has unguarded access to whatever data is in the tables, pure vector similarity misses keyword-exact matches, and near-duplicate passages waste the context window. The application is left to handle embedding generation, token budgeting, and LLM orchestration itself. + +**[pgEdge RAG Server](../pgedge-rag-server/)** solves both problems. It constrains access to pre-configured pipelines against specific tables — the LLM never generates SQL. When a query arrives, the server runs a hybrid search: pgVector cosine similarity for semantic matching and BM25 for keyword matching. Results are fused using Reciprocal Rank Fusion, deduplicated, and assembled into a context window that respects a configurable token budget, then sent to an LLM (OpenAI, Anthropic, or Ollama) for a generated answer. Multiple pipelines can run independently, each with its own database, tables, and provider configuration. diff --git a/docs/index.md b/docs/index.md index 71203fb6..7115bdb6 100644 --- a/docs/index.md +++ b/docs/index.md @@ -303,11 +303,11 @@ hide:
    - +
    -

    AI Toolkit

    +

    pgEdge Postgres MCP Server

    -

    MCP, RAG, Vectorizer.

    +

    Give AI agents secure, structured access to PostgreSQL.

    View Documentation →
    @@ -393,6 +393,11 @@ hide:

    AI Toolkit

      +
    • + Overview + Architecture guide covering agent access and RAG pipelines +
      • +
    • pgEdge Components
    • MCP Server diff --git a/mkdocs.yml b/mkdocs.yml index 82b4c802..7f97b13d 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -174,6 +174,9 @@ extra: - title: pgEdge Cloud url: cloud/ AI Toolkit: + - title: Overview + url: ai-toolkit/ + - hr: true - heading: "pgEdge Components" - title: pgEdge Postgres MCP Server url: pgedge-postgres-mcp-server/ @@ -238,6 +241,8 @@ repo_url: https://github.com/pgEdge nav: - Welcome: index.md + - AI Toolkit: ai-toolkit/index.md + - Ansible: ansible/index.md - pgEdge Enterprise Postgres: From d28dd25e24b1edd77c419dda462de324648dd31d Mon Sep 17 00:00:00 2001 From: Antony Pegg Date: Thu, 19 Mar 2026 13:38:17 -0400 Subject: [PATCH 06/13] Rebalance AI Toolkit overview: restore component descriptions, trim architectural sections --- docs/ai-toolkit/index.md | 44 ++++++++++++++++++---------------------- 1 file changed, 20 insertions(+), 24 deletions(-) diff --git a/docs/ai-toolkit/index.md b/docs/ai-toolkit/index.md index 3875c792..c31a89e5 100644 --- a/docs/ai-toolkit/index.md +++ b/docs/ai-toolkit/index.md @@ -10,21 +10,27 @@ Both capabilities share **[pgVector](../pgvector/)** as a foundation — it prov ## Components -| Component | Description | -|-----------|-------------| -| **[pgEdge Postgres MCP Server](../pgedge-postgres-mcp-server/)** | Secure, structured PostgreSQL access for AI agents via the Model Context Protocol | -| **[pgEdge RAG Server](../pgedge-rag-server/)** | HTTP API for retrieval-augmented generation with hybrid vector and keyword search | -| **[pgEdge Docloader](../pgedge-docloader/)** | CLI tool for loading documents into PostgreSQL from files, directories, and Git repos | -| **[pgEdge Vectorizer](../pgedge-vectorizer/)** | PostgreSQL extension for automatic text chunking and vector embedding generation | -| **[pgVector](../pgvector/)** | Open-source vector similarity search for PostgreSQL (shared dependency) | +### pgEdge Components + +**[pgEdge Postgres MCP Server](../pgedge-postgres-mcp-server/)** — Gives AI agents secure, structured access to PostgreSQL through the Model Context Protocol. Exposes tools for schema inspection, SQL execution, similarity search, embedding generation, query plan analysis, and knowledgebase search. Supports Claude, OpenAI, and Ollama, with read-only defaults, authentication, TLS, and row-level security. + +**[pgEdge RAG Server](../pgedge-rag-server/)** — HTTP API for retrieval-augmented generation. Runs hybrid search combining pgVector cosine similarity with BM25 keyword ranking, fuses results using Reciprocal Rank Fusion, and sends assembled context to an LLM for completion. Supports multiple independent pipelines, streaming responses, and conversation history. + +**[pgEdge Docloader](../pgedge-docloader/)** — CLI tool for loading documents into PostgreSQL from local files, glob patterns, or Git repositories. Accepts HTML, Markdown, reStructuredText, and SGML/DocBook, converting all content to Markdown with extracted metadata. Supports transactional loading and UPSERT mode for incremental updates. + +**[pgEdge Vectorizer](../pgedge-vectorizer/)** — PostgreSQL extension that automatically chunks text and generates vector embeddings via background workers. Triggers detect inserts and updates on configured tables, with configurable chunking strategies and support for OpenAI, Voyage AI, and Ollama embedding providers. + +### Community Components + +**[pgVector](../pgvector/)** — Open-source PostgreSQL extension for vector similarity search. Adds a `vector` column type with IVFFlat and HNSW indexing. pgVector is a shared dependency across the toolkit: the MCP Server uses it for semantic search, the Vectorizer stores embeddings in pgVector columns, and the RAG Server queries them for retrieval. ## Connecting AI agents with the MCP Server -Rather than giving an LLM raw database credentials — uncontrolled access to every table, no guardrails on query complexity, no visibility into what the model is doing — the [MCP Server](../pgedge-postgres-mcp-server/) acts as a controlled gateway. It exposes a defined set of tools that an agent can invoke (schema inspection, SQL execution, similarity search, embedding generation, query plan analysis, and knowledgebase search), while enforcing read-only transactions by default with token authentication, TLS, and PostgreSQL row-level security. +Rather than giving an LLM raw database credentials — uncontrolled access to every table, no guardrails on query complexity, no visibility into what the model is doing — the [MCP Server](../pgedge-postgres-mcp-server/) acts as a controlled gateway with read-only defaults, authentication, TLS, and PostgreSQL row-level security. -This is not a generic database access tool. The MCP Server is purpose-built for PostgreSQL and ships with a **built-in PostgreSQL knowledgebase**. When an agent needs to understand a PostgreSQL feature, diagnose a configuration issue, or write correct syntax for an extension, it queries the knowledgebase directly rather than relying on the LLM's training data (which may be outdated or imprecise). This is the difference between a thin SQL proxy and an enterprise-grade database assistant that understands PostgreSQL deeply. +The MCP Server is purpose-built for PostgreSQL and ships with a **built-in PostgreSQL knowledgebase**. When an agent needs to understand a PostgreSQL feature, diagnose a configuration issue, or write correct syntax for an extension, it queries the knowledgebase directly rather than relying on the LLM's training data (which may be outdated or imprecise). -The server supports **Anthropic Claude**, **OpenAI**, and **Ollama** as LLM providers, and offers two connection modes: +The server offers two connection modes: - **stdio** — For desktop clients (Claude Desktop, Cursor, VS Code Copilot, Windsurf) where the server runs as a local subprocess. - **HTTP + SSE** — For multi-user and remote deployments where the server runs as a long-lived service. The built-in **Go CLI client** and **React web chat interface** both connect via this mode. @@ -99,24 +105,14 @@ flowchart TB ### Ingestion: Docloader → PostgreSQL -**[pgEdge Docloader](../pgedge-docloader/)** reads source content — local files, directories, glob patterns, or Git repositories — and loads it into a PostgreSQL table. Each document is converted to Markdown and stored with metadata (title, filename, timestamps). Loading is transactional (a batch fully commits or rolls back), and UPSERT mode allows re-running the same load to pick up changes without duplicating rows. - -At this stage, the data is plain text in standard PostgreSQL tables. No vectors or chunking are involved yet. +**[Docloader](../pgedge-docloader/)** reads source content and loads it into a PostgreSQL table, converting documents to Markdown with extracted metadata. Loading is transactional, and UPSERT mode allows re-running the same load to pick up changes without duplicating rows. At this stage, the data is plain text — no vectors or chunking are involved yet. ### Processing: Vectorizer + pgVector -**[pgEdge Vectorizer](../pgedge-vectorizer/)** watches configured tables for `INSERT` and `UPDATE` operations via triggers. Changed rows are queued, and background workers handle the rest: - -1. **Chunking** — Text is split into segments sized for embedding models. Strategies include fixed token windows, Markdown-aware splitting that respects document structure, and a hybrid two-pass approach. - -2. **Embedding** — Each chunk is sent to a configured provider (OpenAI, Voyage AI, or Ollama) and the resulting vector is stored in a chunk table using **[pgVector](../pgvector/)** column types. - -3. **Queue management** — Workers process batches with retry logic and exponential backoff. Completed items are cleaned up automatically. - -The result is a set of chunk tables where each row contains a text fragment, its vector embedding, and a foreign key back to the source document, indexed by pgVector for fast similarity search. +**[Vectorizer](../pgedge-vectorizer/)** watches configured tables for changes via triggers. When rows are inserted or updated, background workers chunk the text and generate embeddings, storing the results in dedicated chunk tables using **[pgVector](../pgvector/)** column types. The chunk tables are indexed for fast similarity search. ### Serving: RAG Server -Pointing an LLM directly at your chunk tables is both a security risk and a retrieval quality problem. The LLM has unguarded access to whatever data is in the tables, pure vector similarity misses keyword-exact matches, and near-duplicate passages waste the context window. The application is left to handle embedding generation, token budgeting, and LLM orchestration itself. +Pointing an LLM directly at chunk tables is both a security risk and a retrieval quality problem — unguarded data access, no keyword matching, duplicate passages wasting the context window, and embedding/token/LLM orchestration left to the application. -**[pgEdge RAG Server](../pgedge-rag-server/)** solves both problems. It constrains access to pre-configured pipelines against specific tables — the LLM never generates SQL. When a query arrives, the server runs a hybrid search: pgVector cosine similarity for semantic matching and BM25 for keyword matching. Results are fused using Reciprocal Rank Fusion, deduplicated, and assembled into a context window that respects a configurable token budget, then sent to an LLM (OpenAI, Anthropic, or Ollama) for a generated answer. Multiple pipelines can run independently, each with its own database, tables, and provider configuration. +**[RAG Server](../pgedge-rag-server/)** solves this by constraining access to pre-configured pipelines against specific tables (the LLM never generates SQL) and handling hybrid retrieval (vector + BM25), deduplication, and context assembly in a single layer. From a9f091611845179c606f552041e76f72d6fb69fd Mon Sep 17 00:00:00 2001 From: Antony Pegg Date: Thu, 19 Mar 2026 14:10:02 -0400 Subject: [PATCH 07/13] Fix PgBouncer casing: align nav_categories and welcome page with nav entry --- docs/index.md | 2 +- mkdocs.yml | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/index.md b/docs/index.md index 7115bdb6..32e91e2c 100644 --- a/docs/index.md +++ b/docs/index.md @@ -493,7 +493,7 @@ hide: Web-based administration and management tool for PostgreSQL
    • - pgBouncer + PgBouncer Lightweight connection pooler for PostgreSQL
    • diff --git a/mkdocs.yml b/mkdocs.yml index 7f97b13d..3adc83c3 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -225,7 +225,7 @@ extra: - heading: "Community Tools" - title: pgAdmin 4 url: pgadmin-4/ - - title: pgBouncer + - title: PgBouncer url: pgbouncer/ - title: pgBackRest url: pgbackrest/ From 64875b19859a900ba9190db24be393554bb8a3b1 Mon Sep 17 00:00:00 2001 From: susan-pgedge <130390403+susan-pgedge@users.noreply.github.com> Date: Fri, 20 Mar 2026 07:01:13 -0400 Subject: [PATCH 08/13] Update index.md Minor editing... fixed bulleted list and wrapping. --- docs/ansible/index.md | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/docs/ansible/index.md b/docs/ansible/index.md index c4004fbb..d5a320c9 100644 --- a/docs/ansible/index.md +++ b/docs/ansible/index.md @@ -1,18 +1,20 @@ # Ansible -pgEdge provides an Ansible collection for deploying and managing PostgreSQL clusters on VMs and bare metal servers. +pgEdge provides an Ansible collection for deploying and managing PostgreSQL +clusters on VMs and bare metal servers. ## Overview The pgEdge Ansible collection includes roles for: -- Deploying pgEdge Enterprise Postgres -- Configuring pgEdge Distributed Postgres clusters -- Managing Spock replication setup +- deploying pgEdge Enterprise Postgres. +- configuring pgEdge Distributed Postgres clusters. +- managing Spock replication setup. ## Documentation -For complete documentation, installation instructions, and sample playbooks, see the GitHub repository: +For complete documentation, installation instructions, and sample playbooks, +see the GitHub repository: **[pgEdge Ansible Collection on GitHub](https://github.com/pgEdge/pgedge-ansible)** From c41948913b89e232aed44a0f03a6640919e5e9f1 Mon Sep 17 00:00:00 2001 From: susan-pgedge <130390403+susan-pgedge@users.noreply.github.com> Date: Fri, 20 Mar 2026 07:06:43 -0400 Subject: [PATCH 09/13] Update index.md --- docs/ansible/index.md | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/docs/ansible/index.md b/docs/ansible/index.md index d5a320c9..b264d88c 100644 --- a/docs/ansible/index.md +++ b/docs/ansible/index.md @@ -20,6 +20,9 @@ see the GitHub repository: ## Related Resources -- [Distributed CLI documentation](../platform/) - Manual VM deployments -- [Control Plane documentation](../control-plane/) - Declarative API for cluster management -- [pgEdge Cloud documentation](../cloud/) - Managed cloud deployments +- [Distributed CLI documentation](../platform/) - Using the Distributed CLI for + manual VM deployments. +- [Control Plane documentation](../control-plane/) - Using the Control Plane + for declarative API-based cluster management. +- [pgEdge Cloud documentation](../cloud/) - Using pgEdge Cloud for managed + cloud deployments. From bc1ecc7207513fafafb7b7e84b6d503a25adcc7b Mon Sep 17 00:00:00 2001 From: susan-pgedge <130390403+susan-pgedge@users.noreply.github.com> Date: Fri, 20 Mar 2026 07:40:14 -0400 Subject: [PATCH 10/13] Update index.md --- docs/ai-toolkit/index.md | 120 ++++++++++++++++++++++++++++++--------- 1 file changed, 93 insertions(+), 27 deletions(-) diff --git a/docs/ai-toolkit/index.md b/docs/ai-toolkit/index.md index c31a89e5..56288ba3 100644 --- a/docs/ai-toolkit/index.md +++ b/docs/ai-toolkit/index.md @@ -1,39 +1,85 @@ # AI Toolkit -The pgEdge AI Toolkit connects AI agents and LLMs to PostgreSQL through two independent capabilities: **secure database access** and **retrieval-augmented generation (RAG)**. +The pgEdge AI Toolkit connects AI agents and LLMs to PostgreSQL through two +independent capabilities: **secure database access** and +**retrieval-augmented generation (RAG)**. -The **pgEdge Postgres MCP Server** gives AI agents autonomous, structured access to your database through the Model Context Protocol — with built-in security, PostgreSQL-specific knowledge, and support for multiple LLM providers. It works standalone and requires no additional toolkit components. +The **pgEdge Postgres MCP Server** gives AI agents autonomous, structured +access to your database through the Model Context Protocol — with built-in +security, PostgreSQL-specific knowledge, and support for multiple LLM +providers. It works standalone and requires no additional toolkit +components. -For applications that need to answer questions over a document corpus, the remaining components form a **complete RAG pipeline**: Docloader ingests documents, the Vectorizer chunks and embeds them, and the RAG Server answers questions over the resulting knowledge base. +For applications that need to answer questions over a document corpus, the +remaining components form a **complete RAG pipeline**: Docloader ingests +documents, the Vectorizer chunks and embeds them, and the RAG Server answers +questions over the resulting knowledge base. -Both capabilities share **[pgVector](../pgvector/)** as a foundation — it provides the vector similarity search that powers the MCP Server's semantic search tools and the RAG pipeline's hybrid retrieval. +Both capabilities share **[pgVector](../pgvector/)** as a foundation — it +provides the vector similarity search that powers the MCP Server's semantic +search tools and the RAG pipeline's hybrid retrieval. ## Components -### pgEdge Components - -**[pgEdge Postgres MCP Server](../pgedge-postgres-mcp-server/)** — Gives AI agents secure, structured access to PostgreSQL through the Model Context Protocol. Exposes tools for schema inspection, SQL execution, similarity search, embedding generation, query plan analysis, and knowledgebase search. Supports Claude, OpenAI, and Ollama, with read-only defaults, authentication, TLS, and row-level security. +The pgEdge AI Toolkit consists of the following components. -**[pgEdge RAG Server](../pgedge-rag-server/)** — HTTP API for retrieval-augmented generation. Runs hybrid search combining pgVector cosine similarity with BM25 keyword ranking, fuses results using Reciprocal Rank Fusion, and sends assembled context to an LLM for completion. Supports multiple independent pipelines, streaming responses, and conversation history. - -**[pgEdge Docloader](../pgedge-docloader/)** — CLI tool for loading documents into PostgreSQL from local files, glob patterns, or Git repositories. Accepts HTML, Markdown, reStructuredText, and SGML/DocBook, converting all content to Markdown with extracted metadata. Supports transactional loading and UPSERT mode for incremental updates. +### pgEdge Components -**[pgEdge Vectorizer](../pgedge-vectorizer/)** — PostgreSQL extension that automatically chunks text and generates vector embeddings via background workers. Triggers detect inserts and updates on configured tables, with configurable chunking strategies and support for OpenAI, Voyage AI, and Ollama embedding providers. +**[pgEdge Postgres MCP Server](../pgedge-postgres-mcp-server/)** — Gives AI +agents secure, structured access to PostgreSQL through the Model Context +Protocol. Exposes tools for schema inspection, SQL execution, similarity +search, embedding generation, query plan analysis, and knowledgebase search. +Supports Claude, OpenAI, and Ollama, with read-only defaults, +authentication, TLS, and row-level security. + +**[pgEdge RAG Server](../pgedge-rag-server/)** — HTTP API for +retrieval-augmented generation. Runs hybrid search combining pgVector cosine +similarity with BM25 keyword ranking, fuses results using Reciprocal Rank +Fusion, and sends assembled context to an LLM for completion. Supports +multiple independent pipelines, streaming responses, and conversation +history. + +**[pgEdge Docloader](../pgedge-docloader/)** — CLI tool for loading +documents into PostgreSQL from local files, glob patterns, or Git +repositories. Accepts HTML, Markdown, reStructuredText, and SGML/DocBook, +converting all content to Markdown with extracted metadata. Supports +transactional loading and UPSERT mode for incremental updates. + +**[pgEdge Vectorizer](../pgedge-vectorizer/)** — PostgreSQL extension that +automatically chunks text and generates vector embeddings via background +workers. Triggers detect inserts and updates on configured tables, with +configurable chunking strategies and support for OpenAI, Voyage AI, and +Ollama embedding providers. ### Community Components -**[pgVector](../pgvector/)** — Open-source PostgreSQL extension for vector similarity search. Adds a `vector` column type with IVFFlat and HNSW indexing. pgVector is a shared dependency across the toolkit: the MCP Server uses it for semantic search, the Vectorizer stores embeddings in pgVector columns, and the RAG Server queries them for retrieval. +**[pgVector](../pgvector/)** — Open-source PostgreSQL extension for vector +similarity search. Adds a `vector` column type with IVFFlat and HNSW +indexing. pgVector is a shared dependency across the toolkit: the MCP Server +uses it for semantic search, the Vectorizer stores embeddings in pgVector +columns, and the RAG Server queries them for retrieval. -## Connecting AI agents with the MCP Server +## Connecting AI Agents With the MCP Server -Rather than giving an LLM raw database credentials — uncontrolled access to every table, no guardrails on query complexity, no visibility into what the model is doing — the [MCP Server](../pgedge-postgres-mcp-server/) acts as a controlled gateway with read-only defaults, authentication, TLS, and PostgreSQL row-level security. +Rather than giving an LLM raw database credentials — uncontrolled access to +every table, no guardrails on query complexity, no visibility into what the +model is doing — the [MCP Server](../pgedge-postgres-mcp-server/) acts as a +controlled gateway with read-only defaults, authentication, TLS, and +PostgreSQL row-level security. -The MCP Server is purpose-built for PostgreSQL and ships with a **built-in PostgreSQL knowledgebase**. When an agent needs to understand a PostgreSQL feature, diagnose a configuration issue, or write correct syntax for an extension, it queries the knowledgebase directly rather than relying on the LLM's training data (which may be outdated or imprecise). +The MCP Server is purpose-built for PostgreSQL and ships with a **built-in +PostgreSQL knowledgebase**. When an agent needs to understand a PostgreSQL +feature, diagnose a configuration issue, or write correct syntax for an +extension, it queries the knowledgebase directly rather than relying on the +LLM's training data (which may be outdated or imprecise). The server offers two connection modes: -- **stdio** — For desktop clients (Claude Desktop, Cursor, VS Code Copilot, Windsurf) where the server runs as a local subprocess. -- **HTTP + SSE** — For multi-user and remote deployments where the server runs as a long-lived service. The built-in **Go CLI client** and **React web chat interface** both connect via this mode. +- **stdio** — For desktop clients (Claude Desktop, Cursor, VS Code Copilot, + Windsurf) where the server runs as a local subprocess. +- **HTTP + SSE** — For multi-user and remote deployments where the server + runs as a long-lived service. The built-in **Go CLI client** and **React + web chat interface** both connect via this mode. ```mermaid flowchart LR @@ -67,17 +113,23 @@ flowchart LR server --> KB ``` -### Security model +### Security Model AI agents never interact with your database unguarded: -- **Read-only by default** — All queries run inside read-only transactions unless explicitly configured otherwise. -- **Authentication** — Token-based and user-based authentication control which agents can connect. +- **Read-only by default** — All queries run inside read-only transactions + unless explicitly configured otherwise. +- **Authentication** — Token-based and user-based authentication control + which agents can connect. - **TLS** — All HTTP connections can be encrypted in transit. -- **Row-level security** — PostgreSQL's native RLS policies are respected, so different agents or users see only the data they're authorized to access. -- **Defined tool surface** — Agents can only perform operations the MCP Server exposes. There is no open-ended SQL access unless the administrator enables it. +- **Row-level security** — PostgreSQL's native RLS policies are respected, + so different agents or users see only the data they're authorized to + access. +- **Defined tool surface** — Agents can only perform operations the MCP + Server exposes. There is no open-ended SQL access unless the administrator + enables it. -## Building a RAG pipeline +## Building a RAG Pipeline ```mermaid flowchart TB @@ -105,14 +157,28 @@ flowchart TB ### Ingestion: Docloader → PostgreSQL -**[Docloader](../pgedge-docloader/)** reads source content and loads it into a PostgreSQL table, converting documents to Markdown with extracted metadata. Loading is transactional, and UPSERT mode allows re-running the same load to pick up changes without duplicating rows. At this stage, the data is plain text — no vectors or chunking are involved yet. +**[Docloader](../pgedge-docloader/)** reads source content and loads it into +a PostgreSQL table, converting documents to Markdown with extracted metadata. +Loading is transactional, and UPSERT mode allows re-running the same load to +pick up changes without duplicating rows. At this stage, the data is plain +text — no vectors or chunking are involved yet. ### Processing: Vectorizer + pgVector -**[Vectorizer](../pgedge-vectorizer/)** watches configured tables for changes via triggers. When rows are inserted or updated, background workers chunk the text and generate embeddings, storing the results in dedicated chunk tables using **[pgVector](../pgvector/)** column types. The chunk tables are indexed for fast similarity search. +**[Vectorizer](../pgedge-vectorizer/)** watches configured tables for changes +via triggers. When rows are inserted or updated, background workers chunk the +text and generate embeddings, storing the results in dedicated chunk tables +using **[pgVector](../pgvector/)** column types. The chunk tables are indexed +for fast similarity search. ### Serving: RAG Server -Pointing an LLM directly at chunk tables is both a security risk and a retrieval quality problem — unguarded data access, no keyword matching, duplicate passages wasting the context window, and embedding/token/LLM orchestration left to the application. +Pointing an LLM directly at chunk tables is both a security risk and a +retrieval quality problem — unguarded data access, no keyword matching, +duplicate passages wasting the context window, and embedding/token/LLM +orchestration left to the application. -**[RAG Server](../pgedge-rag-server/)** solves this by constraining access to pre-configured pipelines against specific tables (the LLM never generates SQL) and handling hybrid retrieval (vector + BM25), deduplication, and context assembly in a single layer. +**[RAG Server](../pgedge-rag-server/)** solves this by constraining access to +pre-configured pipelines against specific tables (the LLM never generates +SQL) and handling hybrid retrieval (vector + BM25), deduplication, and +context assembly in a single layer. From 487f798de56e318f700b5b0a3174a45b378902de Mon Sep 17 00:00:00 2001 From: susan-pgedge <130390403+susan-pgedge@users.noreply.github.com> Date: Fri, 20 Mar 2026 08:09:44 -0400 Subject: [PATCH 11/13] Update index.md Fix sentence fragments. --- docs/ai-toolkit/index.md | 38 +++++++++++++++++++------------------- 1 file changed, 19 insertions(+), 19 deletions(-) diff --git a/docs/ai-toolkit/index.md b/docs/ai-toolkit/index.md index 56288ba3..3f2ec91a 100644 --- a/docs/ai-toolkit/index.md +++ b/docs/ai-toolkit/index.md @@ -25,39 +25,39 @@ The pgEdge AI Toolkit consists of the following components. ### pgEdge Components -**[pgEdge Postgres MCP Server](../pgedge-postgres-mcp-server/)** — Gives AI +**[pgEdge Postgres MCP Server](../pgedge-postgres-mcp-server/)** gives AI agents secure, structured access to PostgreSQL through the Model Context -Protocol. Exposes tools for schema inspection, SQL execution, similarity +Protocol. It exposes tools for schema inspection, SQL execution, similarity search, embedding generation, query plan analysis, and knowledgebase search. -Supports Claude, OpenAI, and Ollama, with read-only defaults, +It supports Claude, OpenAI, and Ollama, with read-only defaults, authentication, TLS, and row-level security. -**[pgEdge RAG Server](../pgedge-rag-server/)** — HTTP API for -retrieval-augmented generation. Runs hybrid search combining pgVector cosine -similarity with BM25 keyword ranking, fuses results using Reciprocal Rank -Fusion, and sends assembled context to an LLM for completion. Supports -multiple independent pipelines, streaming responses, and conversation -history. +**[pgEdge RAG Server](../pgedge-rag-server/)** provides an HTTP API for +retrieval-augmented generation. It runs hybrid search combining pgVector +cosine similarity with BM25 keyword ranking, fuses results using Reciprocal +Rank Fusion, and sends assembled context to an LLM for completion. It +supports multiple independent pipelines, streaming responses, and +conversation history. -**[pgEdge Docloader](../pgedge-docloader/)** — CLI tool for loading +**[pgEdge Docloader](../pgedge-docloader/)** is a CLI tool for loading documents into PostgreSQL from local files, glob patterns, or Git -repositories. Accepts HTML, Markdown, reStructuredText, and SGML/DocBook, -converting all content to Markdown with extracted metadata. Supports +repositories. It accepts HTML, Markdown, reStructuredText, and SGML/DocBook, +converting all content to Markdown with extracted metadata. It supports transactional loading and UPSERT mode for incremental updates. -**[pgEdge Vectorizer](../pgedge-vectorizer/)** — PostgreSQL extension that -automatically chunks text and generates vector embeddings via background +**[pgEdge Vectorizer](../pgedge-vectorizer/)** is a PostgreSQL extension +that automatically chunks text and generates vector embeddings via background workers. Triggers detect inserts and updates on configured tables, with configurable chunking strategies and support for OpenAI, Voyage AI, and Ollama embedding providers. ### Community Components -**[pgVector](../pgvector/)** — Open-source PostgreSQL extension for vector -similarity search. Adds a `vector` column type with IVFFlat and HNSW -indexing. pgVector is a shared dependency across the toolkit: the MCP Server -uses it for semantic search, the Vectorizer stores embeddings in pgVector -columns, and the RAG Server queries them for retrieval. +**[pgVector](../pgvector/)** is an open-source PostgreSQL extension for +vector similarity search. It adds a `vector` column type with IVFFlat and +HNSW indexing. pgVector is a shared dependency across the toolkit: the MCP +Server uses it for semantic search, the Vectorizer stores embeddings in +pgVector columns, and the RAG Server queries them for retrieval. ## Connecting AI Agents With the MCP Server From 41aba1e12eeef79d568b63c3231d1589a713939c Mon Sep 17 00:00:00 2001 From: Antony Pegg Date: Fri, 20 Mar 2026 10:48:56 -0400 Subject: [PATCH 12/13] Remove VM / Bare Metal sub-heading from Deployment column on welcome page --- docs/index.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/index.md b/docs/index.md index 32e91e2c..dd63bdbb 100644 --- a/docs/index.md +++ b/docs/index.md @@ -364,7 +364,6 @@ hide:

      Deployment

        -
      • VM / Bare Metal
      • Control Plane Declarative API for deploying and managing PostgreSQL clusters on VMs and bare metal From 27330f1215c06f60de4b869af14a0e4ec130572b Mon Sep 17 00:00:00 2001 From: susan-pgedge <130390403+susan-pgedge@users.noreply.github.com> Date: Mon, 23 Mar 2026 10:28:34 -0400 Subject: [PATCH 13/13] Update index.md --- docs/ai-toolkit/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/ai-toolkit/index.md b/docs/ai-toolkit/index.md index 3f2ec91a..fde8c567 100644 --- a/docs/ai-toolkit/index.md +++ b/docs/ai-toolkit/index.md @@ -7,7 +7,7 @@ independent capabilities: **secure database access** and The **pgEdge Postgres MCP Server** gives AI agents autonomous, structured access to your database through the Model Context Protocol — with built-in security, PostgreSQL-specific knowledge, and support for multiple LLM -providers. It works standalone and requires no additional toolkit +providers. It works as a standalone, requiring no additional toolkit components. For applications that need to answer questions over a document corpus, the