Protocol Adapters

Orbit-RS provides multiple protocol adapters enabling clients to interact with the actor system using familiar protocols. This allows existing applications to integrate with Orbit-RS without requiring significant code changes.

Overview

Protocol adapters act as translation layers between external protocols and the Orbit actor system. They provide familiar interfaces while leveraging the distributed actor model underneath for scalability, fault tolerance, and consistency.

Supported Protocols

Redis Protocol (RESP) Support

Connect to Orbit actors using any Redis client through the RESP (REdis Serialization Protocol) adapter.

Quick Start

Get Redis running in 30 seconds:

# Method 1: One-command startup (recommended)
git clone https://github.com/TuringWorks/orbit-rs.git
cd orbit-rs
cargo build --release
./start-orbit-redis.sh

# Method 2: Manual startup
# Terminal 1: Start Orbit distributed actor runtime
./target/release/orbit-server --grpc-port 50056 --dev-mode

# Terminal 2: Start Redis protocol server
./target/release/resp-server

# Terminal 3: Connect with ANY Redis client
redis-cli -h 127.0.0.1 -p 6379  # Standard Redis port

** Everything works perfectly:**

# String operations
127.0.0.1:6379> SET mykey "hello world"
OK
127.0.0.1:6379> GET mykey  
"hello world"
127.0.0.1:6379> DEL mykey
(integer) 1

# Hash operations
127.0.0.1:6379> HSET user:1 name "Alice" age "25" city "NYC"
(integer) 3
127.0.0.1:6379> HGETALL user:1
1) "name"
2) "Alice"
3) "age"
4) "25"
5) "city"
6) "NYC"

# List operations
127.0.0.1:6379> LPUSH tasks "task1" "task2"
(integer) 2
127.0.0.1:6379> LRANGE tasks 0 -1
1) "task2"
2) "task1"

# Set operations
127.0.0.1:6379> SADD tags "redis" "orbit" "distributed"
(integer) 3
127.0.0.1:6379> SMEMBERS tags
1) "redis"
2) "orbit"
3) "distributed"

# Sorted Set operations
127.0.0.1:6379> ZADD leaderboard 100 "player1" 85 "player2"
(integer) 2
127.0.0.1:6379> ZRANGE leaderboard 0 -1 WITHSCORES
1) "player2"
2) "85"
3) "player1"
4) "100"

Supported Redis Commands

** Complete Command Reference** - Detailed documentation for all 50+ commands

Key-Value Operations (15+ commands)

Hash Operations (10+ commands)

List Operations (12+ commands)

Set Operations (7+ commands)

Sorted Set Operations (8+ commands)

Pub/Sub Operations (6+ commands)

Connection Commands (5+ commands)

Server Commands (5+ commands)

Redis Extensions - Advanced Features PLANNED

Orbit-RS will extend Redis with enterprise-grade features for AI/ML, time series, and graph database workloads in future releases.

Vector Operations (VECTOR.* namespace) PLANNED

AI/ML vector search with multiple similarity metrics - Coming Soon

Similarity Metrics: COSINE, EUCLIDEAN, DOT_PRODUCT, MANHATTAN

VECTOR.ADD embeddings doc1 "0.1,0.2,0.3,0.4" title "AI Document" category "tech"
VECTOR.SEARCH embeddings "0.1,0.2,0.3,0.4" 5 METRIC COSINE THRESHOLD 0.8

RedisSearch Compatible (FT.* namespace) PLANNED

Full-text and vector search engine compatibility - Coming Soon

Time Series (TS.* namespace) PLANNED

Complete RedisTimeSeries compatibility for IoT and monitoring - Coming Soon

Aggregation Functions: AVG, SUM, MIN, MAX, COUNT, FIRST, LAST, STDDEV, VAR

TS.CREATE temperature:sensor1 RETENTION 3600000 LABELS sensor_id "001" location "office"
TS.ADD temperature:sensor1 * 23.5
TS.RANGE temperature:sensor1 - + AGGREGATION AVG 60000

Graph Database (GRAPH.* namespace) PLANNED

Cypher-like graph queries with execution planning - Coming Soon

GRAPH.QUERY social "MATCH (p:Person {name: 'Alice'}) RETURN p"
GRAPH.EXPLAIN social "MATCH (p:Person) WHERE p.age > 25 RETURN p.name"

Actor Mapping

Each Redis command family maps to corresponding Orbit actor operations:

Core Data Types

Advanced Extensions

Redis Configuration Example

[redis]
enabled = true
host = "127.0.0.1"
port = 6380
max_connections = 1000
default_ttl = 3600

[redis.actors]
key_value_actor = "KeyValueActor"
hash_actor = "HashActor"
list_actor = "ListActor"
pubsub_actor = "PubSubActor"

PostgreSQL Wire Protocol EXPERIMENTAL

Connect to Orbit actors using any PostgreSQL client. Note: This is an experimental implementation providing basic SQL parsing for actor operations.

