diff --git a/enterprise/external-postgres.mdx b/enterprise/external-postgres.mdx index 76126aac..d2d7a57f 100644 --- a/enterprise/external-postgres.mdx +++ b/enterprise/external-postgres.mdx @@ -12,6 +12,27 @@ need specific backup/recovery procedures, or require high availability configura 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: + +```sql +-- Check current database encoding +SELECT datname, pg_encoding_to_char(encoding) AS encoding FROM pg_database; + +-- Create databases with explicit UTF8 encoding +CREATE DATABASE openhands WITH ENCODING 'UTF8'; +``` + +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: @@ -48,12 +69,12 @@ If your security policies prevent granting `CREATEDB`, you must manually create databases before installation: ```sql --- Create the databases -CREATE DATABASE openhands; -CREATE DATABASE bitnami_keycloak; -CREATE DATABASE litellm; -CREATE DATABASE runtime_api_db; -CREATE DATABASE automations; +-- Create the databases with UTF8 encoding +CREATE DATABASE openhands WITH ENCODING 'UTF8'; +CREATE DATABASE bitnami_keycloak WITH ENCODING 'UTF8'; +CREATE DATABASE litellm WITH ENCODING 'UTF8'; +CREATE DATABASE runtime_api_db WITH ENCODING 'UTF8'; +CREATE DATABASE automations WITH ENCODING 'UTF8'; -- Create user without CREATEDB CREATE USER openhands_user WITH PASSWORD 'your-secure-password';