---
sidebar_position: 900
title: Manual Alembic Database Migration Guide
---

This guide provides step-by-step instructions for manually applying Alembic database migrations in Open WebUI. Migrations are typically run automatically on startup, but you may need to run them manually for maintenance, debugging, or deployment scenarios.

## Prerequisites

- Ensure you have a Python environment with Open WebUI dependencies installed.
- Your database connection must be configured via the `DATABASE_URL` environment variable.
- You need access to the backend directory of your Open WebUI installation.

## Accessing the Container (for Docker installations)

If you are running Open WebUI in a Docker container, you'll first need to get a shell into the container:

```bash
docker exec -it open-webui /bin/bash
```

:::note
Replace `open-webui` with the name of your container if it's different.
:::

## Manual Migration Commands

This section provides instructions for running Alembic commands. The correct directory path depends on whether you are running Open WebUI from a local installation or within a Docker container.

### 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
```

:::info
All subsequent Alembic commands must be run from this directory (`/app/backend/open_webui` inside the container or `backend/open_webui` in a local setup), where the `alembic.ini` file is located.
:::

### 2. Set Environment Variables (Docker Only)

:::danger[Critical Step for Docker Users]
When you open a shell in a Docker container with `docker exec`, the application's environment variables are **not** automatically loaded. You must set them manually before running any Alembic commands to avoid errors.
:::

You will need to export the following variables:

1. `PYTHONPATH`: This tells Python where to find the application's modules.
2. `DATABASE_URL`: This is the connection string for your database.
3. `WEBUI_SECRET_KEY`: This is a required variable for the application's authentication system.

You can find the values for `DATABASE_URL` and `WEBUI_SECRET_KEY` in your `docker-compose.yaml` file or the `docker run` command you used to start the container.

Before proceeding, export the variables in your container shell:

```bash
export PYTHONPATH=.:../
export DATABASE_URL="your-database-url-here"
export WEBUI_SECRET_KEY="your-secret-key-here"
```

For example, for a PostgreSQL database, it might look like this:

```bash
export PYTHONPATH=.:../
export DATABASE_URL="postgresql://user:password@host:port/database"
export WEBUI_SECRET_KEY="t0p-s3cr3t"
```

### 3. Check the Current Database Revision

To see the current revision of your database, run:

```bash
alembic current
```

### 4. Apply All Pending Migrations (Upgrade)

To upgrade your database to the latest version, which applies all pending migrations, run:

```bash
alembic upgrade head
```

### 5. Upgrade to a Specific Revision

You can upgrade to a specific migration by providing its revision ID:

```bash
alembic upgrade <revision_id>
```

### 6. Downgrade to the Previous Revision

To revert the last migration, use:

```bash
alembic downgrade -1
```

### 7. Downgrade to a Specific Revision

You can also downgrade to a specific revision:

```bash
alembic downgrade <revision_id>
```

### 8. View Migration History

To see the history of all migrations, including their revision IDs, run:

```bash
alembic history
```

:::tip
The `alembic history` command is useful for finding the revision ID to use with the `upgrade` and `downgrade` commands.
:::

## Common Scenarios

### Fresh Database Setup

For a new database, run the following command to apply all migrations:

```bash
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`

### Production Deployment

When deploying to a production environment:

:::danger[Backup Your Database]
**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`.

## Troubleshooting

### `InvalidForeignKey` Error

If you encounter an error similar to `sqlalchemy.exc.ProgrammingError: (psycopg2.errors.InvalidForeignKey) there is no unique constraint matching given keys for referenced table "user"`, it's likely that a primary key constraint is missing on the `user` table.

To fix this, you need to connect to your PostgreSQL database and run the following SQL command:

```sql
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.

### Migrations in Multi-Server Deployments

:::warning[Update All Instances Simultaneously]
If you are running Open WebUI in a load-balanced, multi-server environment, it is critical that you **update all instances of the application at the same time.**

A rolling update, where servers are updated one by one, can cause service disruptions. If the first server to be updated applies a destructive migration (e.g., dropping a column), all other servers still running the old code will immediately encounter errors, as they will be trying to access a database schema that is no longer compatible.
:::

### 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.

### Database Connection

Verify that your `DATABASE_URL` environment variable is correctly set and that the database is accessible from where you are running the commands.

## Notes

:::note
The application automatically runs migrations on startup via the `run_migrations()` function in `config.py`. Manual migrations are useful for debugging, controlled deployments, or when automatic migration is disabled.
:::

- Some migrations include data transformation logic that may take a significant amount of time to run on large datasets.