Quick Start

Start the PostgreSQL-compatible server and connect with psql:


# Start the PostgreSQL-compatible server example
cargo run --example postgres-server

# In another terminal, connect with psql
psql -h 127.0.0.1 -p 5433 -U orbit -d actors

Essential SQL Operations for Actors

Once connected, you can immediately start working with actors using familiar SQL:

-- Create a new actor with JSON state
INSERT INTO actors (actor_id, actor_type, state) 
VALUES ('user:alice', 'UserActor', '{"name": "Alice", "email": "alice@example.com"}');

-- Query actors
SELECT * FROM actors;
SELECT actor_id, actor_type FROM actors WHERE actor_type = 'UserActor';

-- Update actor state with complex JSON
UPDATE actors 
SET state = '{"name": "Alice Johnson", "email": "alice.j@example.com", "verified": true}' 
WHERE actor_id = 'user:alice';

-- Remove actors
DELETE FROM actors WHERE actor_id = 'user:alice';

Currently Supported SQL Features

Basic SQL statements: SELECT, INSERT, UPDATE, DELETE (actor operations only) Basic SQL clauses: FROM, WHERE, SET, INTO, VALUES WHERE operators: =, !=, <> (limited conditional logic) JSON support: Basic JSON state storage and retrieval Case insensitive: Keywords work in any case combination Note: This is a basic implementation focused on actor state management, not full PostgreSQL compatibility

Vector Database Capabilities

Note: Vector database features with CREATE TABLE and vector extensions are planned for future releases. Currently, Orbit-RS PostgreSQL protocol provides full actor-based operations.

The current implementation focuses on actor state management with JSON support:

-- Current: Actor-based approach for storing vector data
INSERT INTO actors (actor_id, actor_type, state) 
VALUES ('document:ai-paper', 'DocumentActor', '{
    "title": "AI in Healthcare",
    "content": "Article about AI applications in medical field...",
    "embedding": [0.1, 0.2, 0.3, 0.4, 0.5],
    "metadata": {"category": "healthcare", "published": "2024-01-15"}
}');

-- Query documents by type
SELECT * FROM actors WHERE actor_type = 'DocumentActor';

Future Vector Support (Planned)

Upcoming releases will include full vector database capabilities:

-- Planned: Traditional table-based approach
-- Enable vector extension
CREATE EXTENSION IF NOT EXISTS vector;

-- Create table with vector embeddings
CREATE TABLE documents (
    id SERIAL PRIMARY KEY,
    title VARCHAR(255) NOT NULL,
    content TEXT,
    embedding VECTOR(768),  -- 768-dimensional vector
    metadata JSONB,
    created_at TIMESTAMP DEFAULT NOW()
);

-- Create vector indexes for similarity search
CREATE INDEX embedding_hnsw_idx 
ON documents USING hnsw (embedding) 
WITH (m = 16, ef_construction = 64);

-- Create IVFFLAT index for large datasets
CREATE INDEX embedding_ivfflat_idx
ON documents USING ivfflat (embedding)
WITH (lists = 100);

-- Insert documents with embeddings
INSERT INTO documents (title, content, embedding) VALUES 
('AI in Healthcare', 'Article about AI applications...', '[0.1, 0.2, 0.3, ...]'),
('Machine Learning Basics', 'Introduction to ML concepts...', '[0.2, 0.1, 0.4, ...]');

-- Perform vector similarity searches
SELECT title, content, embedding <-> '[0.1, 0.2, 0.3, ...]' AS distance
FROM documents 
ORDER BY distance 
LIMIT 5;

-- Hybrid search combining vector similarity and text filtering
SELECT title, content, distance
FROM (
    SELECT title, content, embedding <-> '[0.1, 0.2, ...]' AS distance
    FROM documents 
    WHERE content LIKE '%machine learning%'
    ORDER BY distance
    LIMIT 10
) subq;

Complete SQL Keyword Reference with Examples

Orbit-RS supports a comprehensive set of SQL keywords for actor operations. All examples below are tested and ready to use.

SQL Statement Keywords

INSERT - Create New Actors

Add new actors to the system with JSON state data.

-- Basic actor creation
INSERT INTO actors (actor_id, actor_type, state) 
VALUES ('user:alice', 'UserActor', '{"name": "Alice", "email": "alice@example.com"}');

-- Complex JSON state with nested objects and arrays
INSERT INTO actors (actor_id, actor_type, state) 
VALUES ('order:12345', 'OrderActor', '{
    "order_id": "12345",
    "customer": {"name": "Bob", "address": "123 Main St"},
    "items": [{"product": "laptop", "quantity": 1, "price": 999.99}],
    "status": "pending",
    "total": 999.99
}');

-- Multiple actors in one statement
INSERT INTO actors (actor_id, actor_type, state) VALUES 
    ('cache:sessions', 'CacheActor', '{"type": "redis", "ttl": 3600}'),
    ('cache:products', 'CacheActor', '{"type": "memory", "max_size": 1000}');
