gem-hunter
Language: Python
Interactive, locally hosted tool to migrate Open-WebUI SQLite databases to PostgreSQL
A robust, straightforward and fully interactive tool for migrating Open WebUI databases from SQLite to PostgreSQL. Designed for reliability and ease of use.
openwebui_postgres_migration.mov
All of them, including 0.11.3. There is no version pin and no supported-version list to keep current.
The tool never hard-codes a schema. It discovers the tables in your SQLite file, reads each column type from PostgreSQL, and derives the migration order from PostgreSQL's own foreign key graph, so whatever schema your Open WebUI release created is what gets migrated.
The only requirement is that both databases are created by the same Open WebUI version: bootstrap PostgreSQL by starting your existing Open WebUI build with DATABASE_URL set, then run the migration. If a table or column in your SQLite file is missing from PostgreSQL, the pre-flight check stops and names it, which usually means the two sides were created by different versions.
Run directly without installation:
uvx open-webui-postgres-migration
Clone the repository:
git clone https://github.com/taylorwilsdon/open-webui-postgres-migration.git
cd open-webui-postgres-migrationSet up environment:
python -m venv venv source venv/bin/activate # Windows: venv\Scripts\activate pip install -r requirements.txt
Run the migration:
python migrate.py
Before migration
DATABASE_URL environment variable to your PostgreSQL connection string:
export DATABASE_URL="postgresql://user:password@host:port/dbname"set DATABASE_URL="postgresql://user:password@host:port/dbname"DATABASE_URL configured so it creates the tables.During migration
After migration
During the migration, you'll be prompted to configure:
SQLite database
PostgreSQL connection
Performance settings
| Issue | Solution |
|---|---|
| Connection failed | Check PostgreSQL credentials and firewall settings |
| Permission denied | Verify PostgreSQL user privileges |
| Memory errors | Reduce batch size in configuration |
| Encoding issues | Ensure proper database character encoding |
| Missing tables or columns reported before migration starts | PostgreSQL was never bootstrapped, or it was bootstrapped by a different Open WebUI version than the one that created your SQLite file |
Failed Foreign Key Check for chat_file or knowledge_file |
The migration skips orphaned attachment rows that reference deleted chats or knowledge bases and reports how many rows were skipped |
Contributions are welcome. Please feel free to submit a pull request.
This project is licensed under the MIT License. See the LICENSE file for details.
If you encounter issues: