Create a MySQL or MariaDB database and connect to it

MariaDB and MySQL are the databases behind most PHP applications and a good share of everything else. Both are available as managed instances: order one in the panel, copy the connection details, connect with the usual clients over TLS. They differ in one detail that trips people up, so this guide covers both, including where they part ways.

What you need

• A Headpat Space account with a verified email address and your billing details filled in.
• A client: the mariadb command line that ships with MariaDB, or mysql from MySQL. Either talks to either server; use the one matching your database to get the exact flags below.

1. Order the database

1. Sign in to the panel, open Apps in the sidebar and click Create App.
2. Under Template, search for MariaDB or MySQL and select it.
3. Under Package, choose a package. single runs one server and is fine for most sites. The ha packages run three servers that replicate each other and fail over on their own: MariaDB with Galera, MySQL with semi-synchronous replication. Your connection details stay the same either way.
4. Under Details, fill in a Display name and pick the version your application needs, or leave the default.
5. Tick the box confirming that provisioning may start right away, click Deploy app and complete the payment.

MariaDB is ready in about a minute; MySQL takes two to three because its cluster initialises first. Wait until the app page shows running.

2. Find your connection details

Open the database under Apps. The card Database Connection has everything you need: Host and Port. The port is one of its own, not 3306. Click Reveal next to Credentials to show the login:

	MariaDB	MySQL
Username	app	moco-writable
Database	app, created for you	none yet; you create your own (next section)
Password	generated for your instance	generated for your instance

The Connection string puts it all in one line. Every field has a copy button; click Hide when you are done. Treat the password like any other secret.

3. Connect

The server presents a publicly trusted certificate for its hostname, so your client can verify it with the certificate authorities your operating system already trusts. Ask for that verification; it costs nothing and rules out a tampered connection.

MariaDB, with the mariadb client:

mariadb -h YOUR_HOST -P YOUR_PORT -u app -p --ssl-verify-server-cert --ssl-ca=/etc/ssl/certs/ca-certificates.crt app

MySQL, with the mysql client:

mysql -h YOUR_HOST -P YOUR_PORT -u moco-writable -p --ssl-mode=VERIFY_IDENTITY --ssl-ca=/etc/ssl/certs/ca-certificates.crt

The --ssl-ca path is the CA bundle on Debian and Ubuntu; on Fedora and RHEL it is /etc/pki/tls/certs/ca-bundle.crt, on macOS with Homebrew /etc/ssl/cert.pem. Both clients refuse the connection if the certificate does not match the hostname, which is the point: connecting by IP address fails on purpose.

On MySQL, the first thing to do is create a database, since the server comes without one:

CREATE DATABASE shop;
CREATE USER 'shop'@'%' IDENTIFIED BY 'a-long-random-password';
GRANT ALL ON shop.* TO 'shop'@'%';

moco-writable may create databases and users but has no server administration rights, so it cannot lock you out of your own instance. On MariaDB the database app exists already and app owns it; you can still add more databases and users.

4. Connect from your application

Most frameworks take host, port, user, password and database separately, or a single URL:

DATABASE_URL=mysql://app:YOUR_PASSWORD@YOUR_HOST:YOUR_PORT/app

Turn on TLS verification in your library's options. The server certificate chains to a public root, so pointing the library at the system CA bundle is all it needs; do not disable verification to make a connection work. Two examples:

Node with mysql2:

import mysql from "mysql2/promise";

const pool = mysql.createPool({
  host: process.env.DB_HOST,
  port: Number(process.env.DB_PORT),
  user: process.env.DB_USER,
  password: process.env.DB_PASSWORD,
  database: process.env.DB_NAME,
  ssl: { rejectUnauthorized: true },
});

Python with PyMySQL:

import os
import pymysql

conn = pymysql.connect(
    host=os.environ["DB_HOST"],
    port=int(os.environ["DB_PORT"]),
    user=os.environ["DB_USER"],
    password=os.environ["DB_PASSWORD"],
    database=os.environ["DB_NAME"],
    ssl={"ca": "/etc/ssl/certs/ca-certificates.crt"},
)

Keep the password in an environment variable or a secret store, not in your code.

Limit who can connect

By default the server accepts connections from any address that knows a password. The card IP Allowlist on the app page narrows that to the addresses you list, for example your application server's IP. Add the address, click Save, and the card shows Restricted.

Backups

Both engines are dumped on the schedule of your package to storage outside the cluster, with the retention the package includes.

• MariaDB: the Backups card lists every dump. Create backup takes one before a risky change; Restore replaces the current data with a dump and the database is unavailable while that runs. Details in Back up and restore your app.
• MySQL: the scheduled dumps run and are kept, but the panel does not list them yet. Until it does, take your own copies with mysqldump and restore them with the mysql client.

For a copy on your own machine either way, run the dump tool against the same host and port with the TLS flags from above: mariadb-dump for MariaDB, mysqldump for MySQL.

Look inside without a client

The Database console card on the app page lists the tables with row counts, pages through their rows, and runs SQL you type. It connects from inside the server itself with full rights, so it is the quickest way to check what your application wrote. See Browse and query your database from the panel.

If something does not work

• The connection times out: check the port; it is not 3306. If you set an IP allowlist, your current address must be on it.
• Certificate verification fails: you connected by IP address, or the client has no CA bundle at the path you gave. Connect by hostname and point --ssl-ca at the bundle your system has.
• "No database selected" on MySQL: there is none yet. Create one as shown above and name it in your connection.
• Access denied: the password was copied with a trailing space or newline, or the user has no rights on that database. Reveal the credentials again and copy with the button.