SELECT - Query Actor Data

Retrieve actors and their state information.

-- Retrieve all actors
SELECT * FROM actors;

-- Select specific columns
SELECT actor_id, actor_type FROM actors;

-- Filter by actor type
SELECT * FROM actors WHERE actor_type = 'UserActor';

-- Pattern matching on actor IDs
SELECT actor_id, state FROM actors WHERE actor_id LIKE 'product:%';

-- Multiple conditions
SELECT actor_id, actor_type, state 
FROM actors 
WHERE (actor_type = 'ProductActor' OR actor_type = 'UserActor') 
  AND actor_id LIKE '%user%';
UPDATE - Modify Actor State

Update existing actors with new state data.

-- Simple state update
UPDATE actors 
SET state = '{"name": "Alice Johnson", "email": "alice.johnson@example.com", "verified": true}' 
WHERE actor_id = 'user:alice';

-- Complex nested JSON update
UPDATE actors 
SET state = '{
    "name": "Premium Gaming Laptop",
    "price": 1599.99,
    "category": "electronics",
    "specs": {"cpu": "Intel i7", "ram": "32GB", "storage": "1TB SSD"},
    "tags": ["gaming", "high-performance", "portable"]
}' 
WHERE actor_id = 'product:laptop';

-- Conditional updates
UPDATE actors 
SET state = '{"status": "shipped", "tracking": "TRK123456"}' 
WHERE actor_type = 'OrderActor' AND actor_id = 'order:12345';
DELETE - Remove Actors

Remove actors from the system.

-- Delete specific actor
DELETE FROM actors WHERE actor_id = 'user:alice';

-- Delete by type
DELETE FROM actors WHERE actor_type = 'TempActor';

-- Delete with complex conditions
DELETE FROM actors 
WHERE actor_type = 'CacheActor' AND actor_id LIKE 'temp:%';

SQL Clause Keywords

FROM - Specify Data Source
-- Basic table reference
SELECT actor_id, actor_type FROM actors;

-- The 'actors' table is the primary data source for all operations
SELECT COUNT(*) as total_actors FROM actors;
WHERE - Filter Results

Supports multiple operators for flexible filtering.

-- Equality filtering
SELECT * FROM actors WHERE actor_type = 'UserActor';

-- Pattern matching
SELECT * FROM actors WHERE actor_id LIKE 'service:%';

-- Multiple conditions with AND/OR
SELECT * FROM actors 
WHERE (actor_type = 'ProductActor' OR actor_type = 'ServiceActor')
  AND actor_id NOT LIKE 'temp:%';
SET - Update Values
-- Simple value assignment
UPDATE actors SET state = '{"active": true}' WHERE actor_id = 'service:auth';

-- Complex JSON assignment
UPDATE actors SET state = '{
    "configuration": {
        "database": {"host": "localhost", "port": 5432},
        "cache": {"enabled": true, "ttl": 300},
        "features": ["auth", "logging", "metrics"]
    },
    "status": "configured"
}' WHERE actor_id = 'config:app';
INTO - Target Table Specification
-- Standard insertion syntax
INSERT INTO actors (actor_id, actor_type, state) 
VALUES ('service:payment', 'PaymentServiceActor', '{
    "provider": "stripe",
    "enabled": true,
    "supported_currencies": ["USD", "EUR", "GBP"]
}');
VALUES - Data Specification
-- Single row insertion
INSERT INTO actors (actor_id, actor_type, state) 
VALUES ('config:app', 'ConfigActor', '{"debug": true, "port": 8080}');

-- Multiple rows
INSERT INTO actors (actor_id, actor_type, state) VALUES 
    ('metric:cpu', 'MetricActor', '{"type": "gauge", "value": 45.2}'),
    ('metric:memory', 'MetricActor', '{"type": "gauge", "value": 78.5}'),
    ('metric:requests', 'MetricActor', '{"type": "counter", "value": 12450}');

WHERE Clause Operators

= (Equality)
-- Exact match
SELECT * FROM actors WHERE actor_type = 'UserActor';
SELECT * FROM actors WHERE actor_id = 'user:alice';
!= (Not Equal)
-- Exclude specific types
SELECT actor_id, actor_type FROM actors WHERE actor_type != 'TempActor';
SELECT * FROM actors WHERE actor_id != 'system:internal';
<> (Not Equal Alternative)
-- Alternative not-equal syntax
SELECT * FROM actors WHERE actor_type <> 'CacheActor';
SELECT actor_id FROM actors WHERE actor_type <> 'SystemActor';

Table Support

actors - The Primary Table

All actor operations use the actors table.

-- Table structure (conceptual)
-- actors(
--     actor_id    TEXT PRIMARY KEY,    -- Unique actor identifier  
--     actor_type  TEXT NOT NULL,        -- Type/class of the actor
--     state       JSONB NOT NULL        -- JSON state data
-- )

