Advanced AI vector database CLI for PostgreSQL - pgvector drop-in replacement with 53+ SQL functions, 39 attention mechanisms, GNN layers, hyperbolic embeddings, and self-learning capabilities
npm install @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.
``bashInstall everything (PostgreSQL + RuVector extension) in one command
npx @ruvector/postgres-cli install
That's it! The installer will:
1. Detect your system (Linux/macOS)
2. Install PostgreSQL if not present
3. Install Rust if not present (for native installs)
4. Build and install the RuVector extension
5. 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
$3
bash
Auto-detect and install via Docker
npx @ruvector/postgres-cli installOr explicitly use Docker
npx @ruvector/postgres-cli install --method dockerCustomize port and credentials
npx @ruvector/postgres-cli install \
--port 5433 \
--user myuser \
--password mypass \
--database mydb
`Direct Docker Hub Usage (without CLI):
bash
Pull and run from Docker Hub
docker run -d --name ruvector-pg \
-e POSTGRES_PASSWORD=secret \
-p 5432:5432 \
ruvnet/ruvector-postgres:latestConnect with psql
docker exec -it ruvector-pg psql -U postgres
`$3
bash
Full native installation - installs everything
npx @ruvector/postgres-cli install --method nativeSpecify PostgreSQL version
npx @ruvector/postgres-cli install --method native --pg-version 17Use existing PostgreSQL (skip PostgreSQL install)
npx @ruvector/postgres-cli install --method native --skip-postgresUse existing Rust (skip Rust install)
npx @ruvector/postgres-cli install --method native --skip-rust
`$3
bash
Install globally
npm install -g @ruvector/postgres-cliThen use anywhere
ruvector-pg install
ruvector-pg info
ruvector-pg vector create embeddings --dim 384
`Install Command Options
bash
npx @ruvector/postgres-cli install [options]Options:
-m, --method Installation method: docker, native, auto (default: "auto")
-p, --port PostgreSQL port (default: "5432")
-u, --user Database user (default: "ruvector")
--password Database password (default: "ruvector")
-d, --database Database name (default: "ruvector")
--data-dir Persistent data directory (Docker only)
--name Container name (default: "ruvector-postgres")
--version RuVector version (default: "0.2.5")
--pg-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
bash
Check installation status
npx @ruvector/postgres-cli statusStart/Stop the server
npx @ruvector/postgres-cli start
npx @ruvector/postgres-cli stopView logs
npx @ruvector/postgres-cli logs
npx @ruvector/postgres-cli logs --followConnect 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
$3
bash
Install RuVector PostgreSQL
npx @ruvector/postgres-cli installVerify installation
npx @ruvector/postgres-cli info
`$3
bash
Create table with 384-dimensional vectors and HNSW index
npx @ruvector/postgres-cli vector create documents --dim 384 --index hnsw
`$3
bash
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.jsonnpx @ruvector/postgres-cli vector insert documents --file docs.json
`$3
bash
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:
bash
Create sparse vector for text matching
npx @ruvector/postgres-cli sparse create \
--indices "[0, 5, 10]" \
--values "[0.5, 0.3, 0.2]" \
--dim 10000Compute 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:
bash
Create a graph
npx @ruvector/postgres-cli graph create taxonomyAdd 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:
bash
Enable learning for a table
npx @ruvector/postgres-cli learning enable documents \
--max-trajectories 1000 \
--num-clusters 10Record search trajectory
npx @ruvector/postgres-cli learning record \
--input "[0.1, 0.2, ...]" \
--output "[0.3, 0.4, ...]" \
--success trueGet 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
$3
bash
ruvector-pg vector create --dim --index
ruvector-pg vector insert --file data.json
ruvector-pg vector search --query "[...]" --top-k 10 --metric cosine
ruvector-pg vector distance --a "[...]" --b "[...]" --metric
ruvector-pg vector normalize --vector "[0.5, 0.3, 0.2]"
`$3
bash
ruvector-pg attention compute --query "[...]" --keys "[[...]]" --values "[[...]]" --type scaled_dot
ruvector-pg attention list-types
`$3
bash
ruvector-pg gnn create --type gcn --input-dim 384 --output-dim 128
ruvector-pg gnn forward --features features.json --edges edges.json
`$3
bash
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 "[...]"
`$3
bash
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
`$3
bash
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
`$3
bash
ruvector-pg quantization binary --vector "[...]"
ruvector-pg quantization scalar --vector "[...]"
ruvector-pg quantization compare "[0.1, 0.2, ...]"
`$3
bash
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 |
|----------|-------------|---------|
|
| 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
$3
`bash
Check if Docker is running
docker infoView container logs
npx @ruvector/postgres-cli logsRestart container
npx @ruvector/postgres-cli stop && npx @ruvector/postgres-cli start
`$3
bash
Check PostgreSQL is running
sudo systemctl status postgresqlCheck pgrx installation
cargo pgrx --versionReinstall extension
npx @ruvector/postgres-cli install --method native --skip-postgres --skip-rust
`$3
bash
Native install may require sudo for PostgreSQL operations
The installer will prompt for sudo password when needed
`Related Packages
- Rust PostgreSQL extension (v0.2.5)
- ruvector-core` - Core vector operations libraryContributing
Contributions welcome! See CONTRIBUTING.md.
License
MIT - see LICENSE