Upsun projects already include a variety of managed services, so you don’t have to subscribe to an external cache or search-engine services.
As these services are included in your project, you can manage them through Git.
They’re backed up along with the rest of your project.
You can add new services and manage existing service configurations from your .upsun/config.yaml file.
For example, to add a MariaDB database engine to your Express project, complete the following steps:
1. Create a new branch for testing
To create a new branch, run the following command:
upsun environment:branch add-mysql-database
2. Add a MariaDB service
Configure the MariaDB service by adding a database service to your .upsun/config.yaml file:
To connect the service to your application (APP_NAME), add the following relationship:
Commit your change:
git commit -am "adding MariaDb database service"
upsun push
3. Connect to the service
To configure your Express app so it uses your new database,
you need a Node.s module named mysql2.
To install it, run the following command:
Wherever your application code attemps to connect to the database service,
Upsun will automatically generate environment variables containing connection credentials as a function of the relationship name.
In this example, the MariaDB service access is granted to the application container via the relationship database.
Upsun will therefore generate the variable DATABASE_HOST (among many others), using this name.
Here’s an example of how this credential variable naming convention is used to connect to a MariaDB service:
const express = require('express')
const app = express()
const mysql = require("mysql2/promise");
const port = (process.env.PORT || '3000');
function openConnection() {
return mysql.createConnection({
host: process.env.DATABASE_HOST,
port: process.env.DATABASE_PORT,
user: process.env.DATABASE_USERNAME,
password: process.env.DATABASE_PASSWORD,
database: process.env.DATABASE_DATABASE
});
}
function createTable(connection) {
return connection.execute(
`CREATE TABLE IF NOT EXISTS upsuninfo (
uid INT(10) NOT NULL AUTO_INCREMENT,
username VARCHAR(64) NULL DEFAULT NULL,
departname VARCHAR(128) NULL DEFAULT NULL,
created DATE NULL DEFAULT NULL,
PRIMARY KEY (uid)
) DEFAULT CHARSET=utf8 COLLATE=utf8_unicode_ci;`
);
}
function insertData(connection) {
return connection.execute(
"INSERT INTO upsuninfo (username, departname, created) VALUES ('upsun', 'Deploy Friday', '2026-09-29')"
);
}
function readData(connection) {
return connection.query("SELECT * FROM upsuninfo");
}
function dropTable(connection) {
return connection.execute("DROP TABLE upsuninfo");
}
// Define the main route.
app.get('/', async function(req, res){
// Connect to MariaDB.
const connection = await openConnection();
await createTable(connection);
await insertData(connection);
const [rows] = await readData(connection);
const droppedResult = await dropTable(connection);
// Make the output.
const outputString = `Hello, World! - A simple Express web framework template for Upsun
MariaDB Tests:
* Connect and add row:
- Row ID (1): ${rows[0].uid}
- Username (upsun): ${rows[0].username}
- Department (Deploy Friday): ${rows[0].departname}
- Created (2026-09-29): ${rows[0].created}
* Delete row:
- Status (0): ${droppedResult[0].warningStatus}`;
res.set('Content-Type', 'text/plain');
res.send(outputString);
});
// Get PORT and start the server
app.listen(port, function() {
console.log(`Listening on port ${port}`)
});
git add package.json package-lock.json index.js && git commit -m "adding MariaDb database service"
upsun push
upsun environment:url --primary
4. Merge to production
When satisfied with your changes, merge them to the main branch:
5. Remove the feature branch
Then, remove the feature branch:
upsun checkout main
git pull upsun main
upsun environment:delete add-mysql-database
git fetch --prune
When the environment:delete CLI command is run, the CLI suggests you deactivate and delete your add-mysql-database environment.
Make sure you opt in.
Tips & Tricks
You can get your project’s relationship information using the following command: 