-- Query table information
SELECT COUNT(*) as total_actors FROM actors;
SELECT DISTINCT actor_type FROM actors;

Column Support

actor_id - Primary Identifier
-- Query by specific ID
SELECT * FROM actors WHERE actor_id = 'user:alice';

-- Pattern matching on IDs
SELECT actor_id FROM actors WHERE actor_id LIKE 'product:%';
SELECT actor_id FROM actors WHERE actor_id LIKE '%@company.com';

-- ID-based operations
DELETE FROM actors WHERE actor_id = 'temp:session:12345';
actor_type - Actor Classification
-- Filter by actor type
SELECT * FROM actors WHERE actor_type = 'UserActor';

-- Group by type
SELECT actor_type, COUNT(*) as count FROM actors GROUP BY actor_type;

-- Multiple type filtering
SELECT * FROM actors 
WHERE actor_type IN ('UserActor', 'ServiceActor', 'ProductActor');
state - JSON State Data
-- Retrieve state information
SELECT actor_id, state FROM actors WHERE actor_type = 'UserActor';

-- State-based filtering (basic pattern matching)
SELECT * FROM actors WHERE actor_id LIKE 'config:%';
* (All Columns)
-- Retrieve complete records
SELECT * FROM actors;
SELECT * FROM actors WHERE actor_type = 'ProductActor';
SELECT * FROM actors WHERE actor_id LIKE 'service:%';
Multiple Column Selection
-- Specific column combinations
SELECT actor_id, actor_type FROM actors;
SELECT actor_id, actor_type, state FROM actors WHERE actor_type = 'ConfigActor';

-- Ordered selection
SELECT actor_type, actor_id, state FROM actors ORDER BY actor_type, actor_id;

JSON State Examples

Orbit-RS provides robust JSON support for complex actor state management.

Simple JSON
-- Basic key-value pairs
INSERT INTO actors (actor_id, actor_type, state) 
VALUES ('config:app', 'ConfigActor', '{
    "debug": true,
    "port": 8080,
    "environment": "development"
}');
Nested JSON Objects
-- Complex nested structures
INSERT INTO actors (actor_id, actor_type, state) 
VALUES ('user:profile', 'UserProfileActor', '{
    "user_id": "12345",
    "profile": {
        "personal": {"name": "John Doe", "age": 30},
        "preferences": {"theme": "dark", "notifications": true}
    },
    "metadata": {
        "created_at": "2024-01-15T10:30:00Z",
        "last_login": "2024-01-20T14:45:00Z"
    }
}');
JSON Arrays
-- Arrays and collections
INSERT INTO actors (actor_id, actor_type, state) 
VALUES ('playlist:favorites', 'PlaylistActor', '{
    "name": "My Favorites",
    "songs": [
        {"title": "Song 1", "artist": "Artist A", "duration": 180},
        {"title": "Song 2", "artist": "Artist B", "duration": 240}
    ],
    "tags": ["pop", "rock", "favorites"],
    "created_by": "user:12345"
}');
JSON with Special Characters
-- Handling quotes and special characters
INSERT INTO actors (actor_id, actor_type, state) 
VALUES ('message:welcome', 'MessageActor', '{
    "content": "Welcome to \"Orbit-RS\"! It'"'"'s great to have you here.",
    "author": "System",
    "type": "welcome"
}');
Unicode and International Support
-- International characters and emoji
INSERT INTO actors (actor_id, actor_type, state) 
VALUES ('greeting:international', 'GreetingActor', '{
    "messages": {
        "english": "Hello! ",
        "spanish": "¡Hola!",
        "chinese": "",
        "japanese": "",
        "emoji": ""
    }
}');
Empty JSON Objects
-- Minimal state initialization
INSERT INTO actors (actor_id, actor_type, state) 
VALUES ('temp:placeholder', 'PlaceholderActor', '{}');

Case Sensitivity Support

SQL keywords are case-insensitive, providing flexibility in coding styles.

-- All lowercase
insert into actors (actor_id, actor_type, state) 
values ('test:lowercase', 'TestActor', '{"case": "lowercase"}');

-- All uppercase
SELECT * FROM ACTORS WHERE ACTOR_ID = 'test:lowercase';

-- Mixed case (CamelCase)
UpDaTe actors SeT state = '{"case": "mixed", "updated": true}' 
WhErE actor_id = 'test:lowercase';

-- Column names are also case-insensitive
SELECT ACTOR_ID, actor_type, State FROM actors 
WHERE actor_id = 'test:lowercase';

Edge Cases and Special Characters

Orbit-RS handles various edge cases and special characters gracefully.

Extra Whitespace
-- Handles multiple spaces and formatting
   SELECT   actor_id   ,   actor_type   
   FROM   actors   
   WHERE   actor_type   =   'TestActor'   ;
