Features
Database Export

Database Export

The Database Export feature allows you to export your Keycloak cluster’s PostgreSQL database for backup, migration, or analysis purposes. Exports are processed asynchronously and delivered as downloadable ZIP archives with optional encryption.

Plan Requirements

Database export is available on Launch, Startup, Business, Growth, and Enterprise plans. It is not available on Trial or Dev plans. Attempting to export on a restricted plan returns a 403 Forbidden response with upgrade instructions.

Initiating an Export

To start a database export, send a POST request to the cluster exports endpoint:

POST /api/clusters/{clusterId}/exports

Request Body

Field Type Required Description
format string No Export format: sql (default) or pgdump
includeCredentials boolean No Include user credentials and secrets in the export. Defaults to false
isEncrypted boolean No Encrypt the export file. Defaults to false
encryptionPassword string Conditional Required when isEncrypted is true. Must be at least 8 characters

Example Request 

{
  "format": "sql",
  "includeCredentials": true,
  "isEncrypted": true,
  "encryptionPassword": "my-secure-password"
}

Example Response 

{
  "export_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "pending",
  "message": "Export initiated successfully. You will receive an email when it's ready."
}

Important: When includeCredentials is set to true, encryption is mandatory. The API will reject requests that include credentials without enabling encryption.

Export Formats

Format Description Use Case
sql Plain SQL statements with DROP and CREATE commands Human-readable, easy to inspect and selectively restore
pgdump PostgreSQL custom binary format (pg_dump -Fc) Smaller file size, supports parallel restore with pg_restore

Both formats exclude ownership and access control information for portability across environments.

Credential Inclusion and Data Filtering

By default, exports exclude sensitive tables to protect user data:

  • user_entity – user account records
  • credential – user passwords and credentials
  • fed_user_credential – federated user credentials
  • client_secret – OAuth client secrets

When includeCredentials is enabled, these tables are included in the export. This is useful for full cluster migration but requires encryption to protect the sensitive data.

Encryption

Exports can be encrypted using AES-256-CBC with PBKDF2 key derivation (10,000 iterations, SHA-256). The encryption is OpenSSL-compatible, so you can decrypt using standard tools.

  • The encryption password must be at least 8 characters
  • Only a SHA-256 hash of the password is stored for validation – the password itself is never persisted
  • The encrypted file uses the OpenSSL Salted__ header format

Decrypting an Export

Use OpenSSL to decrypt an encrypted export file:

openssl enc -d -aes-256-cbc -pbkdf2 -iter 10000 -md sha256 \
  -in cluster-name_a1b2c3d4.zip.enc \
  -out cluster-name_a1b2c3d4.zip

You will be prompted for the encryption password you provided when initiating the export. After decryption, unzip the archive to access the database dump file.

Retrieving Exports

List All Exports for a Cluster 

GET /api/clusters/{clusterId}/exports

Returns all exports associated with the cluster, ordered by creation date.

Get a Specific Export 

GET /api/exports/{exportId}

Returns details for a single export, including download URL if the export is completed and not expired.

Export Summary Fields

Field Description
id Unique export identifier
format Export format (sql or pgdump)
status Current status (see below)
progress Completion percentage (0-100)
include_credentials Whether credentials are included
is_encrypted Whether the file is encrypted
file_size Size of the export file in bytes
download_url Pre-signed download URL (available when completed)
expires_at When the download link expires
error_message Error details if the export failed
created_at When the export was initiated
completed_at When the export finished processing

Progress Tracking and Status

Exports progress through the following statuses:

Status Description
pending Export has been queued and is waiting to be processed
processing Export is actively running (progress updates from 10% to 90%)
completed Export finished successfully and is ready for download
failed Export encountered an error. Check error_message for details

Poll the GET /api/exports/{exportId} endpoint to track progress. You will also receive an email notification when the export completes or fails.

Download and Expiration

Once an export completes, a pre-signed download URL is generated. The download link and the stored export file expire after 24 hours. After expiration, the file is automatically deleted from storage and the download URL becomes invalid.

To download after expiration, you must initiate a new export.

Checksum Verification

Each completed export includes a SHA-256 checksum. After downloading, verify the file integrity:

# Calculate the checksum of your downloaded file
sha256sum cluster-name_a1b2c3d4.zip

# Compare it with the checksum from the API response

The checksum is computed on the final file (encrypted ZIP if encryption was used, plain ZIP otherwise).

Email Notifications

You will receive an email when your export completes or fails:

  • Success: Includes a direct download link, file size, checksum, and expiration time
  • Failure: Includes a summary of the issue. The support team is automatically notified for investigation
Last updated on
Insights & AnalyticsExtensions