docs: Add UTF8 encoding requirement for external PostgreSQL#513
docs: Add UTF8 encoding requirement for external PostgreSQL#513jpshackelford wants to merge 1 commit into
Conversation
External PostgreSQL databases must use UTF8 encoding for OpenHands Enterprise to function correctly. Database migrations will fail during installation or upgrades if databases use other encodings (e.g., LATIN1). This documents: - A new 'Database Encoding Requirement' section with a warning callout - SQL commands to check existing database encoding - Updated manual database creation examples with explicit UTF8 encoding Co-authored-by: openhands <openhands@all-hands.dev>
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Workflows to automatically generate PRs for you. |
all-hands-bot
left a comment
all-hands-bot
left a comment
There was a problem hiding this comment.
🟢 Good taste - Clear documentation addressing a real customer issue.
This PR effectively documents the UTF8 encoding requirement that caused the C24 customer upgrade failure. The changes are well-structured:
- Warning callout appropriately emphasizes the criticality
- SQL examples are practical and verifiable (check encoding + create with UTF8)
- Updated all manual creation examples for consistency
- Proper placement after version requirements, before usage details
[RISK ASSESSMENT]
- [Overall PR]
⚠️ Risk Assessment: 🟢 LOW
Documentation-only change addressing a real production failure mode. No code or infrastructure changes. Backward compatible — existing UTF8 databases are unaffected.
VERDICT:
✅ Worth merging - Straightforward documentation improvement preventing future customer issues.
KEY INSIGHT:
This exemplifies good documentation practice: capturing production failure modes as preventive guidance with actionable verification steps.
Was this automated review useful? React with 👍 or 👎 to this review to help us measure review quality.
Workflow run: https://github.com/OpenHands/docs/actions/runs/26168951598
4 participants
Summary
This PR documents the UTF8 encoding requirement for external PostgreSQL databases used with OpenHands Enterprise.
Context
During a recent customer upgrade (C24, 0.7.3 → 0.7.16), the LiteLLM proxy container entered an error state due to failed database migrations. The root cause was identified as the external PostgreSQL database using LATIN1 encoding instead of UTF8.
Relevant Slack thread: https://allhandsai.slack.com/archives/C0A8MKT4RSA/p1779273466074369
Changes
Added a new "Database Encoding Requirement" section after the PostgreSQL Version section with:
Updated the manual database creation example in Option 2 to include explicit
WITH ENCODING 'UTF8'in allCREATE DATABASEstatements.Testing
This PR was created by an AI agent (OpenHands) on behalf of John-Mason Shackelford.
@jpshackelford can click here to continue refining the PR