Skip to main content
OpenHands Enterprise can connect to an external PostgreSQL instance instead of using the bundled database. This is useful when you have existing database infrastructure, need specific backup/recovery procedures, or require high availability configurations.

PostgreSQL Version

OpenHands Enterprise requires PostgreSQL 16.4.0 or above. PostgreSQL 17 is also supported.

Database Encoding Requirement

All databases used by OpenHands Enterprise must use UTF8 encoding. Using other encodings (such as LATIN1) will cause database migrations to fail during installation or upgrades.
When creating databases manually or configuring your PostgreSQL instance, ensure UTF8 encoding is set:
If your PostgreSQL server’s default encoding is not UTF8, you may need to specify the encoding explicitly when creating each database, or configure the server’s default encoding.

Required Databases

OpenHands Enterprise uses the following databases:
DatabasePurpose
openhandsCore application data
bitnami_keycloakIdentity and access management
litellmLLM proxy configuration and usage tracking
runtime_api_dbRuntime/sandbox management
automationsScheduled tasks and automation workflows

Database User Requirements

The PostgreSQL user provided to OpenHands Enterprise needs specific privileges depending on your preferred setup approach. If you provide a database user with the CREATEDB privilege, OpenHands Enterprise will automatically create all required databases during installation.
When the user creates its own databases, it will automatically have all necessary privileges on them including the ability to manage the public schema.

Option 2: Manual Database Creation

If your security policies prevent granting CREATEDB, you must manually create all databases before installation:

Network Requirements

Ensure your PostgreSQL instance is accessible from:
  • The OpenHands application pods/services
  • The Keycloak service
  • The LiteLLM proxy service
  • The Runtime API service
If using network policies or firewalls, allow connections on the PostgreSQL port (default: 5432) from the OpenHands deployment.

Configuration

When configuring OpenHands Enterprise, provide your external PostgreSQL connection details in the Admin Console or Helm values:
  • Host: Your PostgreSQL server hostname or IP
  • Port: PostgreSQL port (default: 5432)
  • Username: The database user created above
  • Password: The user’s password
For production deployments, we recommend enabling SSL/TLS for database connections.