Storage Backends¶

Tryx supports a 3-tier storage architecture so you can pick the right balance between simplicity, performance, and flexibility for your project.

flowchart LR
    subgraph Tryx["Tryx Rust Core"]
        Backend["Backend trait\n(SignalStore + AppSyncStore +\nProtocolStore + DeviceStore +\nMsgSecretStore)"]
    end

    SQLite["SqliteStore\n(built-in)"]
    FFI["FfiBridgeStore\n(C ABI .so/.dll)"]
    Python["PythonStore\n(async Python)"]

    Backend --> SQLite
    Backend --> FFI
    Backend --> Python

    style SQLite fill:#22c55e,color:#fff
    style FFI fill:#3b82f6,color:#fff
    style Python fill:#a855f7,color:#fff

Tier 1: SqliteStore (Default)¶

The built-in SQLite backend requires zero configuration. Just pass a file path:

from tryx.backend import SqliteStore
from tryx.client import Tryx

app = Tryx(SqliteStore("whatsapp.db"))

Internally, the Rust core opens the database with WAL mode, creates all tables automatically, and handles migrations. This is the recommended backend for development and single-instance production deployments.

Tier 2: FFI Store (Native Shared Library)¶

For maximum throughput with no Python overhead, implement a storage backend as a native shared library (.so / .dylib / .dll) that exports C-ABI entry points.

Architecture¶

sequenceDiagram
    participant Rust as Tryx Rust Core
    participant C as Native Store (.so)
    participant DB as Database (Postgres/etc)

    Rust->>C: tryx_store_connect(dsn)
    C->>DB: Open connection pool
    C-->>Rust: handle ptr

    loop Every operation
        Rust->>C: tryx_put_identity(handle, addr, key, len)
        C->>DB: INSERT INTO identities ...
        C-->>Rust: status code (0 = OK)
    end

Usage¶

Any object with lib_path and config_json attributes is detected as an FFI backend:

import json

from tryx.client import Tryx


# tryx-store-postgres exposes this interface
class PostgresStore:
    lib_path = "./libtryx_pg.so"
    config_json = json.dumps({"host": "localhost", "dbname": "tryx"})


app = Tryx(PostgresStore())

Type Safety¶

Use the FfiStoreProtocol for type checking:

from tryx.backend import FfiStoreProtocol


def create_backend() -> FfiStoreProtocol:
    return PostgresStore()  # type checker validates attributes

Required C ABI Entry Points¶

Your shared library must export these symbols:

All functions return 0 on success, non-zero on error.

Tier 3: PythonStore (Pure Python)¶

For maximum flexibility, inherit from StoreBase and implement all abstract methods using any async Python library.

Architecture¶

sequenceDiagram
    participant Rust as Tryx Rust Core (Tokio)
    participant Bridge as PythonStore Bridge
    participant GIL as Python GIL
    participant Py as Your StoreBase subclass

    Rust->>Bridge: put_identity("addr", key_bytes)
    Bridge->>GIL: Python::attach(|py| ...)
    GIL->>Py: await store.put_identity(address="addr", key=b"...")
    Py-->>GIL: None
    GIL-->>Bridge: PyObject
    Bridge-->>Rust: Ok(())

    Note over GIL: GIL is released during<br/>the Python await

Usage¶

import json
import redis.asyncio as redis
from tryx.backend import StoreBase
from tryx.client import Tryx


class RedisStore(StoreBase):
    def __init__(self, url: str = "redis://localhost"):
        self.r = redis.from_url(url)

    async def put_identity(self, address: str, key: bytes) -> None:
        await self.r.set(f"identity:{address}", key)

    async def load_identity(self, address: str) -> bytes | None:
        return await self.r.get(f"identity:{address}")

    async def delete_identity(self, address: str) -> None:
        await self.r.delete(f"identity:{address}")

    # ... implement ALL abstract methods from StoreBase ...


app = Tryx(RedisStore())

Type Checking¶

StoreBase is an ABC with @abstractmethod on every required method. If you miss any method:

• Mypy/Pyright will report an error at class definition
• Runtime will raise TypeError: Can't instantiate abstract class

class IncompleteStore(StoreBase):
    async def put_identity(self, address: str, key: bytes) -> None:
        pass

    # Missing 50+ methods → type checker error!

Performance Characteristics¶

The PythonStore bridge is designed for low overhead:

Typical overhead per call: ~2-5µs for GIL acquire/release + Python method dispatch. The actual database I/O dominates.

API Specification¶

All three tiers implement the same underlying Rust traits. Here is the complete method reference grouped by trait:

SignalStore — End-to-End Encryption¶

Handles identity keys, sessions, pre-keys, signed pre-keys, and sender keys.

AppSyncStore — App State Synchronization¶

DeviceStore — Device Persistence¶

ProtocolStore — Protocol Alignment¶

MsgSecretStore — Message Secret Persistence¶

JSON Struct Schemas¶

Complex types are passed as JSON bytes. Here are the key schemas:

AppStateSyncKey¶

{
  "key_data": [/* u8 array */],
  "fingerprint": [/* u8 array */],
  "timestamp": 1717430400
}

LidPnMappingEntry¶

{
  "lid": "100000012345678",
  "phone_number": "559980000001",
  "created_at": 1717430400,
  "updated_at": 1717430400,
  "learning_source": "usync"
}

TcTokenEntry¶

{
  "token": [/* u8 array */],
  "token_timestamp": 1717430400,
  "sender_timestamp": 1717430400
}

MsgSecretEntry¶

{
  "chat": "5599800001@s.whatsapp.net",
  "sender": "5599800002@s.whatsapp.net",
  "msg_id": "3EB0A1B2C3D4E5F6",
  "secret": [/* 32 u8 bytes */],
  "expires_at": 0,
  "message_ts": 1717430400
}

DeviceListRecord¶

{
  "user": "559980000001",
  "devices": [
    {"device_id": 0, "key_index": null},
    {"device_id": 1, "key_index": 42}
  ],
  "timestamp": 1717430400,
  "phash": "abc123",
  "raw_id": 5
}

Choosing a Backend¶