How to access MySQL/MariaDB credentials on Platform.sh

How-to Guides
, , , ,
#1

Goal

Access credentials for MySQL/MariaDB from within a Platform.sh application using Node.js.

Assumptions

  • an active Platform.sh project
  • properly configured .platform/services.yaml for the given service
  • SSH key configured on account if developing locally
  • MySQL installed if developing locally
  • properly configured MySQL/MariaDB relationship like so, in .platform.app.yaml:
relationships:
    database: "db:mysql"

If developing locally, remember to first open a tunnel to the project environment using the Platform CLI.

$ platform tunnel:open && export PLATFORM_RELATIONSHIPS="$(platform tunnel:info --encode)"

This will open an SSH tunnel to your current Platform.sh environment and expose a local environment variable that mimics the relationships array on Platform.sh. Check the Platform.sh documentation and How to develop locally on Platform.sh with a tethered connection for more information.

Problems

Platform.sh service credentials are made available to applications as the PLATFORM_RELATIONSHIPS environment variable, which is a base64-encoded JSON string that has to be decoded before it can be used.

There are two primary options for accessing service credentials on Platform.sh that can be used within an application:

  1. Using the Platform.sh Config Reader library
  2. Accessing environment variables directly

Steps (Config Reader)

1. Install the library

Install the configuration library. See the documentation for minimum requirements.

$ npm install platformsh-config --save

2. Create a Config object

Creating a Config object provides access to the Platform.sh environment.

const config = require("platformsh-config").config();

3. Read the credentials

// Get the credentials to connect to the MySQL/MariaDB service.
const credentials = config.credentials('database');

Steps (Manual)

1. Load the environment variable

relationships = JSON.parse(new Buffer(process.env['PLATFORM_RELATIONSHIPS'], 'base64').toString());

2. Read the credentials

const credentials = relationships['database'];

Use

path is the database name that will be needed to connect. Pass the needed properties to your MySQL library’s setup routine in your application. Most of the time the other values may be ignored.

In either case, credentials is a an object matching the relationship JSON object, which includes the appropriate user, password, host, database name, and other pertinent information.

{
  "username": "user",
  "scheme": "mysql",
  "service": "db",
  "fragment": null,
  "ip": "169.254.147.122",
  "hostname": "czwb2d7zzunu67lh77infwkm6i.mysql.service._.eu-3.platformsh.site",
  "public": false,
  "cluster": "rjify4yjcwxaa-master-7rqtwti",
  "host": "database.internal",
  "rel": "mysql",
  "query": {
    "is_master": true
  },
  "path": "main",
  "password": "",
  "type": "mysql:10.2",
  "port": 3306
}

Conclusions

Using either the language-specific Platform.sh Configuration library or direct access methods for environment variables, an application can get MySQL/MariaDB credentials in Node.js.

Platform.sh supports configuration libraries for multiple languages. The Node.js configuration library can be useful for inspecting the project environment:

// Checks whether the code is running in a build environment
config.inBuild()
// Checks whether the code is running in a runtime environment
config.inRuntime()

and for reading environment variables as attributes of config:

// Available in Build and at Runtime
config.appDir;
// Available at Runtime only
config.branch;
config.smtpHost;

The APIs for each language are written to be as consistent as possible, but seek out each library’s documentation for specific differences.

#2

Alternatively to decode the env variable directly from the terminal, one could use the following command:

echo $PLATFORM_RELATIONSHIPS | base64 --decode | jq

If jq is not installed, it can be installed through homebrew on macos