Feature: Additional tutorials

[cabaucom376]

Is your feature request related to a problem?

I've noticed a lack of high-quality content on best practices for architecting databases with SurrealDB. My aim is to enhance the tutorial section with more robust, real-world examples and explanations.

I believe the Namespace and Database features are under-documented and can be confusing to implement. This is particularly true for multi-tenancy, where most available content consists of vague answers from the SurrealDB team. While the core concepts are outlined, applying these concepts to a real-world database architecture raises questions on best practices.

Example of current considerations:

I'm developing a system where a User can have multiple Workspaces, each fully isolated for privacy. Users can upload these Workspaces to a central server for collaboration, with permissions defined by the owner. Here are the approaches I'm considering:

• Single Namespace/Database: All data is stored within a single Namespace and Database. While functional with appropriate schemas, this raises security concerns in a server environment, especially with deeply nested hierarchical data shared across users. Scalability also becomes a point of concern.

• Users as Namespaces, Workspaces as Databases: Each user gets a Namespace, with each Workspace stored in a separate Database. However, this approach raises several challenges:

  • How can we dynamically create new Databases, considering $param doesn’t work with DEFINE statements?
  • Should workspace metadata (like names and descriptions) be stored in a global Database?
  • How can we grant other users access to specific Workspaces without duplicating data across Namespaces?
  • What strategies avoid name conflicts across Namespaces/Databases? Would UUIDs work, and how could they be referenced globally?

• Workspaces as Namespaces, Users as Tables: In this model, Users are stored in a table, with one marked as the owner of each Workspace. But how can we dynamically create new Namespaces given the limitations of $param with DEFINE statements?

---

Describe the solution:

The solution is to create new tutorials that dive into practical use cases for SurrealDB's Namespaces and Databases. These tutorials would provide clear, step-by-step guides on implementing multi-tenancy, securing user data, and dynamically managing Databases.

One tutorial could explore how to structure a multi-tenant SaaS application where each user's data is isolated within its own Namespace and Workspace. It would cover dynamic Namespace and Database creation, managing user access permissions, and organizing global metadata efficiently.

These tutorials would give developers a concrete roadmap for applying SurrealDB's features to real-world applications, reducing confusion and enhancing confidence in building secure, scalable architectures.

---

Alternative methods:

I considered creating a YouTube tutorial series to visually demonstrate SurrealDB’s Namespaces and Databases. While this could offer a more hands-on approach, written tutorials within the documentation would be more accessible for developers who prefer detailed, text-based references for easy copy-pasting and following along at their own pace.

Contact Details

[email protected]

Is there an existing issue for this?

• I have searched the existing issues

Code of Conduct

• I agree to follow this project's Code of Conduct

[Ekwuno]

Hey @cabaucom376 thanks for opening this issue. I think the explanation given here(https://discord.com/channels/902568124350599239/1264072571188416512/1292768116417495084) covers most of the current capabilities for namespaces and how it relates to user access.

However as an action point I'll expand the Namespace & Database concept doc https://surrealdb.com/docs/surrealdb/introduction/concepts/namespace to answer some of your questions.

If I want to create a Namespace for each user, how do I handle that dynamically while avoiding conflicts with existing Namespaces

RE your above question: Think of namespaces as organisations housing databases. So you can have multiple databases under the same namespace. On the database level, you can then specify access. You can also have Namespace users(sys admins) that have access to these databases so conflict would be avoided automatically because you'd have to also specify what database you want to query against.

Can you explain more on Storing metadata? You can access this information using the INFO statement: Getting a list of all users and their permissions and all the databases within the specified namespace.

Think of it like so Root users have access to all Namespace and databases

Namespace users have access to all databases

Database user have access to their assigned database.

[cabaucom376]

Thanks @Ekwuno,

So I kind of get the idea of the hierarchy and how the two features interact, but I am struggling to understand how I can utilize the data separation that those tools provide in a collaborative environment. If I want Users to have individual Workspaces where each contains tables that are separate from another, it makes sense to me that I would achieve that via DEFINE NAMESPACE john; DEFINE DATABASE work;. This would allow for a clear separation between all users, while also keeping each workspace independent of one another. But this gives me a few questions such as:

• How do I avoid namespace name conflicts if there is already a john user?
  • Maybe allow any name locally but when connecting to a server(global or self-hosted) claim a username unique to the instance being connected to?
• How would I allow the jane user to connect and collaborate on John's work workspace since it is in an entirely separate namespace?

I did forget about the INFO and DEFINE USER statements so thank you for that, I'll have to do some more deliberation on how to use those. As far as what I meant by metadata, say that I wanted to have a description, last_modified, etc... defined for the workspace work where would that be stored and how would it be queried publicly if its contained within the john namespace? Forgive me for my ignorance but for some reason I can only see this structure for proper user data segregation.