evoid-postgresql

PostgreSQL storage engine — Intent Handler system

Quick Start • Intent Handler • Config • API

Quick Start

uv add evoid-postgresql

Method 1: Intent Handler (Recommended)

from evoid_postgresql import register_handlers
from evoid.core.storage import storage_read, storage_write, storage_delete

# Register PostgreSQL as storage handler
register_handlers(url="postgresql+asyncpg://user:pass@localhost/evoid")

# Use high-level API
await storage_write("user:1", {"name": "Alice"})
user = await storage_read("user:1")
await storage_delete("user:1")

Method 2: Direct API

from evoid_postgresql import create_storage

storage = create_storage("postgresql+asyncpg://user:pass@localhost/evoid")
await storage.write("user:1", {"name": "Alice"})
user = await storage.read("user:1")

Intent Handler

evoid-postgresql registers these Intent handlers:

Configuration

TOML

[engines]
storage = "postgresql"

[engines.options.postgresql]
url = "postgresql+asyncpg://user:pass@localhost/evoid"

Python

from evoid.config import config

app = config(
    engines={
        "storage": "postgresql",
        "options": {
            "postgresql": {
                "url": "postgresql+asyncpg://prod:secret@db/evoid",
            },
        },
    },
)

API

register_handlers(url: str)

Register PostgreSQL as Intent handlers.

create_storage(url: str) -> PostgresStorage

Factory function for direct API access.

Methods

Dependencies

• evoid>=0.4.3
• sqlalchemy[asyncio]>=2.0.0
• asyncpg>=0.29.0

Optional

• evoid-di>=0.1.0 — for DI integration (auto-registered when register_handlers() is called)

DI Integration

When you call register_handlers(), PostgreSQL is auto-registered as storage.postgresql in evoid-di:

from evoid_di import di

# After register_handlers(), set up fallback chain:
di.set_fallback("storage.postgresql", ["storage.sqlite", "cache.redis"])

# Auto-fallback on failure:
storage = di.resolve_with_fallback("storage.postgresql")

Links

• EVOID Runtime
• Documentation
• Plugin Collection

License

MIT