Description

n8n-nodes-pgvector-advanced

Advanced PGVector nodes for n8n with full CRUD control. No more limitations of the built-in node.

View Full Documentation | Installation | Quick Start | Docker Guide

—

Install in 30 Seconds

bash <(curl -fsSL https://raw.githubusercontent.com/aaron777collins/BetterPGVectorN8N/main/install.sh)

That's it! The installer auto-detects your setup and does the right thing.

Download installer first
curl -fsSL https://raw.githubusercontent.com/aaron777collins/BetterPGVectorN8N/main/install.sh -o install.sh
chmod +x install.sh
Then pick your method:
./install.sh --standalone   # New n8n + pgvector Docker setup
./install.sh --docker       # Add to existing Docker Compose
./install.sh --direct       # Install into running container
./install.sh --npm          # Install to ~/.n8n/nodes
./install.sh --update       # Update existing installation

Update existing installation
./install.sh --update
Or run the installer again - it auto-updates on container restart
docker compose restart n8n

---

Why Use This?

| Built-in PGVector Node | This Package |
|------------------------|--------------|
| Insert only | Full CRUD (Upsert, Query, Delete, Get) |
| No stable IDs | External IDs for reliable syncing |
| Basic queries | Filters, pagination, multiple distance metrics |
| Single inserts | Batch operations (1000+ embeddings) |
| Manual schema | Auto table/index creation |
| No AI Agent tools | AI Agent Tool for RAG workflows |

---

Quick Start

1. Set Up Credentials

In n8n: Credentials → Add → Postgres

Host: your-postgres-host
Port: 5432
Database: your_db
User: your_user
Password: your_password

2. Initialize Schema

Add a PGVector Advanced node with:

• Operation: Admin
• Admin Operation: Ensure Schema
• Dimensions: 1536 (or your embedding size)

3. Store Embeddings

Operation: Upsert
Collection: my_documents
External ID: doc-123
Content: "Your document text"
Embedding: [0.1, 0.2, 0.3, ...]
Metadata: {"category": "tech", "author": "Jane"}

4. Search

Operation: Query
Collection: my_documents
Query Embedding: [0.1, 0.2, ...]
Top K: 10
Distance Metric: cosine

---

Operations

Upsert (Insert/Update)

{
  "operation": "upsert",
  "collection": "documents",
  "externalId": "doc-123",
  "content": "Document text",
  "metadata": {"category": "tech"},
  "embedding": [0.1, 0.2, ...]
}

Batch mode: Map fields from input items for bulk inserts.

Query (Similarity Search)

{
  "operation": "query",
  "collection": "documents",
  "queryEmbedding": [0.1, 0.2, ...],
  "topK": 10,
  "distanceMetric": "cosine",
  "metadataFilter": {"category": "tech"}
}

Delete

{
  "operation": "delete",
  "collection": "documents",
  "deleteBy": "externalId",
  "deleteExternalIds": "doc-1, doc-2"
}

Delete by: id, externalId, or metadata filter.

Get

{
  "operation": "get",
  "collection": "documents",
  "getBy": "externalId",
  "getExternalIds": "doc-1, doc-2"
}

Admin

| Operation | What It Does |
|-----------|--------------|
| ensureSchema | Creates table + indexes if missing |
| createIndex | Adds HNSW or IVFFlat vector index |
| dropCollection | Deletes all records in a collection |

---

Distance Metrics

| Metric | Best For |
|--------|----------|
| Cosine | Text embeddings (OpenAI, Cohere, etc.) |
| L2 | When absolute distance matters |
| Inner Product | Pre-normalized vectors |

---

Example Workflows

Semantic Search:
1. Parse documents → Generate embeddings (OpenAI) → Upsert to PGVector → Query similar

Deduplication:
1. Query existing → If similarity > threshold, skip → Else upsert

Sync from External System:
1. Use externalId to upsert → Automatically updates existing or inserts new

---

Docker Persistence (How It Works)

The installer creates a custom Dockerfile that auto-installs community nodes on startup:

n8n/
├── Dockerfile        # Extends official n8n image
└── init-nodes.sh     # Installs packages on container start

To add more packages, edit init-nodes.sh:

PACKAGES="n8n-nodes-pgvector-advanced other-package"

Then: docker compose build && docker compose up -d

---

Troubleshooting

"pgvector extension not found"

CREATE EXTENSION IF NOT EXISTS vector;

Slow queries?

• Create an HNSW index via Admin → Create Index
• Use metadata filters to reduce search space

Dimension mismatch?

• All embeddings in a collection must have the same dimensions
• Use different collections for different embedding models

---

Development

git clone https://github.com/aaron777collins/BetterPGVectorN8N.git
cd BetterPGVectorN8N
npm install
npm run build
npm test

---

AI Agent Tool

The PGVector Store Tool lets n8n AI Agents manage knowledge with natural operations:

| Operation | What it does |
|-----------|--------------|
| Remember | Store new info, update by ID or similar concept |
| Recall | Search with similarity threshold |
| Forget | Delete by exact ID |
| Forget Similar | Delete by concept (with dry-run safety) |
| Lookup | Get by exact ID |

Configuration

Each operation has n8n settings (safety/behavior) and AI parameters (data):

| n8n Config | AI Provides |
|------------|-------------|
| Collection, thresholds, ID hints | Content, IDs, queries |
| Dry run mode, result limits | Metadata filters |

Example - Remember operation:

• n8n: ID Format Hint = "meeting-YYYY-MM-DD", Auto-Generate ID = ON
• AI: content, id (optional), metadata

Example - Forget Similar operation:

• n8n: Similarity Threshold = 0.8, Dry Run = ON
• AI: concept (what to delete)

Full AI Tools Documentation →

---

MCP Server for External AI Agents

Use with Claude, GPT, or other AI agents outside n8n.

Run directly
npx n8n-nodes-pgvector-advanced
Or install globally
npm install -g n8n-nodes-pgvector-advanced
pgvector-mcp

Available tools: pgvectorupsert, pgvectorquery, pgvectordelete, pgvectorget, pgvector_admin

Set environment variables: PGHOST, PGPORT, PGDATABASE, PGUSER, PGPASSWORD

Full MCP Documentation →

---

Documentation

| Guide | Description |
|-------|-------------|
| Installation | All installation methods |
| Quick Start | Get running in 5 minutes |
| Operations | Full operations reference |
| AI Agent Tools | Use with n8n AI Agents |
| MCP Server | Use with external AI (Claude) |
| Docker Guide | Persistent Docker setup |
| Troubleshooting | Common issues & fixes |

---

License

MIT

---

Made with ❤️ for the n8n community

View on GitHub | npm | Full Docs