Databases
In Fauna, a database stores data as documents in one or more collections.
Database structure
Fauna supports a hierarchical database structure, allowing for top-level and child databases.
Top-level databases
Top-level databases exist in an account’s top-level context. Aside from top-level keys, all other Fauna resources, including child databases, exist as documents within the context of a specific database.
Child databases
A Fauna database can have multiple child databases. Child databases can have child databases.
Provisioning
All databases, including child databases, are instantly allocated. There is no resource provisioning or warmup wait interval.
Multi-tenancy
You can use child databases to build multi-tenant applications with strong isolation guarantees.
Child databases do not inherit schema or access controls from their parent database. Each database is logically isolated from its peers, with separate access controls.
When connected to a child database, it isn’t possible to access the parent database or even discover that there is a parent database.
If your use case doesn’t require strong isolation, you can also use collections for multi-tenancy. See Exploring Multi-Tenancy Options in Fauna. |
Transaction scope and routing
In Fauna, every transaction is an HTTP API request. Fauna uses authentication secrets to route requests to a single database or an account’s top-level context.
Transactions run in the context of a single database and can’t access data outside the 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 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:
-
The Fauna Dashboard
-
The Fauna CLI
Create and manage 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 cloud-login
command.
Create and manage 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.
Rename a database
You can rename a database using the Fauna Dashboard. You can also use
update()
to rename a
database in an FQL query:
// Renames the `ECommerce` database to `EcommerceStore`.
Database.byName("ECommerce")!.update({
name: "ECommerceStore"
})
Renaming a database changes its reference but preserves 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 delete()
to delete child databases 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!