SpiceDB Documentation
Concepts
Commands

Commands

SpiceDB provides customization of runtime behavior with a variety command-line flags, but also provides multiple commands that operate SpiceDB in various modes.

Global Flags

The following are configuration flags that can be provided to every SpiceDB command.

FlagDescriptionDefault
--log-formatformat of logs ("auto", "console", "json")auto
--log-levelverbosity of logging ("trace", "debug", "info", "warn", "error")info
--otel-endpointOpenTelemetry collector endpoint - the endpoint can also be set by using environment variables
--otel-insecureconnect to the OpenTelemetry collector in plaintext
--otel-providerOpenTelemetry provider for tracing ("none", "otlphttp", "otlpgrpc")none
--otel-sample-ratioratio of traces that are sampled0.01
--otel-service-nameservice name for trace dataspicedb
--otel-trace-propagatorOpenTelemetry trace propagation format ("b3", "w3c", "ottrace")w3c
--skip-release-checkif true, skips checking for new SpiceDB releases
--termination-log-pathdefine the path to the termination log file, which contains a JSON payload to surface as reason for termination - disabled by default

Migrate

Flags

FlagDescriptionDefault
--datastore-conn-uriconnection string used by remote datastores (e.g. "postgres://postgres:password@localhost:5432/spicedb")
--datastore-credentials-provider-nameretrieve datastore credentials dynamically using one of the following options: aws-iam
--datastore-enginetype of datastore to initialize ("cockroachdb", "mysql", "postgres", "spanner")memory
--datastore-mysql-table-prefixprefix to add to the name of all SpiceDB database tables
--datastore-read-replica-conn-uricomma-separated string of replica host URIs used by Postgres and MySQL datastores for read replicas. Note: MySQL datastores can only point to a list of replica host URIs; never use a load balancer URI. Postgres datastores can point to either a list of replica host URIs or to a load balancer
--datastore-read-replica-credentials-provider-nameretrieve datastore credentials dynamically using one of the following options: aws-iam
--datastore-spanner-credentialspath to service account key credentials file with access to the cloud spanner instance (omit to use application default credentials)
--datastore-spanner-emulator-hostURI of spanner emulator instance used for development and testing (e.g. localhost:9010)
-h, --helphelp for serve
--migration-backfill-batch-sizenumber of items to migrate per iteration of a datastore backfill (default 1000)
--migration-timeoutdefines a timeout for the execution of the migration, set to 1 hour by default (default 1h0m0s)

Serve

The serve command is the primary command for running SpiceDB. This command serves the gRPC and HTTP APIs by default.

Flags

