diff --git a/docs/content/concepts.mdx b/docs/content/concepts.mdx index d790a49c2..85212a42d 100644 --- a/docs/content/concepts.mdx +++ b/docs/content/concepts.mdx @@ -624,7 +624,7 @@ For example, the following returns all the users of type `user` that have the `v }} /> -For more information, see the the [ListUsers API Reference](/api/service#Relationship%20Queries/ListUsers). +For more information, see the [ListUsers API Reference](/api/service#Relationship%20Queries/ListUsers).
diff --git a/docs/content/getting-started/perform-list-users.mdx b/docs/content/getting-started/perform-list-users.mdx index 4da4acd3d..330714183 100644 --- a/docs/content/getting-started/perform-list-users.mdx +++ b/docs/content/getting-started/perform-list-users.mdx @@ -213,7 +213,7 @@ With the tuples: | ------------------------ | -------- | ------------------------ | | group:engineering#member | viewer | document:1 | | group:product#member | viewer | document:1 | -| user:will | member | group:engineering#member | +| user:will | member | group:engineering | Then calling the List Users API for `document:1` with relation `viewer` of type `group#member` will yield the below response. Note that the `user:will` is not returned, despite being a member of `group:engineering#member` because the `user_filters` does not target the `user` type. diff --git a/docs/content/getting-started/production-best-practices.mdx b/docs/content/getting-started/production-best-practices.mdx index c98b92c39..14b7df5fe 100644 --- a/docs/content/getting-started/production-best-practices.mdx +++ b/docs/content/getting-started/production-best-practices.mdx @@ -29,7 +29,7 @@ The following list outlines best practices for running OpenFGA in a production e We recommend: -1. Turn on caching via the flag `--check-query-cache-enabled`. This will reduce latency of requests, but it will increase the staleness of OpenFGA's responses. (The TTL is configurable). +1. Turn on in-memory caching in Check API via flags. This will reduce latency of requests, but it will increase the staleness of OpenFGA's responses. Please see [Cache Expiration](../interacting/consistency.mdx#cache-expiration) for details on the flags. 2. Prefer having a small pool of servers with high capacity (memory and CPU cores) instead of a big pool of servers, to increase cache hit ratios and simplify pool management. 3. Turn on metrics collection via the flags `--metrics-enabled` and `--datastore-metrics-enabled`. This will allow you to debug issues. 4. Turn on tracing via the flag `--trace-enabled`, but set sampling ratio to a low value, for example `--trace-sample-ratio=0.3`. This will allow you to debug issues without overwhelming the tracing server. However, keep in mind that enabling tracing comes with a slight performance cost. diff --git a/docs/content/interacting/consistency.mdx b/docs/content/interacting/consistency.mdx index 9c6a40d61..f041707b9 100644 --- a/docs/content/interacting/consistency.mdx +++ b/docs/content/interacting/consistency.mdx @@ -24,9 +24,9 @@ When querying using Read or | Name | Description | |-----------------------------|---------------------------------------------------------------------------------------------------------------| | MINIMIZE_LATENCY (default) | will serve queries from the cache when possible | -| HIGHER_CONSISTENCY | will skip the cache and query the the database directly | +| HIGHER_CONSISTENCY | will skip the cache and query the database directly | -If you write a tuple and you immediately make a check on a relation affected by that tuple using `MINIMIZE_LATENCY`, the tuple change might not be taken in consideration if serves the result from the cache. +If you write a tuple and you immediately make a Check on a relation affected by that tuple using `MINIMIZE_LATENCY`, the tuple change might not be taken in consideration if serves the result from the cache. ## When to use higher consistency @@ -51,19 +51,22 @@ if (date_modified + cache_time_to_live_period > Date.now()) { ## Cache expiration - cache is disabled by default. When not enabled, all queries will have strong consistency regardless of the consistency mode specified. + caching is disabled by default. When caching is disabled, all queries will have strong consistency regardless of the consistency mode specified. When caching is enabled, the cache will be used for queries with `MINIMIZE_LATENCY` consistency mode. You can use the following parameters to configure 's cache: -| Name | Description | -|-------------------------|---------------------------------------------------------------------------------| -| check-query-cache | Enables caching (default = false) | -| check-query-cache-limit | Configures the number of items that will be kept in the cache (default = 10000) | -| check-query-cache-ttl | Specifies the time that items will be kept in the cache (default = 10s) | +| Name | Description | +|----------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| check-cache-limit | Configures the number of items that will be kept in the in-memory cache used to resolve Check queries (default = 1000) | +| check-query-cache-enabled | Enables in-memory caching of Check subproblems (default = false). For example, if you have a relation `define viewer: owner or editor`, and the query is `Check(user:anne, viewer, doc:1)`, we'll evaluate the `owner` relation and the `editor` relation and cache both results: `(user:anne, viewer, doc:1) -> allowed=true` and `(user:anne, owner, doc:1) -> allowed=true`. | +| check-query-cache-ttl | Specifies the time that items will be kept in the cache of Check subproblems (default = 10s) | +| check-iterator-cache-enabled | Enables in-memory caching of database iterators. Each iterator is the result of a database query, for example, usersets related to a specific object, or objects related to a specific user, up to a certain number of tuples per iterator (default = false) | +| check-iterator-cache-max-results | Configures the number of tuples that will be stored for each database iterator (default = 10000) | +| check-iterator-cache-ttl | Specifies the time that items will be kept in the cache of database iterators (default = 10s) | Learn how to [configure ](../getting-started/setup-openfga/configure-openfga.mdx). -Currently, the cache is used by Check and partially in ListObjects. It will be implemented it for other query endpoints in the future. +Currently, the cache is used by Check and partially in ListObjects. It will be implemented for other query endpoints in the future. ## Future work diff --git a/docs/content/modeling/migrating/overview.mdx b/docs/content/modeling/migrating/overview.mdx index 10c156199..0b0c41749 100644 --- a/docs/content/modeling/migrating/overview.mdx +++ b/docs/content/modeling/migrating/overview.mdx @@ -1,11 +1,11 @@ --- id: overview -title: 'Migrating' +title: 'Model Migrations' slug: /modeling/migrating sidebar_position: 0 --- -import { DocumentationNotice, IntroCard, CardGrid } from '@components/Docs'; +import { DocumentationNotice, ProductName, ProductNameFormat, IntroCard, CardGrid } from '@components/Docs'; @@ -19,14 +19,37 @@ This section has guides that focus on migrating models and relations. ]} /> -# Content +You can think of model migrations for in the same way as you think about relational database migrations. You can perform migrations with or without downtime for both, and for some changes, doing them without downtime is harder. + +| | Relational Databases | +|-----------------------------------------------------|-----------------------| +| Add a type | Add a table | +| Remove a type | Remove a table | +| Rename a type | Rename a table | +| Add a relation | Add a nullable column | +| Rename a relation | Rename a column | +| Delete a relation | Delete a column | + +When thinking about migrations, keep in mind that: + +- [Models are immutable](../../getting-started/immutable-models.mdx). +- The tuples that are not valid according to the specified model, are ignored when evaluating queries. + +## To add a type or relation + + 1. Add the type or relation to the authorization model, and write the model to the store. This will generate a new model ID. + 2. If you have tuples to write for the new types/relations, write them. + 3. Update the application code to start using those new types/relations. + 4. Configure the application to start using the new model ID. + +## To delete a type or relation + + 1. Delete the type or relation to the authorization model, and write the model to the store. This will generate a new model ID. + 2. Update the application code to stops using the deleted types/relations. + 3. Configure the application to start using the new model ID. + 4. Delete the tuples for the deleted type/relations. While not required, doing so can improve performance. Invalid tuples will be ignored during query evaluation, but their presence may slow down the process if they need to be retrieved. + +## To rename a type or relation + + - [This document](./migrating-relations.mdx) describes an end-to-end example for that use case. -