Special Characters in Identifiers
-- Email-like identifiers
INSERT INTO actors (actor_id, actor_type, state) 
VALUES ('user:john.doe@company.com', 'UserActor', '{
    "email": "john.doe@company.com",
    "domain": "company.com"
}');

-- Complex path-like identifiers
INSERT INTO actors (actor_id, actor_type, state) 
VALUES ('api:v1/users/:id/profile', 'ApiEndpointActor', '{
    "method": "GET",
    "path": "/api/v1/users/:id/profile",
    "protected": true
}');
Semicolon Handling
-- Proper query termination
SELECT actor_id FROM actors WHERE actor_id = 'user:john.doe@company.com';

Complete Workflow Examples

Real-world usage patterns combining multiple SQL operations.

Vector Database Workflow - Complete Implementation
-- 1. Enable pgvector extension
CREATE EXTENSION IF NOT EXISTS vector;

-- 2. Create documents table with vector embeddings
CREATE TABLE documents (
    id SERIAL PRIMARY KEY,
    title TEXT NOT NULL,
    content TEXT,
    category TEXT,
    embedding VECTOR(1536),  -- OpenAI ada-002 dimensions
    metadata JSONB,
    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
    updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);

-- 3. Create vector indexes for efficient similarity search
CREATE INDEX documents_embedding_ivfflat_idx 
ON documents USING ivfflat (embedding vector_cosine_ops) 
WITH (lists = 1000);

CREATE INDEX documents_embedding_hnsw_idx 
ON documents USING hnsw (embedding vector_cosine_ops) 
WITH (m = 16, ef_construction = 64);

-- 4. Insert documents with vector embeddings
INSERT INTO documents (title, content, category, embedding, metadata) VALUES 
(
    'Introduction to Machine Learning',
    'Machine learning is a subset of artificial intelligence...',
    'AI/ML',
    '[0.1, 0.2, 0.15, 0.3, 0.25, ...]',  -- 1536-dimensional vector
    '{"author": "Dr. Smith", "tags": ["machine-learning", "ai"]}'
);

-- 5. Perform vector similarity search with analytics
WITH similarity_search AS (
    SELECT 
        title,
        content,
        category,
        embedding <-> '[0.1, 0.2, 0.15, 0.3, 0.25, ...]' as l2_distance,
        1 - (embedding <=> '[0.1, 0.2, 0.15, 0.3, 0.25, ...]') as cosine_similarity,
        metadata,
        ROW_NUMBER() OVER (ORDER BY embedding <-> '[0.1, 0.2, 0.15, 0.3, 0.25, ...]') as rank
    FROM documents
    WHERE category = 'AI/ML'
),
ranked_results AS (
    SELECT *,
           NTILE(3) OVER (ORDER BY cosine_similarity DESC) as similarity_tier
    FROM similarity_search
)
SELECT title, cosine_similarity, similarity_tier, metadata->'tags' as tags
FROM ranked_results
WHERE rank <= 10;
Advanced Analytics with Window Functions
-- Complex time-series analysis with multiple window functions
WITH sales_analytics AS (
    SELECT 
        sale_date,
        product_category,
        region,
        sales_amount,
        sales_person,
        -- Running calculations
        SUM(sales_amount) OVER (
            ORDER BY sale_date 
            ROWS UNBOUNDED PRECEDING
        ) as running_total,
        -- Moving averages
        AVG(sales_amount) OVER (
            ORDER BY sale_date 
            ROWS BETWEEN 6 PRECEDING AND CURRENT ROW
        ) as moving_avg_7day,
        -- Ranking and percentiles
        RANK() OVER (
            PARTITION BY product_category 
            ORDER BY sales_amount DESC
        ) as category_rank,
        PERCENT_RANK() OVER (
            ORDER BY sales_amount
        ) as sales_percentile,
        -- Time-based comparisons
        LAG(sales_amount, 1) OVER (
            ORDER BY sale_date
        ) as previous_day_sales,
        LEAD(sales_amount, 1) OVER (
            ORDER BY sale_date
        ) as next_day_sales,
        -- First and last values in partitions
        FIRST_VALUE(sales_amount) OVER (
            PARTITION BY region 
            ORDER BY sale_date 
            ROWS UNBOUNDED PRECEDING
        ) as first_sale_in_region,
        LAST_VALUE(sales_amount) OVER (
            PARTITION BY region 
            ORDER BY sale_date 
            ROWS BETWEEN UNBOUNDED PRECEDING AND UNBOUNDED FOLLOWING
        ) as last_sale_in_region
    FROM sales_data
)
SELECT *,
       CASE 
           WHEN sales_percentile >= 0.8 THEN 'Top Performer'
           WHEN sales_percentile >= 0.6 THEN 'Above Average'
           WHEN sales_percentile >= 0.4 THEN 'Average'
           ELSE 'Below Average'
       END as performance_tier
