Managed Document Databases - Quickstart

Managed Document Databases provide fully-managed document Database Instances, with FerretDB as a database engine.

Document databases enable users to store and retrieve data in a document format, such as json. Compared to traditional relational databases where data is stored in a table-like format, document-type storage supports storing multiple nested keys and values in each document key.

How to create a database

1. Click Document Databases under Managed Databases on the side menu, if you do not have a Database Instance already created, the creation page displays.

2. Click Create a Database Instance. The creation wizard displays.

3. Complete the following steps in the wizard:

   • Select FerretDB as a database engine.
   • Choose a region. This is the geographical location where your database will be deployed.
   • Select a database configuration. You can choose between:
     • High Availability: creates a secondary node with an up-to-date replica of the database. If the primary Instance fails, the secondary takes over requests.
     • Standalone: creates a standalone database provisioned on a single node.
   • Select a node type.
   • Define the size of your Block Storage volume. You can increase your storage space without changing your node type, with no downtime. You can increase your volume to up to 10 TB.
   • Enable automatic backups, if necessary.
   • Add a name and set a password for your user.
   Important:

   Your username must adhere to specific criteria.

   • Length must be between 1 and 63 characters
   • First character must be an alphabetic character (a-Za-Z)
   • It can not start with _rdb
   • Only a-zA-Z0-9_$- characters are accepted
   • Enter a name for your Database Instance.
   • Tick the checkbox if you wish to share telemetry data with FerretDB.
   Important:

   This option is available during the Public Beta phase of Document Databases. It allows you to contribute with the FerretDB Open Source project. Only request types, such as find and aggregate, will be collected and shared. Request parameters or response content are neither collected nor shared. Refer to the official Ferret DB documentation page on telemetry for more information.

4. Click Create a Database Instance to confirm your choices and launch creation.

   You are taken to the Overview tab for your Database Instance, where you can see information including the Endpoint to enable you to connect to it.

Connect to your database

Via database client

1. Click Document Databases under Managed Databases on the side menu. A list of your Database Instances displays.
2. Click the database name or «See more Icon» > More info to access the Database Instance information page.
3. Click «Download Icon» next to the TLS certificate to download it.
4. Transfer the file to where you will execute the connection command.
5. Copy the connection command located under Connection in the Database Instance information page.
6. Paste the connection command in your terminal, and edit the username field with the login you chose when creating the database. The full command should look like the following:

   mongosh --tls --tlsCAFile databaseinstancename.pem 'mongodb://username@ip:port/databasename?authMechanism=PLAIN'Copy

   • databaseinstancename.pem - the TLS certificate downloaded on step 3.
   • username - the username you defined upon Database Instance creation.
   • ip - your Database Instance’s endpoint IP address.
   • database instance name - the database name you entered upon Database Instance creation. The default database name, generated when a name is not specified, always takes on the following format: docdb-xxxxx-xxxx.
   • database name - The default is called rdb. If you created a new database from the Databases tab inside your Database Instance, replace it with the database name.
   • port - the port on which your Database Instance is accessible
7. Enter your password. If the connection is successful, you should see the following message display on your console, and be able to write queries:

   The server generated these startup warnings when booting
   Powered by FerretDB v0.9.0 and PostgreSQL 14.6.Copy

Via an application

1. Click Document Databases under Managed Databases on the side menu. A list of your Database Instances displays.

2. Click the database name or «See more Icon» > More info to access the Database Instance information page.

3. Click «Download Icon» next to the TLS certificate to download it.

4. Transfer the file to where you will execute the connection command.

5. Get the following connection information from the Database Instance information panel or the string displayed upon connection:

   • username: the username you defined upon Database Instance creation.
   • password: the user password you defined upon Database Instance creation.
   • IP: your Database Instance’s endpoint IP address.
   • port: the port on which your Database Instance is accessible.
   • cert_file_path: the path to your Database Instance TLS certificate.

6. Enter the information above in your application configuration file.

   You can find examples below for Python, Nodejs, and Go applications:

   Python

   The following code shows you how to use the pymongo library to connect using TLS.

   from pymongo.mongo_client import MongoClient
   user_name      = "<replace_with_user_name>"
   password       = "<replace_with_password>"
   ip             = "instance_ip"
   port           = 1234
   cert_file_path ="<instance_certificate.crt>"
   # Estabish the tls connection:
   client = MongoClient(
           f'mongodb://{user_name}:{password}@{ip}:{port}',
           authMechanism='PLAIN',
           tls=True,
           tlsCAFile=cert_file_path,
       )
   # get the database you want to use
   db = client.rdb
   # get the collection cars
   cars = db["cars"]
   # prepare a new car to be inserted
   car = {"name": "Supercar", "price": 100000}
   # execute the insertion
   cars.insert_one(car)
   # read the car you just inserted
   car = cars.find_one()
   # print the car, it should contain an ObjectId
   print(car)Copy

   Nodejs

   The following code shows you how to use the mongodb module to connect using TLS.

   const { MongoClient } = require("mongodb");
   userName     = "<replace_with_user_name>"
   password     = "<replace_with_password>"
   ip           = "instance_ip"
   port         = 1234
   certFilePath = "<instance_certificate.crt>"
   client = new MongoClient(
           `mongodb://${userName}:${password}@${ip}:${port}`, {
             tls: true,
             tlsCaFile: certFilePath,
             authMechanism: "PLAIN",
           })
   await client.connect();
   # get the database you want to use
   const db = client.db("rdb")
   # get the collection cars
   const cars = db.collection("cars")
   # prepare a new car to be inserted
   let car = {name: "Supercar", price: 100000}
   # execute the insertion
   cars.insertOne(car)
   # read the car you just inserted
   car = cars.findOne()
   # print the car, it should contain an ObjectId
   print(car)Copy

   Go

   The following code shows you how to use the mongo driver to connect using TLS.

   package main
   import (
       "context"
       "fmt"
       "go.mongodb.org/mongo-driver/mongo"
       "go.mongodb.org/mongo-driver/mongo/options"
   )
   func main() {
       username := "<replace_with_user_name>"
       password := "<replace_with_password>"
       host := "<endpoint ip>"
       port := 1234 // replace with endpoint port number
       caCertPath := "<instance_certificate.crt>"
       // prepare the uri for the connection
       uri := fmt.Sprintf(
           "mongodb://%s:%s@%s:%d/rdb?tls=true&tlsCACert=%s&authMechanism=PLAIN",
           username,
           password,
           host,
           port,
           caCertPath,
       )
       ctx := context.Background()
       // connect to the database
       client, _ := mongo.Connect(ctx, options.Client().ApplyURI(uri))
       // get the database
       db := client.Database("rdb")
       // get the collection
       cars := db.Collection("cars")
       // insert a document
       carToInsert := Car{Name: "Supercar", Year: 2020}
       cars.InsertOne(ctx, carToInsert)
       // read the document
       carToRead := Car{}
       cars.FindOne(ctx, map[string]interface{}{"name": "Supercar"}).Decode(&carToRead)
       // print the document
       fmt.Println(carToRead)
   }
   type Car struct {
       Name string
       Year int
   }Copy

How to delete your database

1. Click Document Databases under Managed Databases on the side menu. A list of your Database Instances displays.
2. Click the database name or «See more Icon» > More info to access the Database Instance information page.
3. Scroll down the page to the Delete Instance section and click Delete Instance. A pop-up appears to inform that:
   Important:

   This will permanently destroy your Instance and all your data will be lost. This action is irreversible.

4. Type DELETE to confirm and click Delete this Instance.
   Tip:

   Alternatively, you can delete your Instance from your Database Instances list by clicking «See more Icon» next to the Instance name and then Delete.