Spedo Hybrid Embedded & Server Mode

Since version v0.61.0

Spedo supports a Hybrid Runtime Architecture: it can operate as an Embedded In-Process Engine directly within your application process (zero TCP sockets, zero serialization, nanosecond local execution), or as a Standalone Distributed Server over standard TCP/IP networking.

1. Architecture Overview

Traditional databases require running and maintaining a separate daemon, configuring network ports, managing connection pools, and paying TCP round-trip latency costs on every query.

Spedo's Hybrid Architecture eliminates this friction:

+-----------------------------------------------------------------------------------+
|                            HYBRID RUNTIME MODES                                   |
+-----------------------------------------------------------------------------------+

 1. EMBEDDED IN-PROCESS MODE (Zero-Socket / Nanosecond Latency)
    +-------------------------------------------------------------+
    | Application Process (Python / Microservice / Lambda / CLI)  |
    |                                                             |
    |   import spedo                                              |
    |   db = spedo.embedded(max_memory="128MB")                   |
    |                                                             |
    |   +-------------------------------------------------------+ |
    |   | In-Process Spedo Engine (Direct Memory Access / RAM)   | |
    |   +-------------------------------------------------------+ |
    +-------------------------------------------------------------+
               | (Optional SPDO2 Snapshot & WAL on Disk)
               v
       [ Local NVMe / SSD ]


 2. STANDALONE / DISTRIBUTED CLUSTER MODE (Standard TCP/IP)
    +-----------------------+                    +-----------------------+
    | App Pod 1 (Client)    |                    | App Pod 2 (Client)    |
    +-----------------------+                    +-----------------------+
                \                                    /
                 \ (Standard TCP / RESP on Port 6380)
                  v                                v
            +--------------------------------------------+
            | Spedo Server (High-Performance Engine)    |
            +--------------------------------------------+

2. Quickstart & Usage

A. Instant Zero-Socket In-Process Setup (spedo.embedded)

No server installation or Docker container is required. Simply install and run:

import spedo

# Initialize in-process database with a 128MB memory cap:
db = spedo.embedded(max_memory="128MB")

# Execute standard KV operations (0.001ms latency):
db.set("user:100", "Alice")
print(db.get("user:100"))  # Output: b"Alice"

# Atomic increments:
counter = db.incr("page_views")
print(counter)  # Output: 1

# Millisecond TTL & PUSH_TTL:
db.set("session:token", "xyz_auth", ex=3600)
ttl = db.ttl("session:token")
print(f"Remaining TTL: {ttl}s")

B. SQLite-Like Connection Syntax (spedo.connect)

import spedo

# 1. Pure in-memory embedded:
db_mem = spedo.connect(":memory:")

# 2. File-persisted embedded database:
db_file = spedo.connect("app_cache.spedo")
db_file.set("config:theme", "dark")
db_file.save()  # Atomically persists to disk

# 3. Remote TCP cluster (Seamless drop-in switch):
db_remote = spedo.connect("spedo.prod:6380")

3. Supported In-Process Features

The embedded engine maintains full API parity with the distributed server:

4. When to Use Embedded vs. Server Mode

5. Seamless Transition

Switching from embedded mode in development to a clustered deployment in production requires modifying only your connection string:

import os
import spedo

# Use embedded in-memory mode locally and for tests; use remote TCP server in staging/prod:
SPEDO_ENDPOINT = os.getenv("SPEDO_URL", ":memory:")
db = spedo.connect(SPEDO_ENDPOINT)

# Application logic remains 100% identical:
db.set("app:status", "ready")