feat(docs): Add troubleshooting for PostgreSQL connection errors

modified:   docs/getting-started/env-configuration.md
	new file:   docs/troubleshooting/unboundlocalerror-in-postgresql.mdx

docs/getting-started/env-configuration.md

@@ -3173,6 +3173,8 @@ These variables are not specific to Open WebUI but can still be valuable in cert
 Supports SQLite and Postgres. Changing the URL does not migrate data between databases.
 Documentation on the URL scheme is available available [here](https://docs.sqlalchemy.org/en/20/core/engines.html#database-urls).
 
+If your database password contains special characters, please ensure they are properly URL-encoded. For example, a password like `p@ssword` should be encoded as `p%40ssword`.
+
 :::
 
 #### `DATABASE_SCHEMA`

docs/troubleshooting/unboundlocalerror-in-postgresql.mdx

@@ -0,0 +1,58 @@
+---
+title: UnboundLocalError with PostgreSQL Connection
+---
+
+## Problem
+
+When using PostgreSQL as the database, you might encounter an `UnboundLocalError` if the database connection information is incorrect. This typically happens when the application fails to establish a connection to the database, and the error handling logic doesn't properly manage the database connection variable.
+
+This issue is tracked on GitHub: [#14942](https://github.com/open-webui/open-webui/issues/14942)
+
+## Cause
+
+The error occurs because the `db` variable is referenced in the `finally` block before it has been assigned a value in the `try` block. This happens when an exception is raised during the `register_connection` call, for example, due to an invalid `DATABASE_URL`.
+
+## Solution
+
+A workaround has been implemented to handle the Peewee migration before the Alembic migration, which also includes more robust error handling to prevent this `UnboundLocalError`.
+
+Here is the code snippet that addresses the issue:
+
+```python
+# Workaround to handle the peewee migration
+# This is required to ensure the peewee migration is handled before the alembic migration
+def handle_peewee_migration(DATABASE_URL):
+    # db = None
+    try:
+        # Replace the postgresql:// with postgres:// to handle the peewee migration
+        db = register_connection(DATABASE_URL.replace("postgresql://", "postgres://"))
+        migrate_dir = OPEN_WEBUI_DIR / "internal" / "migrations"
+        router = Router(db, logger=log, migrate_dir=migrate_dir)
+        router.run()
+        db.close()
+
+    except Exception as e:
+        log.error(f"Failed to initialize the database connection: {e}")
+        log.warning(
+            "Hint: If your database password contains special characters, "
+            "please ensure they are properly URL-encoded."
+        )
+        raise
+    finally:
+        # Properly closing the database connection
+        if 'db' in locals() and db and not db.is_closed():
+            db.close()
+```
+
+### Key Changes
+
+1.  **Connection String Replacement**: The `DATABASE_URL` is modified to replace `postgresql://` with `postgres://`. This is a specific requirement for the `peewee` library to handle migrations correctly with PostgreSQL.
+2.  **Robust `finally` Block**: The `finally` block now checks if `db` was successfully assigned (`'db' in locals()`) before attempting to close the connection. This prevents the `UnboundLocalError` if the connection fails to initialize.
+
+### Important Hint for Passwords
+
+As noted in the code, if your database password contains special characters (e.g., `@`, `:`, `!`), you must ensure they are properly URL-encoded in your `DATABASE_URL` environment variable.
+
+For example, a password like `p@ssword` should be encoded as `p%40ssword`.
+
+You can find more information on this in the [Environment Variable Configuration](/getting-started/env-configuration.md#database-pool) documentation.