khanh.pndc/open-webui-docs
1
0
Fork 0
mirror of https://github.com/open-webui/docs.git synced 2025-12-12 07:29:49 +07:00
Code Issues Packages Projects Releases Wiki Activity

Update manual-database-migration.md

Browse Source
This commit is contained in:
silentoplayz
2025-11-28 06:22:26 -05:00
parent 627a6d1eee
commit 173422191c
1 changed files with 22 additions and 7 deletions
Download Patch File Download Diff File Expand all files Collapse all files

29
docs/troubleshooting/manual-database-migration.md
View File

@@ -30,13 +30,17 @@ This section provides instructions for running Alembic commands. The correct dir
### 1. Navigate to the Correct Directory
#### Local Installation
If you are running Open WebUI from a local clone of the repository, navigate to the `backend/open_webui` directory from the repository root:
```bash
cd backend/open_webui
```
#### Docker Container
After accessing the container with `docker exec`, you will be in the `/app/backend` directory. From there, navigate to the `open_webui` directory:
```bash
cd open_webui
```
@@ -110,11 +114,12 @@ alembic upgrade head
### Specific Migration Issues
If a migration fails, you can resolve it with the following steps:
1. Check the current revision: `alembic current`
2. Identify the problematic revision from the error message.
3. Downgrade to the previous revision: `alembic downgrade -1`
4. Fix the underlying issue (e.g., a missing constraint).
5. Run the upgrade again: `alembic upgrade head`
1. Check the current revision: `alembic current`
2. Identify the problematic revision from the error message.
3. Downgrade to the previous revision: `alembic downgrade -1`
4. Fix the underlying issue (e.g., a missing constraint).
5. Run the upgrade again: `alembic upgrade head`
### Production Deployment
@@ -124,8 +129,8 @@ When deploying to a production environment:
**Always back up your database before running migrations in a production environment.**
:::
1. Run migrations during a maintenance window to avoid service disruptions.
2. Verify the migration was successful with `alembic current`.
1. Run migrations during a maintenance window to avoid service disruptions.
2. Verify the migration was successful with `alembic current`.
## Troubleshooting
@@ -141,6 +146,16 @@ ALTER TABLE public."user" ADD CONSTRAINT user_pk PRIMARY KEY (id);
After running this command, you can retry the `alembic upgrade head` command.
### Incorrect Autogenerated Migrations
When creating a new migration, the `alembic revision --autogenerate` command can sometimes create an incorrect migration file that attempts to drop existing tables. This can happen if Alembic has trouble detecting the current state of your database schema.
If you encounter this issue, here are a few things to try:
1. **Ensure Your Database is Up-to-Date:** Before generating a new migration, make sure your database is fully upgraded to the latest revision by running `alembic upgrade head`. An out-of-date database is a common cause of this problem.
2. **Create a Manual Migration:** For simple changes, you can avoid `--autogenerate` altogether by creating a manual migration file. This gives you full control over the `upgrade()` and `downgrade()` functions.
3. **Start Fresh:** If your database schema is in a state that is difficult to recover from, the simplest solution may be to start with a fresh installation.
### Migration Path Issues
If you encounter path resolution issues, ensure you are running the `alembic` commands from the correct directory (`open_webui` inside the Docker container, or `backend/open_webui` in a local setup) where the `alembic.ini` file is located.