Jump toUpdate content

Managed Document Databases - Quickstart

Reviewed on 24 July 2023Published on 26 February 2023

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.

Security & Identity (IAM):

You may need certain IAM permissions to carry out some actions described on this page. This means:

  • you are the Owner of the Scaleway Organization in which the actions will be carried out, or
  • you are an IAM user of the Organization, with a policy granting you the necessary permission sets
Requirements:

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'
    • 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.

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)

    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)

    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
    }

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.