FlagDescriptionDefault
--datastore-bootstrap-filesbootstrap data yaml files to load
--datastore-bootstrap-overwriteoverwrite any existing data with bootstrap data
--datastore-bootstrap-timeoutmaximum duration before timeout for the bootstrap data to be written10s
--datastore-conn-max-lifetime-jitterwaits rand(0, jitter) after a connection is open for max lifetime to actually close the connection (default: 20% of max lifetime)
--datastore-conn-pool-read-healthcheck-intervalamount of time between connection health checks in a remote datastore's connection pool30s
--datastore-conn-pool-read-max-idletimemaximum amount of time a connection can idle in a remote datastore's connection pool30m
--datastore-conn-pool-read-max-lifetimemaximum amount of time a connection can live in a remote datastore's connection pool30m
--datastore-conn-pool-read-max-lifetime-jitterwaits rand(0, jitter) after a connection is open for max lifetime to actually close the connection (default: 20% of max lifetime)
--datastore-conn-pool-read-max-opennumber of concurrent connections open in a remote datastore's connection pool20
--datastore-conn-pool-read-min-opennumber of minimum concurrent connections open in a remote datastore's connection pool20
--datastore-conn-pool-write-healthcheck-intervalamount of time between connection health checks in a remote datastore's connection pool30s
--datastore-conn-pool-write-max-idletimemaximum amount of time a connection can idle in a remote datastore's connection pool30m
--datastore-conn-pool-write-max-lifetimemaximum amount of time a connection can live in a remote datastore's connection pool30m
--datastore-conn-pool-write-max-lifetime-jitterwaits rand(0, jitter) after a connection is open for max lifetime to actually close the connection (default: 20% of max lifetime)
--datastore-conn-pool-write-max-opennumber of concurrent connections open in a remote datastore's connection pool10
--datastore-conn-pool-write-min-opennumber of minimum concurrent connections open in a remote datastore's connection pool10
--datastore-conn-uriconnection string used by remote datastores (e.g. "postgres://postgres:password@localhost:5432/spicedb")
--datastore-connect-raterate at which new connections are allowed to the datastore (at a rate of 1/duration) (cockroach driver only)100ms
--datastore-connection-balancingenable connection balancing between database nodes (cockroach driver only)true
--datastore-enginetype of datastore to initialize ("cockroachdb", "mysql", "postgres", "spanner")memory
--datastore-follower-read-delay-durationamount of time to subtract from non-sync revision timestamps to ensure they are sufficiently in the past to enable follower reads (cockroach driver only)4.8s
--datastore-gc-intervalamount of time between passes of garbage collection (postgres driver only)3m
--datastore-gc-max-operation-timemaximum amount of time a garbage collection pass can operate before timing out (postgres driver only)1m
--datastore-gc-windowamount of time before revisions are garbage collected24h
--datastore-max-tx-retriesnumber of times a retriable transaction should be retried10
--datastore-migration-phasedatastore-specific flag that should be used to signal to a datastore which phase of a multi-step migration it is in
--datastore-mysql-table-prefixprefix to add to the name of all SpiceDB database tables
--datastore-prometheus-metricsset to false to disabled prometheus metrics from the datastoretrue
--datastore-query-userset-batch-sizenumber of usersets after which a relationship query will be split into multiple queries1024
--datastore-readonlyset the service to read-only mode
--datastore-read-replica-conn-uricomma-separated string of replica host URIs used by Postgres and MySQL datastores for read replicas. Note: MySQL datastores can only point to a list of replica host URIs; never use a load balancer URI. Postgres datastores can point to either a list of replica host URIs or to a load balancer
--datastore-read-replica-conn-pool-read-healthcheck-intervalamount of time between connection health checks in a read-only replica datastore's connection pool30s
--datastore-read-replica-conn-pool-read-max-idletimemaximum amount of time a connection can idle in a read-only replica datastore's connection pool30m
--datastore-read-replica-conn-pool-read-max-lifetimemaximum amount of time a connection can live in a read-only replica datastore's connection pool30m
--datastore-read-replica-conn-pool-read-max-lifetime-jitterwaits rand(0, jitter) after a connection is open for max lifetime to actually close the connection to a read replica(default: 20% of max lifetime)
--datastore-read-replica-conn-pool-read-max-opennumber of concurrent connections open in a read-only replica datastore's connection pool20
--datastore-read-replica-conn-pool-read-min-opennumber of minimum concurrent connections open in a read-only replica datastore's connection pool20
--datastore-request-hedgingenable request hedgingtrue
--datastore-request-hedging-initial-slow-valueinitial value to use for slow datastore requests, before statistics have been collected (default 10ms)
--datastore-request-hedging-max-requestsmaximum number of historical requests to consider1000000
--datastore-request-hedging-quantilequantile of historical datastore request time over which a request will be considered slow (default 0.95)
--datastore-revision-quantization-intervalboundary interval to which to round the quantized revision5s
--datastore-revision-quantization-max-staleness-percentpercentage of the revision quantization interval where we may opt to select a stale revision for performance reasons (default 0.1)
--datastore-spanner-credentialspath to service account key credentials file with access to the cloud spanner instance (omit to use application default credentials)
--datastore-spanner-emulator-hostURI of spanner emulator instance used for development and testing (e.g. localhost:9010)
--datastore-tx-overlap-keystatic key to touch when writing to ensure transactions overlap (only used if --datastore-tx-overlap-strategy=static is set; cockroach driver only) (default "key")
--datastore-tx-overlap-strategystrategy to generate transaction overlap keys ("request", "prefix", "static", "insecure") (cockroach driver only - see https://spicedb.dev/d/crdb-overlap (opens in a new tab) for details)"static
--datastore-watch-buffer-lengthhow many events the watch buffer should queue before forcefully disconnecting reader1024
--disable-v1-schema-apidisables the V1 schema API
--disable-version-responsedisables version response support in the API
--dispatch-cache-enabledenable cachingtrue
--dispatch-cache-max-costupper bound cache size in bytes or percent of available memory30%
--dispatch-cache-metricsenable cache metricstrue
--dispatch-cache-num-countersnumber of TinyLFU samples to track10000
--dispatch-check-permission-concurrency-limitmaximum number of parallel goroutines to create for each check request or subrequest. defaults to --dispatch-concurrency-limit
--dispatch-cluster-addraddress to listen on to serve dispatch:50053
--dispatch-cluster-cache-enabledenable cachingtrue
--dispatch-cluster-cache-max-costupper bound cache size in bytes or percent of available memory70%
--dispatch-cluster-cache-metricsenable cache metricstrue
--dispatch-cluster-cache-num-countersnumber of TinyLFU samples to track100000
--dispatch-cluster-enabledenable dispatch gRPC server
--dispatch-cluster-max-conn-agehow long a connection serving dispatch should be able to live30s
--dispatch-cluster-max-workersset the number of workers for this server (0 value means 1 worker per request)
--dispatch-cluster-networknetwork type to serve dispatch ("tcp", "tcp4", "tcp6", "unix", "unixpacket")tcp
--dispatch-cluster-tls-cert-pathlocal path to the TLS certificate used to serve dispatch
--dispatch-cluster-tls-key-pathlocal path to the TLS key used to serve dispatch
--dispatch-concurrency-limitmaximum number of parallel goroutines to create for each request or subrequest50
--dispatch-hashring-replication-factorset the replication factor of the consistent hasher used for the dispatcher100
--dispatch-hashring-spreadset the spread of the consistent hasher used for the dispatcher1
--dispatch-lookup-resources-concurrency-limitmaximum number of parallel goroutines to create for each lookup resources request or subrequest. defaults to --dispatch-concurrency-limit
--dispatch-lookup-subjects-concurrency-limitmaximum number of parallel goroutines to create for each lookup subjects request or subrequest. defaults to --dispatch-concurrency-limit
--dispatch-max-depthmaximum recursion depth for nested calls50
--dispatch-reachable-resources-concurrency-limitmaximum number of parallel goroutines to create for each reachable resources request or subrequest. defaults to --dispatch-concurrency-limit
--dispatch-upstream-addrupstream grpc address to dispatch to
--dispatch-upstream-ca-pathlocal path to the TLS CA used when connecting to the dispatch cluster
--dispatch-upstream-timeoutmaximum duration of a dispatch call an upstream cluster before it times out1m0s
--grpc-addraddress to listen on to serve gRPC:50051
--grpc-enabledenable gRPC gRPC servertrue
--grpc-max-conn-agehow long a connection serving gRPC should be able to live30s
--grpc-max-workersset the number of workers for this server (0 value means 1 worker per request)
--grpc-networknetwork type to serve gRPC ("tcp", "tcp4", "tcp6", "unix", "unixpacket")tcp
--grpc-preshared-keypreshared key(s) to require for authenticated requests
--grpc-shutdown-grace-periodamount of time after receiving sigint to continue serving
--grpc-tls-cert-pathlocal path to the TLS certificate used to serve gRPC
--grpc-tls-key-pathlocal path to the TLS key used to serve gRPC
-h, --helphelp for serve
--http-addraddress to listen on to serve gateway:8443
--http-enabledenable http gateway server
--http-tls-cert-pathlocal path to the TLS certificate used to serve gateway
--http-tls-key-pathlocal path to the TLS key used to serve gateway
--max-caveat-context-sizemaximum allowed size of request caveat context in bytes. A value of zero or less means no limit4096
--max-datastore-read-page-sizelimit on the maximum page size that we will load into memory from the datastore at one time1000
--max-relationship-context-sizemaximum allowed size of the context to be stored in a relationship25000
--metrics-addraddress to listen on to serve metrics:9090
--metrics-enabledenable http metrics servertrue
--metrics-tls-cert-pathlocal path to the TLS certificate used to serve metrics
--metrics-tls-key-pathlocal path to the TLS key used to serve metrics
--ns-cache-enabledenable cachingtrue
--ns-cache-max-costupper bound cache size in bytes or percent of available memory16MiB
--ns-cache-metricsenable cache metricstrue
--ns-cache-num-countersnumber of TinyLFU samples to track1000
--schema-prefixes-requiredrequire prefixes on all object definitions in schemas
--streaming-api-response-delay-timeoutmax duration time elapsed between messages sent by the server-side to the client (responses) before the stream times out30s
--telemetry-ca-override-path
--telemetry-endpointendpoint to which telemetry is reported, empty string to disabletelemetry.authzed.com
--telemetry-intervalapproximate period between telemetry reports, minimum
--update-relationships-max-preconditions-per-callmaximum number of preconditions allowed for WriteRelationships and DeleteRelationships calls1000
--write-relationships-max-updates-per-callmaximum number of updates allowed for WriteRelationships calls1000

Serve-Testing

Flags

© 2024 AuthZed.