diff --git a/pages/spicedb/concepts/commands.mdx b/pages/spicedb/concepts/commands.mdx index 0c507db..969c797 100644 --- a/pages/spicedb/concepts/commands.mdx +++ b/pages/spicedb/concepts/commands.mdx @@ -1,17 +1,19 @@ ## Reference: `spicedb` -A database that stores, computes, and validates application permissions +A database that stores and computes permissions ### Examples ``` - No TLS and in-memory: + No TLS and in-memory datastore: spicedb serve --grpc-preshared-key "somerandomkeyhere" - TLS and a real datastore: - spicedb serve --grpc-preshared-key "realkeyhere" --grpc-tls-cert-path path/to/tls/cert --grpc-tls-key-path path/to/tls/key \ - --http-tls-cert-path path/to/tls/cert --http-tls-key-path path/to/tls/key \ - --datastore-engine postgres --datastore-conn-uri "postgres-connection-string-here" + TLS and HTTP enabled, and a real datastore: + spicedb serve --grpc-preshared-key "realkeyhere" \ + --grpc-tls-cert-path path/to/tls/cert --grpc-tls-key-path path/to/tls/key \ + --http-enabled http-tls-cert-path path/to/tls/cert --http-tls-key-path path/to/tls/key \ + --datastore-engine postgres \ + --datastore-conn-uri "postgres-connection-string-here" ``` @@ -27,6 +29,7 @@ A database that stores, computes, and validates application permissions - [spicedb datastore](#reference-spicedb-datastore) - datastore operations - [spicedb lsp](#reference-spicedb-lsp) - serve language server protocol +- [spicedb man](#reference-spicedb-man) - Generate man page - [spicedb serve](#reference-spicedb-serve) - serve the permissions database - [spicedb serve-testing](#reference-spicedb-serve-testing) - test server with an in-memory datastore - [spicedb version](#reference-spicedb-version) - displays the version of SpiceDB @@ -47,14 +50,14 @@ Operations against the configured datastore ### Children commands - [spicedb datastore gc](#reference-spicedb-datastore-gc) - executes garbage collection -- [spicedb datastore head](#reference-spicedb-datastore-head) - compute the head database migration revision +- [spicedb datastore head](#reference-spicedb-datastore-head) - compute the head (latest) database migration revision available - [spicedb datastore migrate](#reference-spicedb-datastore-migrate) - execute datastore schema migrations - [spicedb datastore repair](#reference-spicedb-datastore-repair) - executes datastore repair ## Reference: `spicedb datastore gc` -Executes garbage collection against the datastore +Executes garbage collection against the datastore. Deletes stale relationships, expired relationships, and stale transactions. ``` spicedb datastore gc [flags] @@ -121,7 +124,7 @@ spicedb datastore gc [flags] --datastore-spanner-metrics string configure the metrics that are emitted by the Spanner datastore ("none", "native", "otel", "deprecated-prometheus") (default "otel") --datastore-spanner-min-sessions uint minimum number of sessions across all Spanner gRPC connections the client can have at a given time (default 100) --datastore-tx-overlap-key string static 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-strategy string strategy to generate transaction overlap keys ("request", "prefix", "static", "insecure") (cockroach driver only - see https://spicedb.dev/d/crdb-overlap for details)" (default "static") + --datastore-tx-overlap-strategy string strategy to generate transaction overlap keys ("request", "prefix", "static", "insecure") (cockroach driver only - see https://spicedb.dev/d/crdb-overlap for details) (default "static") --datastore-watch-buffer-length uint16 how large the watch buffer should be before blocking (default 1024) --datastore-watch-buffer-write-timeout duration how long the watch buffer should queue before forcefully disconnecting the reader (default 1s) --datastore-watch-connect-timeout duration how long the watch connection should wait before timing out (cockroachdb driver only) (default 1s) @@ -131,9 +134,10 @@ spicedb datastore gc [flags] --otel-sample-ratio float ratio of traces that are sampled (default 0.01) --otel-service-name string service name for trace data (default "spicedb") --otel-trace-propagator string OpenTelemetry trace propagation format ("b3", "w3c", "ottrace"). Add multiple propagators separated by comma. (default "w3c") - --pprof-block-profile-rate int sets the block profile sampling rate - --pprof-mutex-profile-rate int sets the mutex profile sampling rate - --termination-log-path string define the path to the termination log file, which contains a JSON payload to surface as reason for termination - disabled by default + --pprof-block-profile-rate int sets the block profile sampling rate (between 0 and 1) + --pprof-mutex-profile-rate int sets the mutex profile sampling rate (between 0 and 1) + --termination-log-path string local path to the termination log file, which contains a JSON payload to surface as reason for termination + --write-conn-acquisition-timeout duration amount of time to wait for a connection to become available, otherwise causes resource exhausted errors (0 means wait indefinitely) (default 30ms) ``` ### Options Inherited From Parent Flags @@ -148,7 +152,7 @@ spicedb datastore gc [flags] ## Reference: `spicedb datastore head` -compute the head database migration revision +compute the head (latest) database migration revision available ``` spicedb datastore head [flags] @@ -164,9 +168,9 @@ spicedb datastore head [flags] --otel-sample-ratio float ratio of traces that are sampled (default 0.01) --otel-service-name string service name for trace data (default "spicedb") --otel-trace-propagator string OpenTelemetry trace propagation format ("b3", "w3c", "ottrace"). Add multiple propagators separated by comma. (default "w3c") - --pprof-block-profile-rate int sets the block profile sampling rate - --pprof-mutex-profile-rate int sets the mutex profile sampling rate - --termination-log-path string define the path to the termination log file, which contains a JSON payload to surface as reason for termination - disabled by default + --pprof-block-profile-rate int sets the block profile sampling rate (between 0 and 1) + --pprof-mutex-profile-rate int sets the mutex profile sampling rate (between 0 and 1) + --termination-log-path string local path to the termination log file, which contains a JSON payload to surface as reason for termination ``` ### Options Inherited From Parent Flags @@ -205,9 +209,9 @@ spicedb datastore migrate [revision] [flags] --otel-sample-ratio float ratio of traces that are sampled (default 0.01) --otel-service-name string service name for trace data (default "spicedb") --otel-trace-propagator string OpenTelemetry trace propagation format ("b3", "w3c", "ottrace"). Add multiple propagators separated by comma. (default "w3c") - --pprof-block-profile-rate int sets the block profile sampling rate - --pprof-mutex-profile-rate int sets the mutex profile sampling rate - --termination-log-path string define the path to the termination log file, which contains a JSON payload to surface as reason for termination - disabled by default + --pprof-block-profile-rate int sets the block profile sampling rate (between 0 and 1) + --pprof-mutex-profile-rate int sets the mutex profile sampling rate (between 0 and 1) + --termination-log-path string local path to the termination log file, which contains a JSON payload to surface as reason for termination ``` ### Options Inherited From Parent Flags @@ -289,7 +293,7 @@ spicedb datastore repair [flags] --datastore-spanner-metrics string configure the metrics that are emitted by the Spanner datastore ("none", "native", "otel", "deprecated-prometheus") (default "otel") --datastore-spanner-min-sessions uint minimum number of sessions across all Spanner gRPC connections the client can have at a given time (default 100) --datastore-tx-overlap-key string static 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-strategy string strategy to generate transaction overlap keys ("request", "prefix", "static", "insecure") (cockroach driver only - see https://spicedb.dev/d/crdb-overlap for details)" (default "static") + --datastore-tx-overlap-strategy string strategy to generate transaction overlap keys ("request", "prefix", "static", "insecure") (cockroach driver only - see https://spicedb.dev/d/crdb-overlap for details) (default "static") --datastore-watch-buffer-length uint16 how large the watch buffer should be before blocking (default 1024) --datastore-watch-buffer-write-timeout duration how long the watch buffer should queue before forcefully disconnecting the reader (default 1s) --datastore-watch-connect-timeout duration how long the watch connection should wait before timing out (cockroachdb driver only) (default 1s) @@ -299,9 +303,10 @@ spicedb datastore repair [flags] --otel-sample-ratio float ratio of traces that are sampled (default 0.01) --otel-service-name string service name for trace data (default "spicedb") --otel-trace-propagator string OpenTelemetry trace propagation format ("b3", "w3c", "ottrace"). Add multiple propagators separated by comma. (default "w3c") - --pprof-block-profile-rate int sets the block profile sampling rate - --pprof-mutex-profile-rate int sets the mutex profile sampling rate - --termination-log-path string define the path to the termination log file, which contains a JSON payload to surface as reason for termination - disabled by default + --pprof-block-profile-rate int sets the block profile sampling rate (between 0 and 1) + --pprof-mutex-profile-rate int sets the mutex profile sampling rate (between 0 and 1) + --termination-log-path string local path to the termination log file, which contains a JSON payload to surface as reason for termination + --write-conn-acquisition-timeout duration amount of time to wait for a connection to become available, otherwise causes resource exhausted errors (0 means wait indefinitely) (default 30ms) ``` ### Options Inherited From Parent Flags @@ -339,9 +344,34 @@ spicedb lsp [flags] +## Reference: `spicedb man` + +Generate a man page for SpiceDB. + The output can be redirected to a file and installed to the system: +``` + spicedb man > spicedb.1 + sudo mv spicedb.1 /usr/share/man/man1/ + sudo mandb # Update man page database +``` + + +``` +spicedb man +``` + +### Options Inherited From Parent Flags + +``` + --log-format string format of logs ("auto", "console", "json") (default "auto") + --log-level string verbosity of logging ("trace", "debug", "info", "warn", "error") (default "info") + --skip-release-check if true, skips checking for new SpiceDB releases +``` + + + ## Reference: `spicedb serve` -A database that stores, computes, and validates application permissions +start a SpiceDB server ``` spicedb serve [flags] @@ -350,13 +380,15 @@ spicedb serve [flags] ### Examples ``` - No TLS and in-memory: + No TLS and in-memory datastore: spicedb serve --grpc-preshared-key "somerandomkeyhere" - TLS and a real datastore: - spicedb serve --grpc-preshared-key "realkeyhere" --grpc-tls-cert-path path/to/tls/cert --grpc-tls-key-path path/to/tls/key \ - --http-tls-cert-path path/to/tls/cert --http-tls-key-path path/to/tls/key \ - --datastore-engine postgres --datastore-conn-uri "postgres-connection-string-here" + TLS and HTTP enabled, and a real datastore: + spicedb serve --grpc-preshared-key "realkeyhere" \ + --grpc-tls-cert-path path/to/tls/cert --grpc-tls-key-path path/to/tls/key \ + --http-enabled http-tls-cert-path path/to/tls/cert --http-tls-key-path path/to/tls/key \ + --datastore-engine postgres \ + --datastore-conn-uri "postgres-connection-string-here" ``` @@ -422,7 +454,7 @@ spicedb serve [flags] --datastore-spanner-metrics string configure the metrics that are emitted by the Spanner datastore ("none", "native", "otel", "deprecated-prometheus") (default "otel") --datastore-spanner-min-sessions uint minimum number of sessions across all Spanner gRPC connections the client can have at a given time (default 100) --datastore-tx-overlap-key string static 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-strategy string strategy to generate transaction overlap keys ("request", "prefix", "static", "insecure") (cockroach driver only - see https://spicedb.dev/d/crdb-overlap for details)" (default "static") + --datastore-tx-overlap-strategy string strategy to generate transaction overlap keys ("request", "prefix", "static", "insecure") (cockroach driver only - see https://spicedb.dev/d/crdb-overlap for details) (default "static") --datastore-watch-buffer-length uint16 how large the watch buffer should be before blocking (default 1024) --datastore-watch-buffer-write-timeout duration how long the watch buffer should queue before forcefully disconnecting the reader (default 1s) --datastore-watch-connect-timeout duration how long the watch connection should wait before timing out (cockroachdb driver only) (default 1s) @@ -430,14 +462,14 @@ spicedb serve [flags] --dispatch-cache-enabled enable caching (default true) --dispatch-cache-max-cost string upper bound cache size in bytes or percent of available memory (default "30%") --dispatch-cache-metrics enable cache metrics (default true) - --dispatch-cache-num-counters int number of TinyLFU samples to track (default 10000) + --dispatch-cache-num-counters int number of TinyLFU samples to track. A higher number means more accurate eviction decisions but more memory usage (default 10000) --dispatch-check-permission-concurrency-limit uint16 maximum number of parallel goroutines to create for each check request or subrequest. defaults to --dispatch-concurrency-limit --dispatch-chunk-size uint16 maximum number of object IDs in a dispatched request (default 100) --dispatch-cluster-addr string address to listen on to serve dispatch (default ":50053") --dispatch-cluster-cache-enabled enable caching (default true) --dispatch-cluster-cache-max-cost string upper bound cache size in bytes or percent of available memory (default "70%") --dispatch-cluster-cache-metrics enable cache metrics (default true) - --dispatch-cluster-cache-num-counters int number of TinyLFU samples to track (default 100000) + --dispatch-cluster-cache-num-counters int number of TinyLFU samples to track. A higher number means more accurate eviction decisions but more memory usage (default 100000) --dispatch-cluster-enabled enable dispatch gRPC server --dispatch-cluster-max-conn-age duration how long a connection serving dispatch should be able to live (default 30s) --dispatch-cluster-max-workers uint32 set the number of workers for this server (0 value means 1 worker per request) @@ -454,27 +486,32 @@ spicedb serve [flags] --dispatch-upstream-addr string upstream grpc address to dispatch to --dispatch-upstream-ca-path string local path to the TLS CA used when connecting to the dispatch cluster --dispatch-upstream-timeout duration maximum duration of a dispatch call an upstream cluster before it times out (default 1m0s) - --enable-experimental-watchable-schema-cache enables the experimental schema cache which makes use of the Watch API for automatic updates + --enable-experimental-watchable-schema-cache enables the experimental schema cache, which uses the Watch API to keep the schema up to date --enable-performance-insight-metrics enables performance insight metrics, which are used to track the latency of API calls by shape --enable-revision-heartbeat enables support for revision heartbeat, used to create a synthetic revision on an interval defined by the quantization window (postgres only) (default true) --experimental-dispatch-secondary-maximum-primary-hedging-delays stringToString maximum number of hedging delays to use for each request type to delay the primary request. default is 5ms (default []) --experimental-dispatch-secondary-upstream-addrs stringToString secondary upstream addresses for dispatches, each with a name (default []) --experimental-dispatch-secondary-upstream-exprs stringToString map from request type to its associated CEL expression, which returns the secondary upstream(s) to be used for the request (default []) + --experimental-lookup-resources-version lr3 if non-empty, the version of the experimental lookup resources API to use: lr3 or empty --grpc-addr string address to listen on to serve gRPC (default ":50051") --grpc-enabled enable gRPC gRPC server (default true) - --grpc-log-requests-enabled logs API request payloads - --grpc-log-responses-enabled logs API response payloads + --grpc-log-requests-enabled enable logging of API request payloads + --grpc-log-responses-enabled enable logging of API response payloads --grpc-max-conn-age duration how long a connection serving gRPC should be able to live (default 30s) --grpc-max-workers uint32 set the number of workers for this server (0 value means 1 worker per request) --grpc-network string network type to serve gRPC ("tcp", "tcp4", "tcp6", "unix", "unixpacket") (default "tcp") - --grpc-preshared-key strings preshared key(s) to require for authenticated requests + --grpc-preshared-key strings (required) preshared key(s) that must be provided by clients to authenticate requests --grpc-shutdown-grace-period duration amount of time after receiving sigint to continue serving --grpc-tls-cert-path string local path to the TLS certificate used to serve gRPC --grpc-tls-key-path string local path to the TLS key used to serve gRPC - --http-addr string address to listen on to serve gateway (default ":8443") - --http-enabled enable http gateway server - --http-tls-cert-path string local path to the TLS certificate used to serve gateway - --http-tls-key-path string local path to the TLS key used to serve gateway + --http-addr string address to listen on to serve proxy (default ":8443") + --http-enabled enable http proxy server + --http-tls-cert-path string local path to the TLS certificate used to serve proxy + --http-tls-key-path string local path to the TLS key used to serve proxy + --lookup-resources-chunk-cache-enabled enable caching (default true) + --lookup-resources-chunk-cache-max-cost string upper bound cache size in bytes or percent of available memory (default "50MiB") + --lookup-resources-chunk-cache-metrics enable cache metrics + --lookup-resources-chunk-cache-num-counters int number of TinyLFU samples to track. A higher number means more accurate eviction decisions but more memory usage (default 10000) --max-bulk-export-relationships-limit uint32 maximum number of relationships that can be exported in a single request (default 10000) --max-caveat-context-size int maximum allowed size of request caveat context in bytes. A value of zero or less means no limit (default 4096) --max-datastore-read-page-size uint limit on the maximum page size that we will load into memory from the datastore at one time (default 1000) @@ -486,26 +523,28 @@ spicedb serve [flags] --metrics-enabled enable http metrics server (default true) --metrics-tls-cert-path string local path to the TLS certificate used to serve metrics --metrics-tls-key-path string local path to the TLS key used to serve metrics + --mismatch-zed-token-behavior string behavior to enforce when an API call receives a zedtoken that was originally intended for a different kind of datastore. One of: full-consistency (treat as a full-consistency call, ignoring the zedtoken), min-latency (treat as a min-latency call, ignoring the zedtoken), error (return an error). defaults to full-consistency for safety. (default "full-consistency") --ns-cache-enabled enable caching (default true) --ns-cache-max-cost string upper bound cache size in bytes or percent of available memory (default "32MiB") --ns-cache-metrics enable cache metrics (default true) - --ns-cache-num-counters int number of TinyLFU samples to track (default 1000) + --ns-cache-num-counters int number of TinyLFU samples to track. A higher number means more accurate eviction decisions but more memory usage (default 1000) --otel-endpoint string OpenTelemetry collector endpoint - the endpoint can also be set by using enviroment variables --otel-insecure connect to the OpenTelemetry collector in plaintext --otel-provider string OpenTelemetry provider for tracing ("none", "otlphttp", "otlpgrpc") (default "none") --otel-sample-ratio float ratio of traces that are sampled (default 0.01) --otel-service-name string service name for trace data (default "spicedb") --otel-trace-propagator string OpenTelemetry trace propagation format ("b3", "w3c", "ottrace"). Add multiple propagators separated by comma. (default "w3c") - --pprof-block-profile-rate int sets the block profile sampling rate - --pprof-mutex-profile-rate int sets the mutex profile sampling rate + --pprof-block-profile-rate int sets the block profile sampling rate (between 0 and 1) + --pprof-mutex-profile-rate int sets the mutex profile sampling rate (between 0 and 1) --schema-prefixes-required require prefixes on all object definitions in schemas - --streaming-api-response-delay-timeout duration max duration time elapsed between messages sent by the server-side to the client (responses) before the stream times out (default 30s) + --streaming-api-response-delay-timeout duration maximum time that streaming APIs (LookupSubjects, LookupResources, ReadRelationships and ExportBulkRelationships) can be allowed to run but no response be sent to the client before the stream times out (default 30s) --telemetry-ca-override-path string path to a custom CA to use with the telemetry endpoint --telemetry-endpoint string endpoint to which telemetry is reported, empty string to disable (default "https://telemetry.authzed.com") --telemetry-interval duration approximate period between telemetry reports, minimum 1 minute (default 1h0m0s) - --termination-log-path string define the path to the termination log file, which contains a JSON payload to surface as reason for termination - disabled by default + --termination-log-path string local path to the termination log file, which contains a JSON payload to surface as reason for termination --update-relationships-max-preconditions-per-call uint16 maximum number of preconditions allowed for WriteRelationships and DeleteRelationships calls (default 1000) --watch-api-heartbeat duration heartbeat time on the watch in the API. 0 means to default to the datastore's minimum. (default 1s) + --write-conn-acquisition-timeout duration amount of time to wait for a connection to become available, otherwise causes resource exhausted errors (0 means wait indefinitely) (default 30ms) --write-relationships-max-updates-per-call uint16 maximum number of updates allowed for WriteRelationships calls (default 1000) ``` @@ -554,8 +593,8 @@ spicedb serve-testing [flags] --otel-sample-ratio float ratio of traces that are sampled (default 0.01) --otel-service-name string service name for trace data (default "spicedb") --otel-trace-propagator string OpenTelemetry trace propagation format ("b3", "w3c", "ottrace"). Add multiple propagators separated by comma. (default "w3c") - --pprof-block-profile-rate int sets the block profile sampling rate - --pprof-mutex-profile-rate int sets the mutex profile sampling rate + --pprof-block-profile-rate int sets the block profile sampling rate (between 0 and 1) + --pprof-mutex-profile-rate int sets the mutex profile sampling rate (between 0 and 1) --readonly-grpc-addr string address to listen on to serve read-only gRPC (default ":50052") --readonly-grpc-enabled enable read-only gRPC gRPC server (default true) --readonly-grpc-max-conn-age duration how long a connection serving read-only gRPC should be able to live (default 30s) @@ -567,7 +606,7 @@ spicedb serve-testing [flags] --readonly-http-enabled enable http read-only HTTP server --readonly-http-tls-cert-path string local path to the TLS certificate used to serve read-only HTTP --readonly-http-tls-key-path string local path to the TLS key used to serve read-only HTTP - --termination-log-path string define the path to the termination log file, which contains a JSON payload to surface as reason for termination - disabled by default + --termination-log-path string local path to the termination log file, which contains a JSON payload to surface as reason for termination --update-relationships-max-preconditions-per-call uint16 maximum number of preconditions allowed for WriteRelationships and DeleteRelationships calls (default 1000) --write-relationships-max-updates-per-call uint16 maximum number of updates allowed for WriteRelationships calls (default 1000) ```