Feedback for “Schema Language”

[asaikali]

I think adding a section on Resources and Subjects giving them precise definitions with examples at the start of the doc can make it a lot easier grok and build a mental model from.

I have been trying to answer the question. How is the schema being used and what is the relationship between the schema and what gets put into the database, I wanted to know what goes into the postgres not what is shown the playground which is higher level. How is the engine executing a query for a permission check. I was not able to find any details I am looking for.

I think adding a section along the lines of "How the schema is used by SpiceDB" can be quite helpful. The section should answer the following questions.

1. What happens when a schema is written to spiceDB
2. If I change something in the schema how is versioning handled?
3. There is no version number in the schema how do I evolve the schema?
4. How is a check query executed against a schema, what SQL gets generated is it one SQL query per check or multiple? I have a mental model of how a typical SQL engine executes a query TableScan, HashJoin ... etc. What are operations that are executed during a check? Or a tuple update / insert.

Building a strong mental model of how SpiceDB works is important to building the trust to use it in an application and to fully understand the trade offs of using it.

[ecordell]

These are good questions, and we're actively working on improving docs and making these answers more discoverable. If you can remember and can share where you tried and failed to find answers, that might help us tailor the docs better?

1. What happens when a schema is written to spiceDB

The new schema is stored at a particular revision (which is returned to the client). Future requests will resolve to a revision either before or after the schema change, and either the old or new schema will be used to evaluate the request based on the revision used for the request (which is either server or user-controlled with consistency options in the API)

2. If I change something in the schema how is versioning handled?
3. There is no version number in the schema how do I evolve the schema?

It's similar to traditional RDMSs (i.e. ones without built-in online schema change tooling, which also don't have version numbers) - it's your choice as a user whether to make a change that will break on-going application requests or if you want phase the changes to ensure nothing breaks in clients. We have a blog post that talks about these strategies here: https://authzed.com/blog/online-schema-migrations

4. How is a check query executed against a schema, what SQL gets generated is it one SQL query per check or multiple?

This is a big topic because:

1. The big-picture answer is the Zanzibar architecture, which breaks queries into subproblems and distributes them across a cluster of nodes, each of which may have an answer cached in-memory or may need to reach out to the backing datastore
2. We support multiple database backends and the strategy used for each can be quite different.

Some places to get started with this are:

1. Blog post on the SpiceDB architecture: https://authzed.com/blog/spicedb-architecture
2. Presentation that walks through the original Zanzibar architecture that served as inspiration: https://authzed.com/docs/spicedb/concepts/zanzibar#papers-we-love-presentation
3. Docs on specific datastores here: https://authzed.com/docs/spicedb/concepts/datastores

[asaikali]

Here is what i have done to try and find the answers.

1. I watched all the videos on SpiceDB that I could find on YouTube, the content from the Authzed team is fantastic really great stuff. And lots of general Videos on Zanzibar and OpenFGA. I feel like I have a decent grasp of the concepts, and I am looking to understand how the implementations works.

2. I have gone through all the docs and I have mucked around quite a bit with the playground

3. I have been experimenting with the Authzed running locally on my laptop via docker compose, and peaking under the covers to the postgres database to see what gets written in the database.

4. I have been browsing through the golang source code.

There are fundamental architecture / design trade offs questions that I am trying to answer regarding how to use a system like SpiceDB in a variety of scenarios. These questions have the classic it depends on your situation answers. This is why I am trying to build a very deep understanding of how SpiceDB works under the covers, so I can do a proper analysis for the scenarios I am interested in.