diff --git a/docs/troubleshooting/manual-database-migration.md b/docs/troubleshooting/manual-database-migration.md index 21f8ea4..9236f9f 100644 --- a/docs/troubleshooting/manual-database-migration.md +++ b/docs/troubleshooting/manual-database-migration.md @@ -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.