14 KiB
14 KiB
@ruvector/postgres-cli
The most advanced AI vector database CLI for PostgreSQL. A drop-in pgvector replacement with 53+ SQL functions, 39 attention mechanisms, GNN layers, hyperbolic embeddings, and self-learning capabilities.
Quick Start (One Command Install)
# Install everything (PostgreSQL + RuVector extension) in one command
npx @ruvector/postgres-cli install
# Or install natively without Docker
npx @ruvector/postgres-cli install --method native
That's it! The installer will:
- Detect your system (Linux/macOS)
- Install PostgreSQL if not present
- Install Rust if not present (for native installs)
- Build and install the RuVector extension
- Create a ready-to-use database
Supported Environments
| Platform | Architecture | Docker | Native | Package Manager |
|---|---|---|---|---|
| Ubuntu/Debian | x64, arm64 | ✅ | ✅ | apt |
| RHEL/CentOS/Fedora | x64, arm64 | ✅ | ✅ | dnf/yum |
| Arch Linux | x64 | ✅ | ✅ | pacman |
| macOS | Intel, Apple Silicon | ✅ | ✅ | Homebrew |
| Windows | x64 | ✅ (WSL2) | ❌ | - |
PostgreSQL Versions: 14, 15, 16, 17 (native), Docker supports all
Why RuVector?
| Feature | pgvector | RuVector |
|---|---|---|
| Vector Search | HNSW, IVFFlat | HNSW, IVFFlat |
| Distance Metrics | 3 | 8+ (including hyperbolic) |
| Attention Mechanisms | - | 39 types |
| Graph Neural Networks | - | GCN, GraphSAGE, GAT |
| Hyperbolic Embeddings | - | Poincare, Lorentz |
| Sparse Vectors / BM25 | - | Full support |
| Self-Learning | - | ReasoningBank |
| Agent Routing | - | Tiny Dancer |
Installation Options
Option 1: Docker (Fastest - Recommended)
# Auto-detect and install via Docker
npx @ruvector/postgres-cli install
# Or explicitly use Docker
npx @ruvector/postgres-cli install --method docker
# Customize port and credentials
npx @ruvector/postgres-cli install \
--port 5433 \
--user myuser \
--password mypass \
--database mydb
Direct Docker Hub Usage (without CLI):
# Pull and run from Docker Hub
docker run -d --name ruvector-pg \
-e POSTGRES_PASSWORD=secret \
-p 5432:5432 \
ruvnet/ruvector-postgres:latest
# Connect with psql
docker exec -it ruvector-pg psql -U postgres
Option 2: Native Installation (No Docker Required)
# Full native installation - installs everything
npx @ruvector/postgres-cli install --method native
# Specify PostgreSQL version
npx @ruvector/postgres-cli install --method native --pg-version 17
# Use existing PostgreSQL (skip PostgreSQL install)
npx @ruvector/postgres-cli install --method native --skip-postgres
# Use existing Rust (skip Rust install)
npx @ruvector/postgres-cli install --method native --skip-rust
Option 3: Global CLI
# Install globally
npm install -g @ruvector/postgres-cli
# Then use anywhere
ruvector-pg install
ruvector-pg info
ruvector-pg vector create embeddings --dim 384
Install Command Options
npx @ruvector/postgres-cli install [options]
Options:
-m, --method <type> Installation method: docker, native, auto (default: "auto")
-p, --port <number> PostgreSQL port (default: "5432")
-u, --user <name> Database user (default: "ruvector")
--password <pass> Database password (default: "ruvector")
-d, --database <name> Database name (default: "ruvector")
--data-dir <path> Persistent data directory (Docker only)
--name <name> Container name (default: "ruvector-postgres")
--version <version> RuVector version (default: "0.2.5")
--pg-version <version> PostgreSQL version for native (14, 15, 16, 17) (default: "16")
--skip-postgres Skip PostgreSQL installation (use existing)
--skip-rust Skip Rust installation (use existing)
Server Management
# Check installation status
npx @ruvector/postgres-cli status
# Start/Stop the server
npx @ruvector/postgres-cli start
npx @ruvector/postgres-cli stop
# View logs
npx @ruvector/postgres-cli logs
npx @ruvector/postgres-cli logs --follow
# Connect with psql
npx @ruvector/postgres-cli psql
npx @ruvector/postgres-cli psql "SELECT ruvector_version();"
# Uninstall
npx @ruvector/postgres-cli uninstall
Tutorial 1: Semantic Search in 5 Minutes
Step 1: Install & Connect
# Install RuVector PostgreSQL
npx @ruvector/postgres-cli install
# Verify installation
npx @ruvector/postgres-cli info
Step 2: Create Vector Table
# Create table with 384-dimensional vectors and HNSW index
npx @ruvector/postgres-cli vector create documents --dim 384 --index hnsw
Step 3: Insert Vectors
# Insert from JSON file
echo '[
{"vector": [0.1, 0.2, 0.3], "metadata": {"title": "AI Overview"}},
{"vector": [0.4, 0.5, 0.6], "metadata": {"title": "ML Basics"}}
]' > docs.json
npx @ruvector/postgres-cli vector insert documents --file docs.json
Step 4: Search
# Find similar documents
npx @ruvector/postgres-cli vector search documents \
--query "[0.15, 0.25, 0.35]" \
--top-k 5 \
--metric cosine
Tutorial 2: Hybrid Search with BM25
Combine semantic vectors with keyword search:
# Create sparse vector for text matching
npx @ruvector/postgres-cli sparse create \
--indices "[0, 5, 10]" \
--values "[0.5, 0.3, 0.2]" \
--dim 10000
# Compute BM25 score
npx @ruvector/postgres-cli sparse bm25 \
--query '{"indices": [1,5,10], "values": [0.8,0.5,0.3]}' \
--doc '{"indices": [1,5], "values": [2,1]}' \
--doc-len 150 \
--avg-doc-len 200
Tutorial 3: Knowledge Graph with Hyperbolic Embeddings
Perfect for hierarchical data like taxonomies:
# Create a graph
npx @ruvector/postgres-cli graph create taxonomy
# Add nodes
npx @ruvector/postgres-cli graph create-node taxonomy \
--labels "Category" \
--properties '{"name": "Science"}'
npx @ruvector/postgres-cli graph create-node taxonomy \
--labels "Category" \
--properties '{"name": "Physics"}'
# Add edge
npx @ruvector/postgres-cli graph create-edge taxonomy \
--from 1 --to 2 --type "SUBCATEGORY"
# Compute hyperbolic distance (better for hierarchies)
npx @ruvector/postgres-cli hyperbolic poincare-distance \
--a "[0.1, 0.2]" \
--b "[0.3, 0.4]" \
--curvature -1.0
Tutorial 4: Self-Learning Search
Enable the system to learn from user feedback:
# Enable learning for a table
npx @ruvector/postgres-cli learning enable documents \
--max-trajectories 1000 \
--num-clusters 10
# Record search trajectory
npx @ruvector/postgres-cli learning record \
--input "[0.1, 0.2, ...]" \
--output "[0.3, 0.4, ...]" \
--success true
# Get optimized search parameters
npx @ruvector/postgres-cli learning get-params documents \
--query "[0.15, 0.25, ...]"
# View learning statistics
npx @ruvector/postgres-cli learning stats documents
Commands Reference
Vector Operations
ruvector-pg vector create <table> --dim <n> --index <hnsw|ivfflat>
ruvector-pg vector insert <table> --file data.json
ruvector-pg vector search <table> --query "[...]" --top-k 10 --metric cosine
ruvector-pg vector distance --a "[...]" --b "[...]" --metric <cosine|l2|ip>
ruvector-pg vector normalize --vector "[0.5, 0.3, 0.2]"
Attention Mechanisms (39 types)
ruvector-pg attention compute --query "[...]" --keys "[[...]]" --values "[[...]]" --type scaled_dot
ruvector-pg attention list-types
Graph Neural Networks
ruvector-pg gnn create <name> --type gcn --input-dim 384 --output-dim 128
ruvector-pg gnn forward <layer> --features features.json --edges edges.json
Hyperbolic Geometry
ruvector-pg hyperbolic poincare-distance --a "[...]" --b "[...]"
ruvector-pg hyperbolic lorentz-distance --a "[...]" --b "[...]"
ruvector-pg hyperbolic mobius-add --a "[...]" --b "[...]"
ruvector-pg hyperbolic exp-map --base "[...]" --tangent "[...]"
ruvector-pg hyperbolic poincare-to-lorentz --vector "[...]"
Sparse Vectors & BM25
ruvector-pg sparse create --indices "[...]" --values "[...]" --dim 10000
ruvector-pg sparse bm25 --query "..." --doc "..." --doc-len 150 --avg-doc-len 200
ruvector-pg sparse distance --a "..." --b "..." --metric cosine
Agent Routing (Tiny Dancer)
ruvector-pg routing register --name "agent1" --type llm --capabilities "..." --cost 0.01 --latency 100 --quality 0.9
ruvector-pg routing route --embedding "[...]" --optimize-for balanced
ruvector-pg routing list
Quantization
ruvector-pg quantization binary --vector "[...]"
ruvector-pg quantization scalar --vector "[...]"
ruvector-pg quantization compare "[0.1, 0.2, ...]"
Benchmarking
ruvector-pg bench run --type all --size 10000 --dim 384
ruvector-pg bench report --format table
Architecture
┌─────────────────────────────────────────────────────────────────────┐
│ @ruvector/postgres-cli │
├─────────────────────────────────────────────────────────────────────┤
│ Installation Layer │
│ ├── Docker - Pull/build image, run container │
│ └── Native - Install PG + Rust + pgrx + extension │
├─────────────────────────────────────────────────────────────────────┤
│ CLI Layer (Commander.js) │
│ ├── install/status/start/stop/logs - Server management │
│ ├── vector - CRUD & search operations │
│ ├── attention - 39 attention mechanism types │
│ ├── gnn - Graph Neural Network layers │
│ ├── graph - Cypher queries & traversal │
│ ├── hyperbolic- Poincare/Lorentz embeddings │
│ ├── sparse - BM25/SPLADE scoring │
│ ├── routing - Tiny Dancer agent routing │
│ ├── learning - ReasoningBank self-learning │
│ └── bench - Performance benchmarking │
├─────────────────────────────────────────────────────────────────────┤
│ Client Layer (pg with connection pooling) │
│ ├── Connection pooling (max 10, idle timeout 30s) │
│ ├── Automatic retry (3 attempts, exponential backoff) │
│ └── SQL injection protection │
├─────────────────────────────────────────────────────────────────────┤
│ PostgreSQL Extension (ruvector-postgres 0.2.5) │
│ └── 53+ SQL functions exposed via pgrx │
└─────────────────────────────────────────────────────────────────────┘
Benchmarks
Performance measured on AMD EPYC 7763 (64 cores), 256GB RAM:
| Operation | 10K vectors | 100K vectors | 1M vectors |
|---|---|---|---|
| HNSW Build | 0.8s | 8.2s | 95s |
| HNSW Search (top-10) | 0.3ms | 0.5ms | 1.2ms |
| Cosine Distance | 0.01ms | 0.01ms | 0.01ms |
| Poincare Distance | 0.02ms | 0.02ms | 0.02ms |
| GCN Forward | 2.1ms | 18ms | 180ms |
| BM25 Score | 0.05ms | 0.08ms | 0.15ms |
Dimensions: 384 for vector ops, 128 for GNN
Environment Variables
| Variable | Description | Default |
|---|---|---|
DATABASE_URL |
PostgreSQL connection string | postgresql://localhost:5432/ruvector |
RUVECTOR_POOL_SIZE |
Connection pool size | 10 |
RUVECTOR_TIMEOUT |
Query timeout (ms) | 30000 |
RUVECTOR_RETRIES |
Max retry attempts | 3 |
Troubleshooting
Docker Issues
# Check if Docker is running
docker info
# View container logs
npx @ruvector/postgres-cli logs
# Restart container
npx @ruvector/postgres-cli stop && npx @ruvector/postgres-cli start
Native Installation Issues
# Check PostgreSQL is running
sudo systemctl status postgresql
# Check pgrx installation
cargo pgrx --version
# Reinstall extension
npx @ruvector/postgres-cli install --method native --skip-postgres --skip-rust
Permission Issues
# Native install may require sudo for PostgreSQL operations
# The installer will prompt for sudo password when needed
Related Packages
ruvector-postgres- Rust PostgreSQL extension (v0.2.5)ruvector-core- Core vector operations library
Contributing
Contributions welcome! See CONTRIBUTING.md.
License
MIT - see LICENSE