# MySQL Connection Strings

> The MySQL connection strings API Maker takes, for MySQL, Percona Server and TiDB - the five parts it reads, examples, how to add one to an instance, and the common errors.

Source: https://docs.apimaker.dev/v4/docs/Database-connection-string/mysql-connection-strings.html

This page also serves Percona Server and TiDB, which speak the protocol of MySQL. MariaDB has [its own page](https://docs.apimaker.dev/v4/docs/Database-connection-string/mariadb-connection-strings.html).

## The format

```text
mysql://user:password@host:port/database
```

| Part | What it is |
|---|---|
| `mysql://` | `mariadb://` works too. |
| `user:password@` | The user and its password. Write the password as it is, even with `@` or `:` in it : API Maker encodes it before it connects. |
| `host:port` | `3306` when no port is given. TiDB listens on `4000`. |
| `/database` | Optional : the database a connection starts in. An instance reaches every database its user may read. |

API Maker reads the user, the password, the host, the port and the database, and nothing else : options after `?` are not read (`?multipleStatements=true` in the sample secret changes nothing).

> **Warning : No TLS to MySQL and MariaDB**
>
> API Maker v4 connects to MySQL, MariaDB, Percona Server and TiDB without TLS. Keep the database on the same server or on a private network, or reach it through an SSH tunnel or a VPN. A server which requires TLS (`require_secure_transport=ON`, the default of some managed services) refuses the connection.

## Examples

```text
# 1. MySQL on the same server
mysql://root:password@127.0.0.1:3306

# 2. A database to start in
mysql://app:password@10.0.0.5:3306/inventory

# 3. A password with special characters, written as it is
mysql://app:p@ss:w0rd!@10.0.0.5:3306/inventory

# 4. Percona Server
mysql://app:password@10.0.0.6:3306

# 5. TiDB
mysql://root:password@10.0.0.7:4000
```

## Add it to API Maker

An instance never holds the connection string itself : it names a key of your [default secret](https://docs.apimaker.dev/v4/docs/secrets/secrets.html), where the string stays encrypted, out of Git.

1. **Put the string in the secret** **Security → Secret Management** → `Default`. Add it under `common.connectionString`, with a name of your choice, and save.
2. **Create the instance** **APIs & Logic → Instance API (DB API)** → add an instance : pick the database type, give it a name, and pick the key of the secret under **Connection**.
3. **Test it** **Test Instance** connects with the string. An instance which can not reach its database is not saved, and the form says why.

**Connection String Sandbox** is optional : a second key, for code which runs in a sandbox and reaches the database by another address than API Maker does.

## Common errors

| What you see | What to check |
|---|---|
| `Access denied for user 'app'@'10.0.0.2'` | The password, and a user allowed from the address of API Maker : `CREATE USER 'app'@'10.0.0.2'`, or `'app'@'%'`. |
| A timeout, or the connection refused | The server listens on the network (`bind-address`), the firewall lets API Maker in, the port is right. |
| `Invalid URL : …` | The string starts with `mysql://` or `mariadb://` and names a host. |
| The server asks for TLS | Not supported, see above. |

## Related

- [Secret Management](https://docs.apimaker.dev/v4/docs/secrets/secrets.html) · [MariaDB connection strings](https://docs.apimaker.dev/v4/docs/Database-connection-string/mariadb-connection-strings.html) · [Execute plain query](https://docs.apimaker.dev/v4/docs/apis-all/system-apis/system-generated-execute-plain-query-api.html)