> For the complete documentation index, see [llms.txt](https://docs.lleverage.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.lleverage.ai/administer-and-govern/control/databases.md).

# Databases

Connect your Project to PostgreSQL or MySQL and run your first query.

Connect your Project to PostgreSQL or MySQL to read and update data from your Workflows. PostgreSQL also supports an SSH tunnel for access to a private database.

If you're setting up a new database in Azure, follow the [Azure PostgreSQL example](#example-private-postgresql-in-azure) below.

## Before you start

Ask your database administrator for:

* The database hostname, port, and database name.
* A database account with the read or write permissions your Workflow needs.
* The connection's TLS certificate requirements.

Before configuring firewall rules, contact Lleverage to confirm network access and the source IP addresses for your Project's database or SSH connection. The usual ports are **5432 for PostgreSQL**, **3306 for MySQL**, and **22 for SSH**.

Store credentials in your Project's [Secrets](/administer-and-govern/control/secrets.md). You can create multiple database connections; give each a clear name, such as `Reporting · Test` or `ERP · Production`.

## Connect PostgreSQL

### 1. Save your connection string

In your Project, open **Control → Secrets**. Create a Secret named `POSTGRES_CONNECTION_STRING`, or add a suffix such as `POSTGRES_CONNECTION_STRING_REPORTING`.

Use this connection-string format:

```
postgresql://USER:PASSWORD@HOST:5432/DATABASE?sslmode=verify-full
```

Replace `USER`, `PASSWORD`, `HOST`, and `DATABASE` with your database details. `sslmode=verify-full` enables TLS with certificate validation. If your database uses a private certificate authority, contact Lleverage to configure certificate trust.

URL-encode special characters in the username and password. For example, `demo@pass#1` becomes `demo%40pass%231`. Encode the credential components only.

### 2. Add the connection

1. Open **Control → Databases** in your Project.
2. Add a **PostgreSQL** connection.
3. Select your Secret for `POSTGRES_CONNECTION_STRING`.
4. Leave the SSH fields empty for a direct connection, or complete the SSH setup below.
5. Enter a connection name and select **Confirm**.

![PostgreSQL connection settings in Project Control.](https://3370306531-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FlgSglJDQZxDZdn20CUcl%2Fuploads%2FEbdVffEzaSfnG7pJJpZO%2Fcontrol-databases.png?alt=media)

### 3. Run your first query

Add a **Query Database** node to your Workflow, select your connection, and run:

```sql
SELECT 1 AS connection_ok;
```

A result containing `connection_ok: 1` confirms the connection works. Next, try a small query against one of your tables:

```sql
SELECT id
FROM your_table
LIMIT 5;
```

Replace the table and column names with your own. Your database account must have permission to read that table.

## Connect private PostgreSQL through SSH

Use an SSH server, also called a jump host or bastion, to reach a private PostgreSQL database:

```
Lleverage → SSH server → PostgreSQL
```

The SSH server must be reachable from Lleverage and able to connect to the database. Your administrator should:

1. Allow Lleverage's agreed source IP addresses to reach the SSH port.
2. Configure an SSH account and allow TCP forwarding to the database.
3. Ensure the SSH server can resolve the database hostname and reach its database port.
4. Allow the database to accept connections from the SSH server.

### Add the SSH settings

In your Project's PostgreSQL connection, select values for these fields. Save passwords, private keys, and passphrases as **Secrets**. Hostnames, ports, and usernames can use Project **Variables**.

| Field                         | What to enter                                                |
| ----------------------------- | ------------------------------------------------------------ |
| `POSTGRES_SSH_HOST`           | SSH server hostname or IP address.                           |
| `POSTGRES_SSH_PORT`           | SSH port; defaults to `22`.                                  |
| `POSTGRES_SSH_USER`           | Username on the SSH server.                                  |
| `POSTGRES_SSH_KEY`            | Private key for key-based authentication.                    |
| `POSTGRES_SSH_KEY_PASSPHRASE` | Passphrase, if the private key is encrypted.                 |
| `POSTGRES_SSH_PASSWORD`       | Password, if using password authentication instead of a key. |

Name each Secret or Variable after its field, optionally adding a suffix such as `_REPORTING`. Fill in both the SSH host and username, and choose either key or password authentication.

For a private key, paste the complete PEM content into a multiline Secret, preserving its BEGIN/END lines and line breaks. Your administrator places the matching public key on the SSH server.

Keep the **database hostname** in `POSTGRES_CONNECTION_STRING` and the **SSH server hostname** in `POSTGRES_SSH_HOST`. The database credentials remain in the connection string; the SSH fields contain the separate SSH login details.

Keep `sslmode=verify-full` in the PostgreSQL URL so the database connection also uses validated TLS. Save the connection and run the test query above.

### Example: private PostgreSQL in Azure

This setup keeps PostgreSQL on a private network and connects Lleverage through an SSH jump host. Use **Azure Database for PostgreSQL Flexible Server** for the database and a small Linux VM for SSH access. An existing suitable SSH host can also be used.

```
Lleverage → Linux VM in Azure → Azure PostgreSQL
            SSH on port 22      Private access on port 5432
```

**1. Create the database.** In Azure, create a PostgreSQL Flexible Server and choose **Private access (VNet integration)**. Place it in a subnet delegated to PostgreSQL and link its private DNS zone to the virtual network. Choose compute, storage, backups, and availability for your workload. Azure's [private-access setup guide](https://learn.microsoft.com/en-us/azure/postgresql/connectivity/quickstart-create-connect-server-vnet) covers resource creation.

**2. Create a database login.** Enable PostgreSQL password authentication for this connection. Create your application database and a dedicated login with the table or procedure permissions your Workflow needs. Keep the server administrator account for administration.

**3. Set up the SSH host.** Create a Linux VM in a separate subnet in the same virtual network. Give it a stable public IP address or DNS name and configure a dedicated SSH user with key authentication. Allow SSH forwarding to the PostgreSQL hostname on port `5432`. The VM must remain running for Workflows to connect. This example uses a normal SSH-enabled VM; Azure Bastion is not required.

**4. Configure network access.** In the VM's network security group, restrict inbound TCP `22` to the source IP addresses supplied by Lleverage. Permit the VM to reach PostgreSQL on TCP `5432`, preserving Azure's required service traffic. From the VM, confirm that the PostgreSQL hostname resolves to a private IP and that the database login can connect. The VM belongs in a different subnet because Azure reserves the delegated database subnet for PostgreSQL. See [Azure networking requirements](https://learn.microsoft.com/en-us/azure/postgresql/network/concepts-networking-private).

**5. Add the connection in your Project.** Follow the PostgreSQL and SSH steps above, using these values:

| Lleverage field              | Azure value                                                                                                        |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| `POSTGRES_CONNECTION_STRING` | Database URL using the server hostname copied from Azure, the dedicated database login, and `sslmode=verify-full`. |
| `POSTGRES_SSH_HOST`          | Linux VM's public IP address or DNS name.                                                                          |
| `POSTGRES_SSH_USER`          | Dedicated SSH username on the VM.                                                                                  |
| `POSTGRES_SSH_KEY`           | Private key matching the public key configured for that user.                                                      |

An example database URL is:

```
postgresql://USER:PASSWORD@my-server.postgres.database.azure.com:5432/appdb?sslmode=verify-full
```

Store the URL and key in Project Secrets, supply the key passphrase if needed, and run `SELECT 1 AS connection_ok;` from your Workflow. Then test a limited read from your application table. Keep certificate validation enabled; Azure documents its [TLS requirements](https://learn.microsoft.com/en-us/azure/postgresql/security/security-tls).

If you already use an IP-restricted public PostgreSQL endpoint, you can follow the direct connection steps instead. Confirm network access with Lleverage first. For an existing private database, reuse its network setup and a suitable SSH host where possible.

## Connect MySQL

Use a full MySQL connection URL stored in a Project Secret.

1. Open **Control → Secrets** and create `MYSQL_CONNECTION_STRING`.
2. Save your MySQL URL as its value. The example below enables TLS with certificate and hostname validation:

```
mysql://USER:PASSWORD@HOST:3306/DATABASE?ssl=%7B%22rejectUnauthorized%22%3Atrue%2C%22verifyIdentity%22%3Atrue%7D
```

Replace the credentials, host, and database. URL-encode special characters in the credentials. If your server uses a private certificate authority, contact Lleverage for the certificate configuration.

3. Add a new **Query Database** node to your Workflow.
4. Select **Toggle editor** beside **Connection String** and enter:

```
{{_secret.MYSQL_CONNECTION_STRING}}
```

5. Run `SELECT 1 AS connection_ok;` to test the connection.

The SSH setup on this page applies to PostgreSQL. For private MySQL access, contact Lleverage to arrange the network connection.

## Troubleshooting

| Problem                                  | What to check                                                                                                              |
| ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| Connection or Secret is missing          | Check that it was saved in the correct Project. For PostgreSQL fields, use the matching Secret-name prefix.                |
| Connection times out                     | Hostname, port, firewall rules, and the source IP addresses agreed with Lleverage.                                         |
| SSH login fails                          | SSH username, password or key, and key passphrase. Select one authentication method.                                       |
| Private key is rejected                  | Save the complete private key in a multiline Secret with its original line breaks.                                         |
| SSH connects but PostgreSQL fails        | The SSH server's private DNS, forwarding permissions, database access, and database credentials.                           |
| Certificate error                        | Database hostname, certificate validity, and trusted certificate authority. Contact Lleverage if a private CA is required. |
| PostgreSQL reports “no encryption”       | Include the TLS settings in the database connection string, including when using SSH.                                      |
| Login fails                              | Database credentials, account access rules, and URL encoding of the password.                                              |
| Test query works but a table query fails | Database, table and column names, and the account's read or write permissions.                                             |

Use the source IP addresses supplied specifically for your database or SSH connection when configuring firewalls. An IP supplied for HTTP API traffic may belong to a different network route.

Start with a new Query Database node when testing a different connection. Keep queries small with `LIMIT`, and retest after changing credentials or network settings.

If you need help, send [Support](/reference/troubleshooting-and-support.md) your Project, Workflow run, database type, connection method, and error message. Remove passwords and private keys before sharing.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.lleverage.ai/administer-and-govern/control/databases.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.