Databases and multi-tenancy

In Fauna, a database stores data as documents in one or more collections.

Database model

Fauna’s database model makes it easy to create databases for isolated environments, such as staging and production, and multi-tenant applications:

  • Each Fauna database can have multiple child databases. You can use child databases as tenants for your application. See Multi-tenancy.

  • All databases, including child databases, are instantly allocated without provisioning or warmup.

  • Each database is logically isolated from its peers with separate access controls. See Isolation and access control.

  • All Fauna resources, except top-level keys, exist as documents within a specific database. This includes collections, user-defined functions, and child databases.

  • Transactions run in the context of a single database and can’t access data outside the database. See Scope and routing.

Multi-tenancy

Fauna databases support a hierarchical database structure with top-level and child databases.

Top-level and child databases

Top-level databases exist in an account’s top-level context. All Fauna resources, except top-level keys, exist as documents within a specific database. This includes child databases.

A database can have multiple child databases, which can also have child databases.

Isolation and access control

You can use Fauna databases to build applications with strong isolation guarantees:

  • Each database is logically isolated from its peers with separate access controls.

  • You can use scoped keys from a parent database to manage and access child databases.

  • Child databases can’t access or discover parent or peer databases.

Scope and routing

Each Fauna query is an independently authenticated request to the Query HTTP API endpoint. Each query is a transaction.

Transactions run in the context of a single database and can’t access data outside the database.

Transactions are routed to a database based on the Query API request’s authentication secret. You can’t use a secret to access a peer or parent database.

Database system collection

Fauna stores metadata and settings for databases as documents in the Database system collection. You can use Database collection methods to create and manage databases in FQL.

The Database collection only contains direct child databases of the database scoped to your authentication secret. You can’t use the Database collection to access parent, peer, or other descendant databases.

If you use an authentication secret scoped to an account’s top-level context, the Database collection contains documents for the account’s top-level databases. You can create a top-level secret using the Fauna CLI's cloud-login command.

See Role FQL docs

Global database ID

Each Database document contains an auto-generated, globally unique ID for the database:

{
  name: "ECommerce",
  coll: Database,
  ts: Time("2099-06-24T21:54:38.890Z"),
  // Globally unique id for the `ECommerce` database.
  global_id: "ysjpykbahyyr1",
  priority: 10,
  typechecked: true
}

Applications and external systems can use this ID to identify a Fauna database.

Create and manage databases

You can create and manage databases using:

Authentication for top-level databases

To create or manage a top-level database using the Fauna CLI or an FQL query, you must use an authentication secret scoped to the account’s top-level context. You can create a top-level secret using the Fauna CLI's cloud-login command.

Authentication for child databases

To create or manage a child database using the Fauna CLI or an FQL query, you must use an authentication secret scoped to the parent database.

Create a database

You can create a database using the Fauna Dashboard or the Fauna CLI's create-database command:

fauna create-database ECommerce

You can also use Database.create() to create a database in an FQL query:

Database.create({
  name: "ECommerce",
  typechecked: true
})

Manage a database’s schemas

You can use schemas to control a database’s structure and behavior. You manage schemas as using the Fauna Dashboard or as FSL files using the Fauna CLI.

You can create a CI/CD pipeline to copy and deploy schemas across databases.

See Schema

Rename a database

You can rename a database using the Fauna Dashboard. You can also use database.update() to rename a database in an FQL query:

// Renames the `ECommerceStore` database to `Ecommerce`.
Database.byName("ECommerceStore")!.update({
  name: "ECommerce"
})

Renaming a database preserves any inbound references to the database. Data in a renamed database remains accessible using existing keys.

Delete a database

You can delete a database using the Fauna Dashboard or the Fauna CLI's delete-database command:

fauna delete-database ECommerce

You can also use database.delete() to delete a database in an FQL query:

// Renames the `ECommerce` database to `EcommerceStore`.
Database.byName("ECommerce")!.delete()

Considerations

When you delete a database, its data becomes inaccessible and is asynchronously deleted. As part of the deletion process, Fauna recursively deletes:

  • Any keys scoped to the database.

  • The database’s child databases, including any nested databases.

Deleting a database with a large number of keys can exceed Transactional Write Ops throughput limits and cause errors with a 429 HTTP status code.

Deleting a database with a large number of child databases can cause errors with a 440 HTTP status code.

To avoid throttling or timeouts, incrementally delete all keys and child databases before deleting the database. See delete all keys and delete all child databases.

Is this article helpful? 

Tell Fauna how the article can be improved:
 Visit Fauna's forums or email docs@fauna.com

Thank you for your feedback!