How to connect to a managed database on Skygear

Search…

You can connect to your self-managed database to Skygear using secret management.

Introduction
An database is often an essential to frontend apps. Skygear doesn't come with an out-of-the-box database, however it's almost effortless to bring in one of yours.
While it's perfectly fine to read this How to section as a standalone guide, to grasp the whole picture you are recommended to go through this Quick Start .
There exist numerous managed database services out there, and we will use MongoDB Atlas as our sample in this section. Connection will be established through MongoDB Atlas's Connection String.
Prerequisites
Have a Skygear account and an app registered. We will be using Secret on Skygear, which is a resource designed to hold sensitive information, registered under and can used by a Skygear app. The latter part of this definition means you will need an app before you can add Secrets.
Before you start this section, please ensure you have skycli installed and configured properly.
Although this section doesn't really require skycli as we will be adding database connection via Secrets which can be done with Skygear Portal, to try out the newly connected database you will still need an app deployed and skycli is the only way to perform that. 
TL;DR Sooner or later you will need to install and configure skycli.
Sign up to MongoDB Atlas
Navigate to here and fill in the create account form. Finish the registration flow and choose options as you fancy. They offer a free managed database cluster, still you can opt for the more decorated ones.
Once you have signed up and are redirected to your Atlas dashboard, click on the "Database Access" link on the left sidebar. Add a new user to your MongoDB Atlas cluster in that page, and be sure to jot down the username and password pair as we will need these later.
Then go to the "Network Access" page, whose link is just under "Database Access" on the left sidebar. You should find an add-ip-address button, click on it and choose the option "Allow Access from Anywhere" in the popped up form. Don't forget to click "Confirm" to finalise your configurations!
Go back to "Cluster" on the left sidebar, and click the grey button "Connect".
Choose the option “Connect Your Application” .
And save the connection string. Be sure to replace the placeholders in the string with your credentials jotted down earlier.
Save the Connection String as a Secret on Skygear
You have two options:
skycli
Create a secret with the database connection information using skycli:
1
$ skycli secret create <secret_name> '<database_url>'
2
​
3
#example
4
$ skycli secret create MONGO_DB_URL 'mongodb+srv://<USER>:<PASSWORD>@<HOST>/<COL>?retryWrites=true'
Copied!
To check if the Secret has been created successfully:
1
$ skycli secret list
2
NAME           CREATED_AT                  
3
MONGO_DB_URL   2019-10-10 14:03:40 +08:00 
Copied!
Skygear Portal
Create a secret on Skygear Portal. Below is a screenshot where a Secret has been added:
Pass in the Connection String to service(s)
Say you have written some code that are deployment-ready called backend. To access a Secret, i.e. your MongoDB Atlas connection string in backendnamed MONGO_DB_URL,  update skygear.yaml:
1
app: <your_app_name>
2
​
3
api_version: v2.1
4
​
5
deployments:
6
  - name: backend
7
    type: http-service
8
    context: <your_code_path>    #where you code resides
9
    path: <service_path>         #where the service is exposed         
10
    port: 8080                   #where the service is exposed         
11
    environment:
12
      - secret: MONGO_DB_URL       #the actual Secret value
13
​
Copied!
Say you are coding in Node.js. To access the Connection String:
1
const connectionString = process.env.MONGO_DB_URL;
2
// do something with connectionString...
Copied!
Deploy app to apply changes
1
$ skycli app deploy
Copied!