How data works 3: Add services

1. Cleanup Your Environments

Before moving forward, let's clean up the project by deactivating the development environments from the previous steps.

Run the following commands to switch to your main branch, update it, and delete the data-child and data environments along with their remote branches:

git checkout main
git pull upsun main
upsun environment:deactivate data-child -y --delete-branch
upsun environment:deactivate data -y --delete-branch

You should now only have two environments in your project: main (active, production) and updates (inactive, development).

2. Add a Service

Next, let's create a new development environment specifically for adding our database:

upsun environment:branch add-db

Unlike Platform.sh which uses multiple YAML files, Upsun uses a single, unified .upsun/config.yaml file to define your entire infrastructure.

Open .upsun/config.yaml in your editor and add a top-level services block at the bottom of the file with the following configuration:

services:
    db:
        type: mariadb:10.4
        disk: 2048

You have now configured a service container named db running MariaDB version 10.4. Notice that we only specify the minor version (10.4), not the patch version (e.g., 10.4.x). This is because Upsun provides managed services:

• Simple Configuration: You do not need to understand how to provision or install a database; a few lines of YAML handle it.

• Sane Defaults: The complex background configurations required to keep a database secure and functional are managed automatically.

• Patch Versions: The platform continuously monitors upstreams for security patches. When a patch is released, your service container is updated automatically between deployments.

3. Expose the Service to Your App

By default, all containers exist in strict isolation. To allow your application container to talk to your new database container, you must explicitly define a relationship.

Still in your .upsun/config.yaml file, locate your application definition under the applications block. Add the relationships mapping there:

applications:
    app: # (This might be named something else depending on your setup)
        # ... your existing app config ...
        
        relationships:
            database: "db:mysql"

Understanding this relationship:

• database: This is the chosen name of the relationship. Your application will use this exact name to access the database credentials.

• db: This corresponds to the name of the service container you defined in the services block.

• mysql: This is the endpoint type provided by the MariaDB service.

4. Deploy and Test Services at Runtime

Commit and push your changes to deploy the new database configuration:

git add .upsun/config.yaml
git commit -m "Add a database."
git push upsun add-db

During the deployment log output, you will see the platform provisioning the new db container alongside your app:

Redeploying environment add-db
Preparing deployment
Closing services app and router
Opening application app and its relationships
Opening environment
Environment configuration
  app (type: LANGUAGE:VERSION, size: S)
  db (type: mariadb:10.4, size: S, disk: 2048)

Accessing the Credentials

Once the deployment finishes, SSH into your application container:

upsun ssh -e add-db

Because you defined a relationship, Upsun securely provides the database connection credentials directly to your app via a base64-encoded environment variable called $PLATFORM_RELATIONSHIPS.

Decode and view this variable using the pre-installed jq JSON processor:

echo $PLATFORM_RELATIONSHIPS | base64 --decode | jq

You will see an output similar to this:

{
  "database": [
    {
      "username": "user",
      "scheme": "mysql",
      "service": "db",
      "ip": "169.254.196.237",
      "host": "database.internal",
      "port": 3306,
      "path": "main",
      "password": "",
      "type": "mariadb:10.4"
    }
  ]
}

Notice that the top-level key matches the relationship name (database) you defined earlier.

Connecting to the Database

You can extract these values dynamically to connect to the database via the terminal. Run the following commands in your SSH session to parse the JSON and open a MySQL prompt:

DB_HOST=$(echo $PLATFORM_RELATIONSHIPS | base64 --decode | jq -r '.database[0].host')
DB_PORT=$(echo $PLATFORM_RELATIONSHIPS | base64 --decode | jq -r '.database[0].port')
DB_USER=$(echo $PLATFORM_RELATIONSHIPS | base64 --decode | jq -r '.database[0].username')
DB_PATH=$(echo $PLATFORM_RELATIONSHIPS | base64 --decode | jq -r '.database[0].path')

mysql -h $DB_HOST -P $DB_PORT -u $DB_USER $DB_PATH

(You can exit the MySQL session by pressing Ctrl+D)

A Note on Security:

Notice that the database has an internal host (database.internal). Services do not have external routes. They can only be accessed by the application container they are explicitly linked to via a relationship, keeping your data secure and isolated from the public internet.