CreateDatabase( param_object )
CreateDatabase( param_object )
CreateDatabase( param_object )
CreateDatabase( param_object )
create_database( param_object )
CreateDatabase( param_object )


The CreateDatabase function adds a new child database in the current database with the specified parameters. It requires an admin key.

It is not possible to create a parent or peer database with this function. To create a database outside of the current database, use the Fauna Dashboard.


Parameter Type Definition and Requirements


The param_object fields are described below.


Field Name Field Type Definition and Requirements


The name of a database.

Cannot be events, sets, self, documents, or _. Cannot contain the % character.


Optional - A JSON object to contain user-defined metadata for the database. It is provided for the developer to store information at the database level.


Optional - A relative weight between 1 and 500, inclusive, indicating how many resources this database is allowed to utilize. Defaults to 1. A higher number means more resources.

The priority option is deprecated as of release 2.10.0. You should avoid specifying priority. In some future Fauna release, priority will be removed. See Deprecations for more details.


Optional - A timestamp indicating the document’s time-to-live, which is when the document should be removed. When a document is removed, the document’s existence ceases (as if it never existed); temporal queries cannot recover the document.

Removal is handled by a background task, so once a document (including collections, databases, indexes, keys, roles, and tokens) "expires" due to the setting in the ttl field, it could be some time (hours or days) before the removal occurs. There is no guarantee that removal occurs.

As of version 3.0.0, the ttl field is honored on read — an expired but not yet removed document behaves as if removal is complete. But, until removal is completed by background task processing, you can continue to access the history of the document, provided you have its reference, using the Events function.


An object containing the metadata of CreateDatabase operations.

Field Name Field Type Definition and Requirements


A Reference to the database that was created.


The name of the database just created.


The timestamp, with microsecond resolution, associated with the creation of the database.


Included only when specified during database creation. An object containing user-defined metadata for this database.


A read-only string that provides a globally-unique identifier for this database.


The following query creates a database named "db-next" and returns the reference to the database, the name of the database, and the time the database was created:

    Value result = await client.Query(
        CreateDatabase(Obj("name", "db-next"))
catch (Exception e)
    Console.WriteLine($"ERROR: {e.Message}");
ObjectV(ref: RefV(id = "db-next", collection = RefV(id = "databases")),ts: LongV(1603756177320000),name: StringV(db-next),global_id: StringV(yx1enifpkybyy))
result, err := client.Query(
	f.CreateDatabase(f.Obj{"name": "db-next"}))

if err != nil {
	fmt.Fprintln(os.Stderr, err)
} else {
map[global_id:yx18tp8ogydyy name:db-next ref:{db-next 0xc0000ad290 0xc0000ad290 <nil>} ts:1603747134420000]
        CreateDatabase(Obj("name", Value("db-next")))
{ref: ref(id = "db-next", collection = ref(id = "databases")), ts: 1593464629200000, name: "db-next", global_id: "yq9nin7xhybyy"}
  q.CreateDatabase({ name: 'db-next' })
.then((ret) => console.log(ret))
.catch((err) => console.error(
  'Error: [%s] %s: %s',,
  ref: Database("db-next"),
  ts: 1592054207370000,
  name: 'db-next',
  global_id: 'yqhq17umsybyy'
result = client.query(
    q.create_database({"name": "db-next"})
{'ref': Ref(id=db-next, collection=Ref(id=databases)), 'ts': 1592856487080000, 'name': 'db-next', 'global_id': 'yq76pr57aybyy'}
CreateDatabase({ name: 'db-next' })
  ref: Database("db-next"),
  ts: 1624310358060000,
  name: 'db-next',
  global_id: 'yoatgw3icybyy'
Query metrics:
  •    bytesIn:   49

  •   bytesOut:  154

  • computeOps:    1

  •    readOps:    0

  •   writeOps:    1

  •  readBytes:   20

  • writeBytes:  473

  •  queryTime: 45ms

  •    retries:    0

Is this article helpful? 

Tell Fauna how the article can be improved:
Visit Fauna's forums or email

Thank you for your feedback!