Package Exports

@ruvector/postgres-cli
@ruvector/postgres-cli/dist/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@ruvector/postgres-cli) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

@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

ruvector-postgres - Rust PostgreSQL extension (v0.2.5)
ruvector-core - Core vector operations library

Contributing

Contributions welcome! See CONTRIBUTING.md.

License

MIT - see LICENSE