Account structure

SurrealDB Cloud has five layers, from your company down to the data. This page shows how they fit together, who manages each one, and which layer to use when you need to keep things apart, such as production and development, two teams, or two invoices.

The layers

Each layer sits inside the one above it. The enterprise is optional, and the data lives at the bottom, in databases.

Enterprise               your company: single sign-on, verified domains, one member list (optional)
└── Organisation         members, roles, one invoice, one support plan
    ├── Instance         a running SurrealDB server, with its own size, region and version
    │   └── Namespace    a group of databases
    │       └── Database tables, records, indexes and functions
    └── Agent Memory context

An Agent Memory context belongs to an organisation in the same way as an instance, and appears on the same invoice.

Two layers of permissions

Two separate sets of permissions apply, and a role in one grants nothing in the other.

• •

  Administration decides who can run the account in Studio: deploy and delete instances, invite members, and view or change billing. Organisation roles and enterprise roles belong here.

• •

  Data access decides who can read and change data inside an instance. It is defined in each instance with DEFINE USER and DEFINE ACCESS, and applications sign in through it.

Members and roles has the full table of what each organisation role can do.

A user defined in an instance applies at one of three levels. A root user covers the whole instance, a namespace user covers every database in its namespace, and a database user covers one database. A user can only create users at its own level or below, so a namespace Owner can create namespace and database users, and a database Owner can only create database users.

Where to keep things apart

Each layer separates something different. Use the lowest layer that separates what you need, because each layer above it adds something to manage, such as another server to size or another invoice to pay.

Some common reasons to add a second instance are:

• •

  Different sizes: a small instance for development and a larger one for production, each paid for at its own size.

• •

  Analytics: heavy reporting queries use CPU and memory. On their own instance, a large report does not slow down the application.

• •

  Region or data residency: an instance runs in one region, so data that must stay in the EU, or close to its users, goes on an instance in that region.

• •

  Stricter separation: production with its own root users, its own version and its own backups.

A common setup puts production in one organisation and development and testing in another. The production organisation then has a short member list and its own invoice, while one non-production instance holds a database for each of dev, test and uat.

Organisation: Production
└── Instance: app
    └── Namespace: main
        └── Database: prod
Organisation: Non-production
└── Instance: app-nonprod
    └── Namespace: main
        ├── Database: dev
        ├── Database: test
        └── Database: uat

Splitting environments into databases on one instance costs the least, but they share the server, so a load test in test competes with dev for CPU and memory. Splitting them into instances in one organisation keeps one member list and one invoice. Splitting them into organisations also separates who can deploy and delete instances.

Single sign-on and organisation membership

Single sign-on is set up on the enterprise, and it controls how people sign in to Studio, which is the administration layer. Applications that connect to an instance sign in through the data access layer instead, with database users or with tokens from an access method.

A person who signs in through single sign-on for the first time gets a new SurrealDB account in the enterprise's member list, with no organisation memberships. Add them to each organisation they need, with the role they need, as described in Members and roles. This account is separate from any account the person already has with the same email address, so memberships of the earlier account do not carry over. Enterprise roles do not currently grant anything inside organisations, so each person is added to each organisation directly.

Billing

Billing belongs to the organisation. Each organisation receives one monthly invoice that covers all of its instances and Agent Memory contexts, so two organisations means two invoices. See Billing.

A support plan also applies to a whole organisation. With more than one organisation, check that each one has the plan it needs.

Buying through a marketplace works per organisation as well. Claiming an AWS Marketplace or Azure Marketplace subscription creates a new organisation, billed through that cloud account. Existing instances can be moved into it through support.

Related pages

• •

  Organisations: Create an organisation and use its settings.

• •

  Members and roles: What each organisation role can do.

• •

  Enterprises: Single sign-on, domains and enterprise roles.

• •

  Instances: Deploy and size an instance.

• •

  DEFINE USER: Users at the root, namespace and database levels.