FROM sales_analytics
ORDER BY sale_date;
Enterprise Schema Management with Permissions
-- 1. Create organizational schemas
BEGIN;

CREATE SCHEMA IF NOT EXISTS hr AUTHORIZATION hr_admin;
CREATE SCHEMA IF NOT EXISTS finance AUTHORIZATION finance_admin;
CREATE SCHEMA IF NOT EXISTS analytics AUTHORIZATION data_team;

-- 2. Create tables with proper constraints
CREATE TABLE hr.employees (
    employee_id SERIAL PRIMARY KEY,
    employee_number VARCHAR(10) UNIQUE NOT NULL,
    first_name VARCHAR(50) NOT NULL,
    last_name VARCHAR(50) NOT NULL,
    email VARCHAR(100) UNIQUE NOT NULL,
    department VARCHAR(50) NOT NULL,
    hire_date DATE NOT NULL DEFAULT CURRENT_DATE,
    salary DECIMAL(10,2) CHECK (salary > 0),
    manager_id INTEGER REFERENCES hr.employees(employee_id),
    employee_data JSONB DEFAULT '{}',
    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
    updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);

-- 3. Create indexes for performance
CREATE INDEX idx_employees_department ON hr.employees(department);
CREATE INDEX idx_employees_manager ON hr.employees(manager_id);
CREATE INDEX idx_employees_email ON hr.employees USING hash(email);
CREATE INDEX idx_employees_data ON hr.employees USING gin(employee_data);

-- 4. Set up comprehensive permissions
-- HR team permissions
GRANT USAGE ON SCHEMA hr TO hr_manager, hr_admin;
GRANT SELECT, INSERT, UPDATE ON TABLE hr.employees TO hr_admin;
GRANT SELECT ON TABLE hr.employees TO hr_manager;
GRANT USAGE ON SEQUENCE hr.employees_employee_id_seq TO hr_admin;

-- Analytics team - read-only access
GRANT USAGE ON SCHEMA hr TO analytics_team;
GRANT SELECT ON TABLE hr.employees TO analytics_team;

-- Finance team - salary access only
CREATE VIEW finance.employee_compensation AS
SELECT 
    employee_id,
    employee_number,
    first_name,
    last_name,
    department,
    salary,
    hire_date
FROM hr.employees;

GRANT SELECT ON finance.employee_compensation TO finance_team;

COMMIT;
Transaction Management with Savepoints
-- Complex transaction with multiple savepoints
BEGIN ISOLATION LEVEL READ COMMITTED;

-- Initial operations
SAVEPOINT initial_setup;

CREATE TEMPORARY TABLE batch_operations (
    operation_id SERIAL PRIMARY KEY,
    operation_type VARCHAR(50),
    target_table VARCHAR(100),
    operation_data JSONB,
    status VARCHAR(20) DEFAULT 'pending',
    created_at TIMESTAMP DEFAULT NOW()
);

-- Bulk data operations
SAVEPOINT bulk_operations;

INSERT INTO hr.employees (employee_number, first_name, last_name, email, department, salary)
SELECT 
    'EMP' || LPAD(generate_series(1001, 1100)::text, 4, '0'),
    'Employee',
    'Number ' || generate_series(1001, 1100)::text,
    'emp' || generate_series(1001, 1100) || '@company.com',
    CASE 
        WHEN generate_series(1001, 1100) % 4 = 0 THEN 'Engineering'
        WHEN generate_series(1001, 1100) % 4 = 1 THEN 'Sales'
        WHEN generate_series(1001, 1100) % 4 = 2 THEN 'Marketing'
        ELSE 'Operations'
    END,
    50000 + (generate_series(1001, 1100) * 1000);

-- Validation checkpoint
SAVEPOINT validation_point;

-- Check data integrity
DO $$
BEGIN
    IF (SELECT COUNT(*) FROM hr.employees WHERE email IS NULL OR email = '') > 0 THEN
        RAISE EXCEPTION 'Data validation failed: null or empty email addresses found';
    END IF;
    
    IF (SELECT COUNT(DISTINCT email) FROM hr.employees) != (SELECT COUNT(*) FROM hr.employees) THEN
        RAISE EXCEPTION 'Data validation failed: duplicate email addresses found';
    END IF;
END $$;

-- If validation passes, commit all changes
COMMIT;

-- Example of selective rollback (if needed):
-- ROLLBACK TO SAVEPOINT bulk_operations;  -- Keep setup, undo bulk ops
-- ROLLBACK TO SAVEPOINT initial_setup;    -- Undo everything except transaction start
-- ROLLBACK;                               -- Undo entire transaction
E-commerce Order Processing
-- Create customer
INSERT INTO actors (actor_id, actor_type, state) 
VALUES ('customer:12345', 'CustomerActor', '{
    "customer_id": "12345",
    "name": "Alice Johnson",
    "email": "alice@example.com",
    "tier": "premium"
}');

