> 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/administration-guide/platform/backup-and-restore-scope.md). # What a backup and restore must cover What a recoverable copy of OpenIAM actually consists of — the seven schemas, the vault, files on disk and OpenSearch — and the one version check that exists. ## What this is, and when you need it Taking the backup is deployment work: it needs access to the database hosts, and a genuinely consistent set needs the back-end services stopped or a replica at a known position. That procedure belongs to the [Installation Guide](/installation/installation.md). What belongs here is the **scope**, because an incomplete list is the failure you will actually meet — and the scope is something you can check without shell access, by asking whoever runs the backup which of five things it covers. Read this before you plan a restore, a disaster-recovery test, or a [promotion between environments](/administration-guide/platform/import-export-and-promotion.md), all three of which assume the target can be put back. ## It is not one database OpenIAM stores its state in **seven separate database schemas**, each with its own connection and its own migration history. The inventory and what each one holds is in [Diagnose a failed operation](/administration-guide/operations/diagnose-a-failed-operation.md#the-seven-database-schemas). Two corrections to make before you plan anything against that table: * **The `auditlog` schema does not contain the audit log.** It holds only the audit *export* connector configuration — `AUDIT_EXPORT_CONNECTOR`, `AUDIT_EXPORT_CONNECTOR_ACTION`, `AUDIT_EXPORT_FAILED_DISPATCH` — and that schema's own `OPENIAM_VERSION`. Audit events themselves are OpenSearch documents; the database tables that once held them were dropped in 4.2.0.0. **Backing up all seven schemas does not back up your audit trail.** See [Find audit evidence](/administration-guide/operations/find-audit-evidence.md). * **Each schema's migration history is tracked separately**, in that schema's own `OPENIAM_VERSION` table. There is no combined product version anywhere, so nothing detects a restore that mixes versions across schemas. Reading all seven values and recording them is the only check that exists. {% hint style="warning" %} **Break-glass, read-only, and the only version check available.** No screen in OpenIAM shows the schema versions, so `SELECT` the highest applied version from `OPENIAM_VERSION` in each of the seven schemas and record all seven together, before and after any restore or promotion. This is outside the supported path in that the table belongs to the migration tool rather than to the product, and its shape can change between releases; the cost of the read itself is nothing, and it is not audited, so nothing records that you looked. **Never write to it.** A hand-edited `OPENIAM_VERSION` makes the next upgrade either skip a migration or replay one, and neither failure will be attributed to this. {% endhint %} ## What a backup has to cover | What has to be covered | Why it is not optional | | ------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | | All seven schemas, from one point in time | Nothing in OpenIAM coordinates a cross-schema snapshot. Seven hot dumps taken one after another are seven different points in time | | The seven `OPENIAM_VERSION` values, recorded | Nothing anywhere detects a version-mismatched restore, so this is the only evidence you will have | | Files on disk: the workflow definitions, script files, properties files, migration trees and any UI label override | None of these is in any schema | | The vault | Secrets are referenced from object rows by key, never stored in them. An object restored without its vault entry is configuration that cannot authenticate | | OpenSearch, if you have an audit retention obligation | The audit indexes have no database source at all, so nothing rebuilds them | **The search indexes and the authorization graph are the exception: they are rebuildable, and you can rebuild them yourself.** The 32 indexes can be rebuilt from the database — see [Search indexes and the authorization graph](/administration-guide/reference/search-indexes.md) — with one exception, the `auditlog`, `auditlogtargets` and `auditlogattribute` indexes, which have no database source. The JanusGraph store behind effective access is also rebuildable, though from no screen — it is a single request against `openiam-esb`; see [Rebuild the authorization graph](/administration-guide/operations/rebuild-the-authorization-graph.md). Back either store up only if fast recovery matters more than rebuild time; otherwise plan the rebuild into your RTO and confirm afterwards that `REINDEX` audit events completed rather than merely started. {% hint style="danger" %} **Restore consistency, stated as the symptoms you will see.** A restore of `openiam` alone leaves every in-flight approval orphaned (that state is in `activiti`), every stored script referenced by a managed system or business rule missing (`groovy`), every campaign broken (`certification`) and every batch task's history gone (`batchtasks`). All seven have to come back from the same point in time, and the seven `OPENIAM_VERSION` values then have to match what you recorded. Reindex OpenSearch and rebuild the authorization graph before you let users back in. **Audit history is not restored by any of this** — it lives in OpenSearch, and deleted audit history is not recoverable from a database backup at all. {% endhint %} ## Related * [Promote configuration between environments](/administration-guide/platform/import-export-and-promotion.md) — the utility, and the four categories a promotion has to cover * [Diagnose a failed operation](/administration-guide/operations/diagnose-a-failed-operation.md) — the seven schemas and what each one holds * [Find audit evidence](/administration-guide/operations/find-audit-evidence.md) — why the audit trail is not in any of them * [Search indexes and the authorization graph](/administration-guide/reference/search-indexes.md) — what you rebuild rather than restore *Applies to OpenIAM 2026.8.1. Last reviewed 7 August 2026.* --- # 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/administration-guide/platform/backup-and-restore-scope.md?ask=&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.