Accounts, chats, and saved settings belong to Open WebUI's application database. PostgreSQL can hold those records separately from the web container, while the application's data volume retains its local files.

DATABASE_URL selects the database when Open WebUI starts, and startup migrations initialize an empty database. Changing that URL does not copy existing SQLite records. A fresh installation fits this setup; an installation with existing users or chats needs a separate backup and migration plan.

The Docker Compose project keeps PostgreSQL private and exposes Open WebUI only on the Docker host. Its data volume still holds uploads and other local files. A shared SQL database alone does not make those files or vector storage available to multiple application replicas.

Steps to configure PostgreSQL for Open WebUI:

  1. Create a separate Compose directory for the fresh installation.
    $ mkdir ~/open-webui-postgres

    This setup creates an empty application database. Existing SQLite accounts, chats, and settings remain in the old deployment; changing its database URL would make that data unavailable through the application. A protected backup and migration plan are required before changing an existing deployment. The old configuration and volumes provide the recovery path.
    Related: How to back up and restore Open WebUI data

  2. Change into the new project directory.
    $ cd ~/open-webui-postgres
  3. Create an owner-only .env file.
    $ install -m 600 /dev/null .env
  4. Generate the database passwords and application key directly into .env.
    $ printf 'COMPOSE_PROJECT_NAME=open-webui-postgres\nOPEN_WEBUI_PORT=3000\nPOSTGRES_ADMIN_PASSWORD=%s\nPOSTGRES_PASSWORD=%s\nWEBUI_SECRET_KEY=%s\n' "$(openssl rand -hex 32)" "$(openssl rand -hex 32)" "$(openssl rand -hex 32)" >| .env

    The file contains credentials and must stay outside version control and shared transcripts. Its original values belong in protected backups. Regenerating the application key can invalidate sessions and make encrypted credentials unreadable; changing an environment password does not reset a password in an initialized PostgreSQL volume.

    The generated hexadecimal passwords can be used directly in a connection URL. A manually chosen password containing reserved URL characters needs percent-encoding in DATABASE_URL, while PostgreSQL receives its original value.

  5. Create compose.yaml with separate persistent database and application volumes.
    ~/open-webui-postgres/compose.yaml
    services:
      postgres:
        image: postgres:16-alpine
        restart: unless-stopped
        environment:
          POSTGRES_PASSWORD: "${POSTGRES_ADMIN_PASSWORD:?set POSTGRES_ADMIN_PASSWORD}"
          OPEN_WEBUI_DATABASE_PASSWORD: "${POSTGRES_PASSWORD:?set POSTGRES_PASSWORD}"
        healthcheck:
          test: ["CMD-SHELL", "pg_isready -U postgres"]
          interval: 5s
          timeout: 5s
          retries: 10
        volumes:
          - postgres-data:/var/lib/postgresql/data
    
      open-webui:
        image: ghcr.io/open-webui/open-webui:v0.12.4
        restart: unless-stopped
        depends_on:
          postgres:
            condition: service_healthy
        healthcheck:
          start_period: 5m
        ports:
          - "127.0.0.1:${OPEN_WEBUI_PORT:-3000}:8080"
        environment:
          WEBUI_SECRET_KEY: "${WEBUI_SECRET_KEY:?set WEBUI_SECRET_KEY}"
          DATABASE_URL: "postgresql://openwebui:${POSTGRES_PASSWORD:?set POSTGRES_PASSWORD}@postgres:5432/openwebui"
        volumes:
          - open-webui:/app/backend/data
    
    volumes:
      postgres-data:
      open-webui:

    PostgreSQL has no published host port. The application connects to postgres:5432 over the private Compose network. Docker with the Compose plugin and OpenSSL must already be available.
    Tool: Docker Compose Healthchecks Checker

  6. Validate Compose without printing the resolved credentials.
    $ docker compose config --quiet

    A zero exit status with no output means the configuration parsed. Plain docker compose config includes resolved environment values.

  7. Pull the selected service images.
    $ docker compose pull
  8. Start PostgreSQL with its readiness check.
    $ docker compose up -d --wait postgres
  9. Create the application login without cluster administration privileges.
    $ docker compose exec -T postgres psql -U postgres -v ON_ERROR_STOP=1 <<'SQL'
    \getenv app_password OPEN_WEBUI_DATABASE_PASSWORD
    CREATE ROLE openwebui LOGIN NOSUPERUSER NOCREATEDB NOCREATEROLE NOREPLICATION PASSWORD :'app_password';
    CREATE DATABASE openwebui OWNER openwebui;
    SQL
    CREATE ROLE
    CREATE DATABASE

    The role owns only the new application's database and can create its migration tables. The postgres account remains the cluster administrator. These creation statements are for an empty installation and fail if the role or database already exists.

  10. Start Open WebUI against the new database.
    $ docker compose up -d --wait open-webui

    Startup runs the schema migrations. The five-minute healthcheck grace allows initial model downloads to finish. A startup error or timeout needs attention before account creation. For a later multi-replica deployment, startup migrations must finish on one instance before the others start.

  11. Check the startup log for the PostgreSQL migration backend.
    $ docker compose logs open-webui
    ##### snipped #####
    open-webui-1  | INFO  [alembic.runtime.migration] Context impl PostgresqlImpl.
    open-webui-1  | INFO  [alembic.runtime.migration] Will assume transactional DDL.
    ##### snipped #####

    PostgresqlImpl identifies the migration backend. It does not by itself prove that account and chat writes work.
    Related: How to view Open WebUI Docker logs

  12. Create the initial administrator through the local application API.

    The first account on an empty installation becomes its administrator. The local-only binding prevents remote visitors from claiming it. The password prompt hides input, and the response token goes into an owner-only temporary file inside the container.

    $ docker compose exec open-webui python -c '
    import getpass, json, os, urllib.request
    email = input("Administrator email: ")
    password = getpass.getpass("Administrator password: ")
    body = json.dumps({"name": "Database Admin", "email": email, "password": password}).encode()
    request = urllib.request.Request("http://127.0.0.1:8080/api/v1/auths/signup", data=body, headers={"Content-Type": "application/json"})
    account = json.load(urllib.request.urlopen(request))
    os.umask(0o077)
    with open("/tmp/postgresql-check.json", "x") as state:
        json.dump({"id": account["id"], "email": account["email"], "token": account["token"]}, state)
    print("Account created:", account["email"], account["role"])
    '
    Administrator email: admin@example.com
    Administrator password:
    Account created: admin@example.com admin

    The temporary file contains a session token. It must not be displayed or copied into logs. The container's bundled Python handles the request without adding a host dependency.

  13. Save a test chat through the authenticated application API.
    $ docker compose exec -T open-webui python -c '
    import json, urllib.request
    with open("/tmp/postgresql-check.json") as state:
        account = json.load(state)
    body = json.dumps({"chat": {"title": "PostgreSQL persistence check"}}).encode()
    headers = {"Content-Type": "application/json", "Authorization": "Bearer " + account["token"]}
    request = urllib.request.Request("http://127.0.0.1:8080/api/v1/chats/new", data=body, headers=headers)
    chat = json.load(urllib.request.urlopen(request))
    account["chat_id"] = chat["id"]
    with open("/tmp/postgresql-check.json", "w") as state:
        json.dump(account, state)
    print("Chat saved:", chat["title"])
    '
    Chat saved: PostgreSQL persistence check

    This saves an empty chat record; no model connection or generated response is needed to test database storage.

  14. Restart only the application service.

    The restart briefly interrupts Open WebUI. The database service, volumes, application key, and temporary check file stay in place.

    $ docker compose restart open-webui
  15. Wait for the restarted application to become healthy.
    $ docker compose up -d --wait open-webui
  16. Read the saved account and chat through Open WebUI after the restart.
    $ docker compose exec -T open-webui python -c '
    import json, urllib.request
    with open("/tmp/postgresql-check.json") as state:
        expected = json.load(state)
    headers = {"Authorization": "Bearer " + expected["token"]}
    def read(path):
        request = urllib.request.Request("http://127.0.0.1:8080" + path, headers=headers)
        return json.load(urllib.request.urlopen(request))
    account = read("/api/v1/auths/")
    chat = read("/api/v1/chats/" + expected["chat_id"])
    assert account["id"] == expected["id"] and account["email"] == expected["email"]
    assert chat["user_id"] == account["id"] and chat["title"] == "PostgreSQL persistence check"
    print("Account readable after restart:", account["email"])
    print("Chat readable after restart:", chat["title"])
    '
    Account readable after restart: admin@example.com
    Chat readable after restart: PostgreSQL persistence check

    An HTTP error or failed assertion stops the check instead of printing the two result lines.

  17. Confirm that the account and chat records are in PostgreSQL.
    $ docker compose exec -T postgres psql -U openwebui \
      -d openwebui -c 'SELECT u.email, c.title FROM "user" u
      JOIN chat c ON c.user_id = u.id
      WHERE c.title = '\''PostgreSQL persistence check'\'';'
           email       |            title
    -------------------+------------------------------
     admin@example.com | PostgreSQL persistence check
    (1 row)

    The named volumes contain the application records and local files. docker compose down -v deletes them. Protected backups are needed before upgrades or host replacement.
    Related: How to back up and restore Open WebUI data

  18. Remove the temporary session-token file from the application container.
    $ docker compose exec -T open-webui rm /tmp/postgresql-check.json

    The account, saved chat, and PostgreSQL database remain available.

Share this guide