Skip to content

docs: enhance performance guide with additional configuration options #502

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
tstirrat15 merged 4 commits into from
Apr 8, 2026
+48 −5
Merged

docs: enhance performance guide with additional configuration options #502

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
eba05d6
docs: enhance performance guide with additional configuration options
ivanauth Jan 23, 2026
339665a
style: fix formatting in performance guide
ivanauth Jan 29, 2026
0d7f985
style: fix formatting with oxfmt after merging main
ivanauth Jan 29, 2026
3bb24fe
chore: fixup
tstirrat15 Apr 8, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 2 additions & 5 deletions app/spicedb/getting-started/installing-zed/page.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1313,7 +1313,7 @@ zed schema compile <file> [flags]
zed schema compile schema.zed 1> compiled.zed
Write to a file:
zed schema compile root.zed --out compiled.zed

```

### Options
Expand Down Expand Up @@ -1608,7 +1608,4 @@ zed version [flags]
--request-id string optional id to send along with SpiceDB requests for tracing
--skip-version-check if true, no version check is performed against the server
--token string token used to authenticate to SpiceDB
```



```
46 changes: 46 additions & 0 deletions app/spicedb/ops/performance/page.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,13 @@ import { Callout } from "nextra/components";

# Improving Performance

<Callout type="info">
SpiceDB's server-side configuration defaults favor correctness over raw speed. API requests,
however, default to `minimize_latency` consistency for read operations, favoring cache utilization
over strict freshness. The flags documented on this page allow you to further tune SpiceDB for
your specific workload.
</Callout>

## 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.
Expand Down Expand Up @@ -59,6 +66,24 @@ 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`.

### Dispatch Chunk Size

The `--dispatch-chunk-size` flag controls the maximum number of object IDs included in a single dispatched request.
This is particularly impactful for lookup operations (such as LookupResources and LookupSubjects) that need to process many objects,
or checks that need to consider a "wide arrow," where SpiceDB needs to walk a relation that has many entries in
order to resolve a check.

```sh
spicedb serve \
--dispatch-chunk-size=100
```

<Callout type="info">
Larger chunk sizes reduce dispatch overhead but increase memory usage per request. Start with the
default (100) and increase if you observe high dispatch latency with large lookup or check
operations.
</Callout>

## By enabling Materialize

[Materialize] is a separate service that allows for the precomputation of permission query results.
Expand Down Expand Up @@ -90,3 +115,24 @@ To configure the schema cache, use the following flags:
# When false: always uses JIT caching
--enable-experimental-watchable-schema-cache=false
```

## By tuning revision quantization

The `--datastore-revision-quantization-interval` and `--datastore-revision-quantization-max-staleness-percent` flags control how SpiceDB groups revisions for caching.
Increasing these values improves cache hit rates at the cost of data freshness.

See the [load testing guide](/spicedb/ops/load-testing#spicedb-quantization-performance) for details on how quantization affects performance, and the [hotspot caching blog post](https://authzed.com/blog/hotspot-caching-in-google-zanzibar-and-spicedb) for a deeper explanation.

## By tuning connection pools

For PostgreSQL, CockroachDB, and MySQL datastores, connection pool sizing significantly impacts performance under load.
Key flags include `--datastore-conn-pool-read-max-open`, `--datastore-conn-pool-write-max-open`, and the corresponding min and jitter settings.

See the [datastores reference](/spicedb/concepts/datastores) for the full list of connection pool flags and defaults, and the [best practices guide](/best-practices#tune-connections-to-datastores) for sizing recommendations.

## By tuning the transaction overlap strategy (CockroachDB only)

The `--datastore-tx-overlap-strategy` flag controls how SpiceDB handles concurrent write transactions.
CockroachDB users can trade consistency guarantees for write throughput by selecting from strategies: `static` (default), `prefix`, `request`, or `insecure`.

See the [CockroachDB datastore documentation](/spicedb/concepts/datastores#overlap-strategy) for detailed strategy descriptions and trade-offs.
Loading