Skip to main content
This guide covers how to connect to your MariaDB database in Zerops, both from services within the same project and from outside the Zerops environment.

​
Default MariaDB database and user

Zerops creates a default database and a default user automatically when a new MariaDB service is created.

​
Database

The default database name is identical to the service hostname. The default encoding is set to utf8mb4.

​
DB user

Default user name is identical to the service hostname. Default user password is generated randomly. You will find the password in Zerops GUI or you can use the environment variable.
Zerops creates a second DB user: zps for maintenance reasons with full privileges. Do not delete, change the password or remove privileges from this user, it will disrupt Zerops ability to maintain the database cluster.

​
Copy access details from Zerops GUI

You will find the MariaDB access details under the Access details button in the project dashboard page. The same information is available in the service detail page in the left menu under the Peek access details button.

​
MariaDB access parameters

ParameterDescription
HostnameThe service hostname specified when the MariaDB service was created.
Port3306
This port is fixed for all MariaDB services and cannot be customized.
UserZerops creates a database user automatically when the service is created. The user name is always identical to the service hostname.
PasswordZerops sets a random password when the service is created.
Connection stringThe connection string for MariaDB service is:
mysql://${user}:${password}@{hostname}:3306

​
Connect to MariaDB from runtime services of the same project

Projects in Zerops represent a group of one or more services. Services can be of different types (runtime services, databases, message brokers, object storage, etc.). All services of the same project share a dedicated private network. To connect to a service within the same project, just use the service hostname and its internal port.

​
Direct Connection Example

To connect to MariaDB database1 service, set: 
host = database1
port = 3306
user = database1
password = **********
You will find the password under the Access details button in Zerops GUI.
Do not use SSL/TLS protocols when connecting to MariaDB from other runtime services in the same project. Zerops MariaDB is not configured to support these protocols. The security is assured by the project private network. Due to security reasons Zerops doesn’t allow exposing MariaDB service to the internet.

​
Use MariaDB environment variables

Zerops creates default environment variables for each MariaDB service to help you with connection from runtime services in the same project. To avoid the need to copy database access parameters manually, use environment variables in your runtime service.

​
Prefix the environment variable key

All services of the same project can reference environment variables from other services. To use an environment variable from one service in another service in the same project, you must prefix the environment variable key with the service hostname and underscore.

​
Example

To access the connectionString env variable of the mariadb1 service, use mariadb1_connectionString as the env variable key. To access the password env variable of the mariadb2 service, use mariadb2_password as the env variable key.

​
MariaDB environment variables

List of service environment variables is available in Zerops GUI. Go to a MariaDB service detail and choose Environment variables in the left menu. Zerops creates following environment variables when the MariaDB service is created:
VariableDescription
hostnameThe service hostname specified when the MariaDB service was created.
port3306
This port is fixed for all MariaDB services and cannot be customized.
projectIdID of the project. Generated by Zerops.
serviceIdID of the MariaDB service. Generated by Zerops.
connectionStringThe connection string for MariaDB service is:
mysql://${user}:${password}@{hostname}:3306

Connection string contains references to user and password variables. Each time the user or password variable is updated, the connectionString variable is automatically updated as well.
userZerops creates a database user automatically when the service is created. The user name is always identical to the service hostname.
passwordZerops sets a random password when the service is created.
Important notes:
  • When you change the value of the password env variable, only the env variable is updated, not the actual password of the MariaDB user. You have to update the password of the database user manually.
  • When you change the password of the default MariaDB user in the database, the new password is not synchronised to the password env variable. You have to update the password env variable manually.
You can create own custom environment variables for the MariaDB service in Zerops GUI and use them in the same way as the default variables.

​
Connection Examples

// Using environment variables to connect
const mysql = require('mysql2');

const connection = mysql.createConnection(
  process.env.mariadb1_connectionString
);

// Or using individual parameters
const connection = mysql.createConnection({
  host: process.env.mariadb1_hostname,
  port: process.env.mariadb1_port,
  user: process.env.mariadb1_user,
  password: process.env.mariadb1_password,
  database: process.env.mariadb1_hostname
});

​
Connect to MariaDB in Zerops remotely

Due to security reasons Zerops doesn’t allow exposing MariaDB service directly to the internet.

​
Connect via Zerops VPN

You can securely connect to MariaDB from your local workspace via Zerops VPN. Zerops VPN client is included into zCLI, the Zerops command-line tool.
1

Install & setup zCLI

Install and configure zCLI if you haven’t already.
2

Start the Zerops VPN

Start the VPN connection to your project.
3

Get connection details

Copy the access details manually from Zerops GUI.
Environment variables are not available when connected through VPN.
4

Connect with your tool

Use your preferred database management tool or command-line client to connect.
5

Stop the VPN when finished

Stop the Zerops VPN when you’re done.
Do not use SSL/TLS protocols when connecting to MariaDB over VPN. Zerops MariaDB is not configured to support these protocols. The security is assured by the VPN.

​
Using mysql CLI

If you use the mysql command-line client to manage your MariaDB on your local workspace, you can connect it securely to MariaDB via Zerops VPN. Once the VPN session is established, you have the secured connection to the project’s private network in Zerops. You can access all project services locally by using their hostname. Use mysql command to connect to MariaDB in Zerops: 
mysql -h [hostname] -u [user] -p [password] [database_name]
Try {hostname}.zerops instead of just {hostname} if you encounter any connection issues.

​
Connect to MariaDB from another Zerops project

All services of the same project share a dedicated private network. You can use the service hostname to connect from one service to another within the same project. Different Zerops projects have no special connection. They can communicate with each other only via the internet. If you need to connect to a MariaDB service in a Zerops project from a runtime service in another project, you need to use the Zerops VPN.
Due to security reasons Zerops doesn’t allow exposing MariaDB service directly to the internet.

​
Next Steps

Manage MariaDB

Learn how to manage users and databases

Build docs developers (and LLMs) love

Get started for freeTalk to us