-- Create order
INSERT INTO actors (actor_id, actor_type, state) 
VALUES ('order:67890', 'OrderActor', '{
    "order_id": "67890",
    "customer_id": "12345",
    "items": [{"sku": "LAPTOP-001", "quantity": 1, "price": 1299.99}],
    "status": "pending",
    "total": 1299.99
}');

-- Update order status
UPDATE actors 
SET state = '{
    "order_id": "67890",
    "customer_id": "12345",
    "items": [{"sku": "LAPTOP-001", "quantity": 1, "price": 1299.99}],
    "status": "processing",
    "total": 1299.99,
    "processing_started": "2024-01-20T15:30:00Z"
}' 
WHERE actor_id = 'order:67890';

-- Query orders by customer
SELECT * FROM actors 
WHERE actor_type = 'OrderActor' AND actor_id LIKE 'order:%';
Service Configuration Management
-- Create service configurations
INSERT INTO actors (actor_id, actor_type, state) VALUES
    ('config:database', 'ConfigActor', '{
        "type": "postgresql",
        "host": "localhost",
        "port": 5432,
        "pool_size": 20
    }'),
    ('config:cache', 'ConfigActor', '{
        "type": "redis", 
        "host": "localhost",
        "port": 6379,
        "ttl": 3600
    }'),
    ('config:logging', 'ConfigActor', '{
        "level": "info",
        "format": "json",
        "outputs": ["stdout", "file"]
    }');

-- Query all configurations
SELECT actor_id, state FROM actors WHERE actor_type = 'ConfigActor';

-- Update specific configuration
UPDATE actors 
SET state = '{
    "level": "debug",
    "format": "json", 
    "outputs": ["stdout", "file"],
    "debug_modules": ["http", "database", "auth"]
}' 
WHERE actor_id = 'config:logging';

Planned PostgreSQL Features

Future releases will expand PostgreSQL compatibility with advanced SQL features:

Core SQL Operations (Planned)

DDL Operations (Planned)

DCL Operations (Planned)

TCL Operations (Planned)

Advanced SQL Features (Planned)

Vector Database Support (Planned)

Future Enhancement Opportunities

Potential areas for further enhancement:

Performance Optimizations

Enterprise Features

Advanced Vector Features

Extended SQL Compliance

Integration Features

Complex SQL Examples

-- Complex expressions with proper precedence
SELECT * FROM documents 
WHERE (score > 0.8 AND category = 'research') 
   OR (embedding <-> '[0.1, 0.2, ...]' < 0.5 AND published_at > '2024-01-01');

-- Function calls and arithmetic operations
SELECT 
    title,
    COALESCE(score * 100, 0) + bonus_points AS final_score,
    GREATEST(created_at, updated_at) AS last_modified
FROM documents
WHERE NOT deleted AND (category IN ('ai', 'ml', 'research'));

-- Window functions with vector similarity
SELECT 
    title,
    content,
    embedding <-> '[0.1, 0.2, ...]' AS distance,
    ROW_NUMBER() OVER (ORDER BY embedding <-> '[0.1, 0.2, ...]') AS rank,
    PERCENT_RANK() OVER (ORDER BY score DESC) AS score_percentile
FROM documents
WHERE category = 'research';

-- Common Table Expression with recursive queries
WITH RECURSIVE category_hierarchy AS (
    SELECT id, name, parent_id, 1 as level
    FROM categories 
    WHERE parent_id IS NULL
    UNION ALL
    SELECT c.id, c.name, c.parent_id, ch.level + 1
    FROM categories c
    JOIN category_hierarchy ch ON c.parent_id = ch.id
)
SELECT * FROM category_hierarchy ORDER BY level, name;

SQL Expression Parser Engine

The PostgreSQL wire protocol includes a comprehensive expression parser:

use orbit_protocols::postgres_wire::sql::parser::ExpressionParser;
use orbit_protocols::postgres_wire::sql::lexer::Lexer;

// Parse complex SQL expressions
let mut lexer = Lexer::new();
let tokens = lexer.tokenize("score * 100 + bonus > threshold AND NOT deleted")?;
let mut parser = ExpressionParser::new();
let mut pos = 0;
let expression = parser.parse_expression(&tokens, &mut pos)?;

