opschain admin database import
Included from Basic tier
Merges an admin database export archive into a server through the ORDINARY
authorised lanes — the estate-scope sibling of admin nodes import. Nothing
bypasses RBAC: project subtrees replay through the node create endpoints
(the same importer as admin nodes import), identity through the v2 user/group services (user
CREATION stays on the v1 admin endpoint until its v2 twin lands),
authorisation and settings through the v2 services, scheduled windows
through the node maintenance endpoints. Existing records are SKIPPED, never
overwritten, and the command reports created/skipped per type. A group
named by the archive that does not exist on the target is created before
its members are added (the v2 lane never creates groups implicitly).
Replay order: global settings → users → group memberships → authorisation rules and policies (with attachments and assignments) → project subtrees → scheduled maintenance windows. Skip keys: a project code, a username, a group+member pair, a rule's name+path, a policy name. System policies are always skipped (a fresh install bootstraps its own), directory-provider users are skipped (they re-mirror on their next login), and an existing project is skipped wholesale — merge never reshapes a subtree.
The TARGET needs no quiesce: import IS ordinary authorised creation, and a quiesced target's write barrier would refuse these very requests — resume it first. An archive whose manifest format this binary does not know is refused (version skew it cannot replay). Run history in the archive is never imported; the archive remains the record of what ran.
Secrets never travelled, so afterwards re-enter git remote credentials, secured settings values and local user passwords (each created local user gets a generated password — reset it).
Credentials: the project/authorisation/settings lanes authenticate as the
ordinary logged-in user (the global --server / active context); the
users/groups lanes need the admin bearer (--auth-token, then
OPSCHAIN_ADMIN_TOKEN, then the token stored by opschain admin login).
Flags
| Flag | Meaning |
|---|---|
--auth-token <token> | Admin bearer token for the identity lanes (default: $OPSCHAIN_ADMIN_TOKEN, then the stored admin login token). |
--into-empty | Assert the target holds no projects yet, and also apply the archive's global settings document (otherwise the singleton settings document is skipped — merging it over a live estate has no safe semantics). |
Exit codes
| Code | Meaning |
|---|---|
| 0 | The merge completed; the created/skipped table was reported. |
| 1 | Unsupported archive format, --into-empty on a populated target, or any create lane failed (the error names the record). |
| 2 | Usage error — no server or no credential resolvable. |
Named errors
unsupported estate export format "..."— exit 1 (version skew).--into-empty was given but the target already holds projects— exit 1.
Examples
opschain admin database import estate.zip --into-empty
opschain admin database import estate.zip
See also
opschain docs cli/admin-database-export— producing the archive.opschain docs cli/admin-nodes-import— the single-subtree import this extends.