Improving Performance

By enabling cross-node communication

SpiceDB can be deployed in a clustered configuration where multiple nodes work together to serve API requests. In such a configuration, and for the CheckPermissions API, enabling a feature called dispatch allows nodes to break down one API request into smaller "questions" and forward those to other nodes within the cluster. This helps reduce latency and improve overall performance.

How it works

Each SpiceDB node maintains an in-memory cache of permissions queries it has resolved in the past. When a new permissions query is encountered by one node, its answer may be present on another node, so SpiceDB will forward the request onward to the other node to check the shared cache.

For more details on how dispatching works, see the Consistent Hash Load Balancing for gRPC (opens in a new tab) article.

Configuration in Kubernetes environments

If using the SpiceDB Operator, dispatching is enabled by default and no additional configuration is necessary.

If not using it, you need to set the following flag:

--dispatch-upstream-addr=kubernetes:///spicedb.default:50053

where spicedb.default is the Kubernetes Service in which SpiceDB is accessible.

If you are deploying SpiceDB under Kubernetes, it is recommended to use the SpiceDB Operator, which configures dispatching automatically.

Configuration in non-Kubernetes environments

⚠️

Non-Kubernetes based dispatching relies upon DNS updates, which means it can become stale if DNS is changing. This is not recommended unless DNS updates are rare.

To enable dispatch, the following flags must be specified:

spicedb serve \
  --dispatch-cluster-enabled=true \
  --dispatch-upstream-addr=upstream-addr \
  ...

or via environment variables with the SPICEDB_ prefix:

SPICEDB_DISPATCH_CLUSTER_ENABLED=true \
SPICEDB_DISPATCH_UPSTREAM_ADDR=upstream-addr \
spicedb serve ...

The upstream-addr should be the DNS address of the load balancer at which all SpiceDB nodes are accessible at the default dispatch port of :50053.

By enabling Materialize

Materialize is a separate service that allows for the precomputation of permission query results.

If Materialize is running, SpiceDB can dispatch sub-queries to Materialize, which can significantly speed up permission checks.

By enabling the schema cache

The schema cache stores type definitions and caveat definitions to avoid repeatedly fetching schema information from the datastore.

SpiceDB offers two caching modes:

Just-In-Time (JIT) Caching: The default mode that loads definitions on-demand. Uses less memory, but it incurs a cold start penalty on first access to each definition.
Watching Cache: An experimental mode that proactively maintains an always-up-to-date cache. This mode uses more memory but avoids cold start penalties. It is recommended when there are frequent schema changes.

To configure the schema cache, use the following flags:

# Enable namespace cache (default: true)
--ns-cache-enabled=true
 
# Maximum memory (default: 32 MiB)
--ns-cache-max-cost=32MiB
 
# Enable experimental watchable schema cache (default: false)
# When true: uses watching cache if datastore supports it
# When false: always uses JIT caching
--enable-experimental-watchable-schema-cache=false

First Steps