Operator Precedence (lowest to highest)

  1. OR - Logical disjunction
  2. AND - Logical conjunction
  3. Equality - =, !=, <>, IS, IS NOT
  4. Comparison - <, <=, >, >=, LIKE, ILIKE, IN, vector operators (<->, <#>, <=>)
  5. Additive - +, -, || (concatenation)
  6. Multiplicative - *, /, %
  7. Unary - NOT, unary -, unary +
  8. Primary - Literals, identifiers, function calls, parenthesized expressions

Supported Expression Types

Model Context Protocol (MCP) EXPERIMENTAL

AI agent integration through the standardized Model Context Protocol, enabling AI systems to interact with Orbit-RS. Note: This is an experimental implementation with basic functionality.

MCP Server Setup

use orbit_protocols::mcp::{McpServer, McpConfig};

// Configure MCP server for AI agents
let mcp_config = McpConfig {
    name: "orbit-mcp-server".to_string(),
    version: "0.1.0".to_string(),
    capabilities: McpCapabilities::default()
        .with_tools()
        .with_resources()
        .with_prompts(),
};

let mcp_server = McpServer::new(mcp_config).await?;

AI Agent Capabilities

Through MCP, AI agents can:

MCP Tool Examples

{
  "tools": [
    {
      "name": "execute_sql",
      "description": "Execute SQL query against Orbit actor system",
      "input_schema": {
        "type": "object",
        "properties": {
          "query": {"type": "string"},
          "parameters": {"type": "array"}
        }
      }
    },
    {
      "name": "vector_search",
      "description": "Perform vector similarity search",
      "input_schema": {
        "type": "object",
        "properties": {
          "table": {"type": "string"},
          "vector": {"type": "array"},
          "limit": {"type": "integer"},
          "threshold": {"type": "number"}
        }
      }
    }
  ]
}

Architecture Highlights

Modular Design

Protocol Integration

Distributed Features

Configuration

Global Protocol Configuration

[protocols]

# Enable specific protocols
redis.enabled = true
postgres.enabled = true
mcp.enabled = true

# Global settings
max_connections_per_protocol = 1000
connection_timeout = "30s"
idle_timeout = "300s"

[protocols.redis]
host = "0.0.0.0"
port = 6380
default_database = 0

[protocols.postgres]
host = "0.0.0.0"
port = 5433
database = "orbit"
ssl_mode = "prefer"

[protocols.mcp]
host = "127.0.0.1"
port = 8080
capabilities = ["tools", "resources", "prompts"]

Upcoming Time Series Features

Orbit-RS will add comprehensive time-series database capabilities in Phase 12 (Q1 2025), providing compatibility with two major time-series ecosystems.

Redis Time Series Compatibility

Full RedisTimeSeries module compatibility - Detailed Documentation

Redis Time Series Key Features

Redis Time Series Example Usage

import redis
r = redis.Redis(host='localhost', port=6380)  # Orbit-RS RESP server

# Create time series with retention
r.execute_command('TS.CREATE', 'sensor:temp:001', 
                 'RETENTION', 3600000,
                 'LABELS', 'sensor_id', '001', 'type', 'temperature')

# Add readings
import time
now = int(time.time() * 1000)
r.execute_command('TS.ADD', 'sensor:temp:001', now, 23.5)
r.execute_command('TS.ADD', 'sensor:temp:001', now + 1000, 24.1)

# Query with aggregation
results = r.execute_command('TS.RANGE', 'sensor:temp:001',
                           now - 300000, now,
                           'AGGREGATION', 'AVG', 60000)
print(f"1-minute averages: {results}")

PostgreSQL TimescaleDB Compatibility

Complete TimescaleDB extension compatibility - Detailed Documentation

Key Features

Example Usage

-- Enable TimescaleDB extension
CREATE EXTENSION IF NOT EXISTS timescaledb CASCADE;

-- Create hypertable
CREATE TABLE sensor_data (
    timestamp TIMESTAMPTZ NOT NULL,
    sensor_id TEXT NOT NULL,
    temperature DOUBLE PRECISION,
    humidity DOUBLE PRECISION
);

SELECT create_hypertable('sensor_data', 'timestamp',
    chunk_time_interval => INTERVAL '1 hour');

-- Time bucket aggregation
SELECT 
    time_bucket('15 minutes', timestamp) AS bucket,
    sensor_id,
    AVG(temperature) as avg_temp,
    MAX(temperature) - MIN(temperature) as temp_range
FROM sensor_data
WHERE timestamp >= NOW() - INTERVAL '4 hours'
GROUP BY bucket, sensor_id
ORDER BY bucket DESC;

Integration Benefits

Future Protocols

REST API

HTTP/JSON interface for web applications with:

Neo4j Bolt Protocol

Graph database compatibility featuring:

Additional Protocols Under Consideration

Best Practices

Protocol Selection

  1. Redis: Ideal for caching, session storage, and pub/sub messaging
  2. PostgreSQL: Best for complex queries, ACID transactions, and vector operations
  3. MCP: Perfect for AI agent integration and programmatic access
  4. REST: Great for web applications and microservices integration

Performance Optimization

  1. Connection Pooling: Use connection pools for high-throughput scenarios
  2. Batch Operations: Group operations when possible to reduce overhead
  3. Index Strategy: Create appropriate indexes for your query patterns
  4. Monitor Metrics: Use built-in metrics to identify performance bottlenecks

Security Considerations

  1. Network Security: Use TLS for production deployments
  2. Authentication: Implement proper authentication for each protocol
  3. Authorization: Configure fine-grained access controls
  4. Audit Logging: Enable comprehensive audit trails