spicedb-embedded (Python)

Sometimes you need a simple way to run access checks without spinning up a new service. This library provides an embedded version of SpiceDB in various languages. Each implementation is based on a C-shared library (compiled from the SpiceDB source code) with a very thin FFI binding on top of it. This means that it runs the native SpiceDB code within your already-running process.

from spicedb_embedded import EmbeddedSpiceDB
from authzed.api.v1 import (
    CheckPermissionRequest,
    CheckPermissionResponse,
    Consistency,
    ObjectReference,
    Relationship,
    SubjectReference,
)

schema = """
definition user {}

definition document {
    relation reader: user
    permission read = reader
}
"""

rel = Relationship(
    resource=ObjectReference(object_type="document", object_id="readme"),
    relation="reader",
    subject=SubjectReference(
        object=ObjectReference(object_type="user", object_id="alice")
    ),
)

with EmbeddedSpiceDB.start(schema, [rel]) as spicedb:
    req = CheckPermissionRequest(
        consistency=Consistency(fully_consistent=True),
        resource=ObjectReference(object_type="document", object_id="readme"),
        permission="read",
        subject=SubjectReference(
            object=ObjectReference(object_type="user", object_id="alice")
        ),
    )
    resp = spicedb.permissions().CheckPermission(req)
    allowed = (
        resp.permissionship == CheckPermissionResponse.PERMISSIONSHIP_HAS_PERMISSION
    )

Who should consider using this?

If you want to spin up SpiceDB, but don't want the overhead of managing another service, this might be for you.

If you want an embedded server for your unit tests and don't have access to Docker / Testcontainers, this might be for you.

If you have a schema and set of permissions that are static / readonly, this might be for you.

Who should avoid using this?

If you live in a world of microservices that each need to perform permission checks, you should almost certainly spin up a centralized SpiceDB deployment.

How does storage work?

The default datastore is "memory" (memdb). If you use this datastore, keep in mind that it will reset on each app startup. This is a great option if you can easily provide your schema and relationships at runtime. This way, there are no external network calls to check relationships at runtime.

If you need a longer term storage, you can use any SpiceDB-compatible datastores.

from spicedb_embedded import EmbeddedSpiceDB, StartOptions

# Run migrations first: spicedb datastore migrate head --datastore-engine postgres --datastore-conn-uri "postgres://..."
schema = """
definition user {}

definition document {
    relation reader: user
    permission read = reader
}
"""

options = StartOptions(
    datastore="postgres",
    datastore_uri="postgres://user:pass@localhost:5432/spicedb",
)

with EmbeddedSpiceDB.start(schema, [], options=options) as spicedb:
    # Use full Permissions API (writeRelationships, checkPermission, etc.)
    pass

Running code written in Go compiled to a C-shared library within my service sounds scary

It is scary! Using a C-shared library via FFI bindings introduces memory management in languages that don't typically have to worry about it.

That being said, the SpiceDB code still runs in a Go runtime with garbage collection, which is where the vast majority of time is spent. To help mitigate some of the risk, the FFI layer is kept as straightforward as possible. protobuf is marshalled and unmarshalled at the FFI <--> language runtime boundary in a standardized way. After unmarshalling, requests are sent directly to the SpiceDB server, and responses are returned directly back to the language runtime (after marshalling).

Installation

pip install spicedb-embedded

Or from source:

cd python && pip install -e .

Prerequisites: Go 1.23+ with CGO enabled. Build the shared library first:

cd shared/c && CGO_ENABLED=1 go build -buildmode=c-shared -o libspicedb.dylib .  # macOS
cd shared/c && CGO_ENABLED=1 go build -buildmode=c-shared -o libspicedb.so .      # Linux

The library looks for libspicedb.dylib (macOS) or libspicedb.so (Linux) in SPICEDB_LIBRARY_PATH or relative to the working directory (shared/c, ../shared/c, etc.). Override with SPICEDB_LIBRARY_PATH=/path/to/shared/c.

Usage

from spicedb_embedded import EmbeddedSpiceDB
from authzed.api.v1 import (
    CheckPermissionRequest,
    CheckPermissionResponse,
    Consistency,
    ObjectReference,
    Relationship,
    SubjectReference,
)

schema = """
definition user {}

definition document {
    relation reader: user
    permission read = reader
}
"""

rel = Relationship(
    resource=ObjectReference(object_type="document", object_id="readme"),
    relation="reader",
    subject=SubjectReference(
        object=ObjectReference(object_type="user", object_id="alice")
    ),
)

with EmbeddedSpiceDB.start(schema, [rel]) as spicedb:
    stub = spicedb.permissions()
    req = CheckPermissionRequest(
        consistency=Consistency(fully_consistent=True),
        resource=ObjectReference(object_type="document", object_id="readme"),
        permission="read",
        subject=SubjectReference(
            object=ObjectReference(object_type="user", object_id="alice")
        ),
    )
    resp = stub.CheckPermission(req)
    allowed = (
        resp.permissionship == CheckPermissionResponse.PERMISSIONSHIP_HAS_PERMISSION
    )

API

• EmbeddedSpiceDB.start(options=) — Start an instance without bootstrapping schema or relationships. Supports context manager (with).
• EmbeddedSpiceDB.start(schema, relationships, options=) — Start an instance and bootstrap it with schema and optional relationships. Supports context manager (with).
• permissions() — Permissions service stub (CheckPermission, WriteRelationships, ReadRelationships, etc.).
• schema() — Schema service stub (ReadSchema, WriteSchema, ReflectSchema, etc.).
• watch() — Watch service stub for relationship changes.
• channel() — Underlying gRPC channel for custom usage.
• close() — Dispose the instance and close the channel.

Use types from authzed.api.v1 (ObjectReference, SubjectReference, Relationship, etc.).

StartOptions

from spicedb_embedded import EmbeddedSpiceDB, StartOptions

options = StartOptions(
    datastore="memory",  # or "postgres", "cockroachdb", "spanner", "mysql"
    datastore_uri="postgres://user:pass@localhost:5432/spicedb",  # required for remote
)

with EmbeddedSpiceDB.start(schema, [], options=options) as spicedb:
    ...

Metrics & Tracing

Metrics are disabled by default. Set metrics_enabled=True to turn them on.

Prometheus — exposes http://localhost:9090/metrics for scraping:

options = StartOptions(
    metrics_enabled=True,
    metrics_port=9090,
)

OpenTelemetry traces — pushes to an OTLP gRPC collector (insecure):

options = StartOptions(
    metrics_enabled=True,
    otlp_endpoint="localhost:4317",
    otlp_service_name="my-app-spicedb",  # service.name on SpiceDB's spans; default "spicedb"
)

With opentelemetry-api installed (pip install "spicedb-embedded[opentelemetry]"), every call carries the current OpenTelemetry context, so SpiceDB's spans join your trace as children of the span that made the call and follow its sampling decision. Without it, each call starts its own trace.

Both can be combined. datastore_metrics_enabled and cache_metrics_enabled default to True when metrics_enabled is set; pass False to opt out of either.