> For the complete documentation index, see [llms.txt](https://docs.openiam.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.openiam.com/installation/rpm/rpm-single-node/use-a-remote-database.md).

# Use a remote database

Run OpenIAM against your own database server — what to provision, what privileges are needed, and what changes in the installation.

OpenIAM runs against a database server you provide and administer. This is the usual choice where database administration is a separate function, where the organisation has a standard for backup and recovery, or where a managed database service is already in use.

## What this covers, and how long it takes

<table><thead><tr><th width="146.8000030517578"></th><th></th></tr></thead><tbody><tr><td><strong>You get</strong></td><td>An OpenIAM deployment using your own database server rather than one installed on the platform host</td></tr><tr><td><strong>Time</strong></td><td>30 minutes of database preparation, before the installation</td></tr><tr><td><strong>Hosts</strong></td><td>The platform host, plus your database server</td></tr><tr><td><strong>Downtime</strong></td><td>None on the database server</td></tr><tr><td><strong>Reversible</strong></td><td>Yes — the choice is made during installation</td></tr></tbody></table>

## Before you start

**Must exist**

* A database server on one of the supported platforms — MariaDB, MySQL, PostgreSQL, Microsoft SQL Server or Oracle. Versions are in [*System requirements*](/installation/system-requirements.md). Managed services on AWS and Azure are supported — [*Managed databases*](/installation/rpm/cloud/managed-databases.md) covers which service for which engine.
* Network access from the platform host to the database server on its listening port — 3306 for MySQL and MariaDB, 5432 for PostgreSQL, 1433 for SQL Server, 1521 for Oracle.
* An administrative database account able to create databases, create users and grant privileges.

**Must be decided**

* **The platform.** Fixed after installation, so confirm which your organisation will support long term. On Oracle, decide whether you will connect by SID or by service name — the installation asks.
* **Where the schemas live.** OpenIAM uses eight schemas, and they are hosted on **one database server**. Plan for one server rather than distributing schemas across several.

## Set these first

{% code overflow="wrap" %}

```bash
export DB_HOST=<your database server>
export DB_PORT=<3306, 5432, 1433 or 1521>
export DB_ADMIN=<an administrative account on that server>
```

{% endcode %}

**These are used to prepare the database, not stored by OpenIAM.** The platform's own accounts are created below and held in the secret store.

***

## What OpenIAM creates

Eight schemas, each serving a part of the platform:

<table><thead><tr><th width="234.79998779296875">Schema</th><th>Holds</th></tr></thead><tbody><tr><td><code>openiam</code></td><td>The core identity and access model</td></tr><tr><td><code>activiti</code></td><td>Workflow process state</td></tr><tr><td><code>groovy</code></td><td>Managed scripts</td></tr><tr><td><code>auditlog</code></td><td>Audit records</td></tr><tr><td><code>batchtasks</code></td><td>Scheduled task definitions and history</td></tr><tr><td><code>pbac</code></td><td>Policy-based access control data</td></tr><tr><td><code>certification</code></td><td>Access certification campaigns</td></tr><tr><td><code>privacy</code></td><td>Privacy and consent records</td></tr></tbody></table>

**Use the default names.** They are what the installation and every service expect, and keeping them makes support and upgrades straightforward.

***

## Build it

### 1. Confirm the server is reachable from the platform host

{% code overflow="wrap" %}

```bash
# MySQL / MariaDB
mysql -h "$DB_HOST" -u "$DB_ADMIN" -p -e "SELECT VERSION();"

# PostgreSQL
psql -h "$DB_HOST" -U "$DB_ADMIN" -c "SELECT version();"
```

{% endcode %}

**What you should see:** the server version. If the connection is refused, resolve network access and the server's host-based access rules before continuing.

### 2. Create the administrative account OpenIAM will use, if you are not using an existing one

The installation creates the eight schemas and their application users. The account you give it needs permission to do that.

{% code overflow="wrap" %}

```sql
-- MySQL / MariaDB
CREATE USER '<openiam-admin>'@'<platform-host>' IDENTIFIED BY '<password>';
GRANT ALL PRIVILEGES ON *.* TO '<openiam-admin>'@'<platform-host>' WITH GRANT OPTION;
FLUSH PRIVILEGES;
```

{% endcode %}

{% code overflow="wrap" %}

```sql
-- PostgreSQL
CREATE ROLE <openiam-admin> WITH LOGIN CREATEDB CREATEROLE PASSWORD '<password>';
```

{% endcode %}

**What you should see:** the statements complete without error.

**On PostgreSQL, confirm host-based authentication allows the platform host** in `pg_hba.conf`, and reload the server after any change.

**On a managed service — Amazon RDS or Azure Database** — set the instance parameter `log_bin_trust_function_creators` to `1` on RDS or `ON` on Azure beforehand, so the schema migration can create stored functions, and answer `y` when the installation asks whether this is a cloud-hosted database. **That question applies to MySQL and MariaDB**; on the other engines answer `n`. [*Managed databases*](/installation/rpm/cloud/managed-databases.md) has the full sequence.

### 3. Answer the installation prompts accordingly

During `openiam-cli init`:

* **"Would you like to install MariaDB RDBMS locally?"** — answer **`n`**.
* **Engine** — type your engine at the prompt: `mysql`, `postgres`, `mssql` or `oracle`. It offers `mysql`; **type your choice rather than pressing Enter**, because this is fixed for the life of the deployment.
* **"Do you want to initialize OpenIAM Schema and Users?"** — `y` if the schemas do not yet exist. It then asks for a database super-user name and password, which it uses once and does not store.
* **"Are you going to use external DB service…?"** — `y` for a managed service, per step 2.
* **Schema names** — accept the defaults.
* **Host and port** — asked **once per schema, eight times**. On a single database server, give the same answer each time. Anything you skip stays at `localhost`, which is what you are moving away from.

**To answer the host and port once instead of eight times**, set all sixteen values in `/usr/local/openiam/env.conf` before you start. The prompts then offer your values as the defaults and you press Enter through them:

{% code overflow="wrap" %}

```
export FLYWAY_DATABASE_TYPE=mysql      # mysql | postgres | mssql | oracle
for s in OPENIAM ACTIVITI GROOVY AUDITLOG BATCHTASKS PBAC CERTIFICATION PRIVACY; do
  export FLYWAY_${s}_HOST=$DB_HOST
  export FLYWAY_${s}_PORT=3306
done
```

{% endcode %}

Set them as literal `export` lines in `env.conf` rather than a loop — the loop above shows which sixteen variables to write.

### 4. Run the initialisation SQL when the installation asks

**On MySQL and MariaDB** the installation creates the schemas and their application users for you, and this step does not apply.

**On PostgreSQL, SQL Server and Oracle** the installation writes the statements to `/tmp/init.sql` on the platform host and pauses:

{% code overflow="wrap" %}

```
Please perform script located at /tmp/init.sql to initialize Database MANUALLY.
File contains secrets! Remove it after initialization.
Press enter to continue database initialization
```

{% endcode %}

**Have a second terminal open** so you can act without losing the installation session:

{% code overflow="wrap" %}

```bash
# PostgreSQL
psql -h "$DB_HOST" -U "$DB_ADMIN" -f /tmp/init.sql

# SQL Server
sqlcmd -S "$DB_HOST" -U "$DB_ADMIN" -i /tmp/init.sql

# Oracle
sqlplus $DB_ADMIN@$DB_HOST @/tmp/init.sql
```

{% endcode %}

Then **delete the file** — it contains the credentials for the eight application accounts:

{% code overflow="wrap" %}

```bash
shred -u /tmp/init.sql
```

{% endcode %}

Return to the installation and press Enter.

### 5. On PostgreSQL, grant schema privileges

PostgreSQL needs one grant per database that the initialisation SQL does not make. For each of the eight:

{% code overflow="wrap" %}

```sql
ALTER ROLE <schema-user> SET search_path TO public;
GRANT USAGE  ON SCHEMA public TO <schema-user>;
GRANT CREATE ON SCHEMA public TO <schema-user>;
```

{% endcode %}

Without these, the schema migration cannot create objects.

### 6. On Oracle, create the schemas and users first

Oracle deployments create the `openiam` and `activiti` users and their schemas before the installation runs, following your organisation's standards for tablespaces and quotas. The installation reminds you when you select Oracle.

Set either the SID or the service name — whichever your database uses:

{% code overflow="wrap" %}

```
export FLYWAY_ORACLE_SID=<sid>
# or
export FLYWAY_ORACLE_SERVICE_NAME=<service-name>
```

{% endcode %}

### 7. Let the migration run

The installation applies the full schema definition to all eight schemas. This is the longest part of the database work and needs nothing further from you.

***

## Verify it

After the installation, from the platform host:

{% code overflow="wrap" %}

```bash
# MySQL / MariaDB
mysql -h $DB_HOST -u <openiam-admin> -p -e "SHOW DATABASES;"

# PostgreSQL
psql -h $DB_HOST -U <openiam-admin> -c "\l"
```

{% endcode %}

**Expected:** all eight schemas present.

Then confirm the platform is using them — the schema version table is populated once migration completes:

{% code overflow="wrap" %}

```bash
mysql -h $DB_HOST -u <openiam-admin> -p openiam \
  -e "SELECT version, description, success FROM flyway_schema_history ORDER BY installed_rank DESC LIMIT 5;"
```

{% endcode %}

**Expected:** recent rows, all with `success` set.

## If it goes wrong

| What you see                              | What it means                                       | What to do                                                                                               |
| ----------------------------------------- | --------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| Connection refused from the platform host | Network path or server access rules                 | Confirm the port is open and the server accepts connections from the platform host's address             |
| `Access denied` during installation       | The account cannot create databases or users        | Grant the privileges in step 2 and run the installation again                                            |
| PostgreSQL authentication failure         | `pg_hba.conf` does not cover the platform host      | Add an entry for the host and reload the server                                                          |
| Fewer than eight schemas afterwards       | The installation did not complete its database step | Check the installation output for the database section, correct the cause, and run again on a clean host |

## Operating the database

Once the deployment is running, the database is yours to operate as you would any other production database:

* **Back it up on your standard schedule.** OpenIAM does not back up the database.
* **Include all eight schemas** in the backup set and in any restore test.
* **Restore them together.** They are one logical dataset, and a partial restore leaves the platform inconsistent.

## On a managed cloud database

[*Managed databases*](/installation/rpm/cloud/managed-databases.md) covers the supported services on AWS and Azure, the engine parameters to set before you install, and the one prompt that changes what the installation asks your database for.

## What this procedure does not cover

Provisioning the database server, its availability, and its backups. On AWS and Azure, [*Managed databases*](/installation/rpm/cloud/managed-databases.md) covers the engines and the parameters that must be set. Installation continues on [*Install*](/installation/rpm/rpm-single-node/install.md).

## Related

* [*Install*](/installation/rpm/rpm-single-node/install.md)
* [*Start and verify*](/installation/rpm/rpm-single-node/start-and-verify.md)
* [*Settings*](/installation/settings.md)

*Applies to OpenIAM 2026.8.1.*


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.openiam.com/installation/rpm/rpm-single-node/use-a-remote-database.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.