SQLite Database Overview

[!WARNING] This documentation was created/updated based on version 0.6.42 and updated for recent migrations.

Open-WebUI Internal SQLite Database​

For Open-WebUI, the SQLite database serves as the backbone for user management, chat history, file storage, and various other core functionalities. Understanding this structure is essential for anyone looking to contribute to or maintain the project effectively.

Internal SQLite Location​

You can find the SQLite database at root -> data -> webui.db

📁 Root (/)
├── 📁 data
│   ├── 📁 cache
│   ├── 📁 uploads
│   ├── 📁 vector_db
│   └── 📄 webui.db
├── 📄 dev.sh
├── 📁 open_webui
├── 📄 requirements.txt
├── 📄 start.sh
└── 📄 start_windows.bat

Copy Database Locally​

If you want to copy the Open-WebUI SQLite database running in the container to your local machine, you can use:

docker cp open-webui:/app/backend/data/webui.db ./webui.db

Alternatively, you can access the database within the container using:

docker exec -it open-webui /bin/sh

Table Overview​

Here is a complete list of tables in Open-WebUI's SQLite database. The tables are listed alphabetically and numbered for convenience.

Note: there are two additional tables in Open-WebUI's SQLite database that are not related to Open-WebUI's core functionality, that have been excluded:

• Alembic Version table
• Migrate History table

Now that we have all the tables, let's understand the structure of each table.

Auth Table​

Things to know about the auth table:

• Uses UUID for primary key
• One-to-One relationship with users table (shared id)

Channel Table​

Things to know about the auth table:

• Uses UUID for primary key
• Case-insensitive channel names (stored lowercase)

Channel Member Table​

Channel File Table​

Things to know about the channel_file table:

• Unique constraint on (channel_id, file_id) to prevent duplicate entries
• Foreign key relationships with CASCADE delete
• Indexed on channel_id, file_id, and user_id for performance

Chat Table​

Chat File Table​

Things to know about the chat_file table:

• Unique constraint on (chat_id, file_id) to prevent duplicate entries
• Foreign key relationships with CASCADE delete
• Indexed on chat_id, file_id, message_id, and user_id for performance

Why this table was added:

• Query Efficiency: Before this, files were embedded in message objects. This table allows direct indexed lookups for finding all files in a chat without iterating through every message.
• Data Consistency: Acts as a single source of truth for file associations. In multi-node deployments, all nodes query this table instead of relying on potentially inconsistent embedded data.
• Deduplication: The database-level unique constraint prevents duplicate file associations, which is more reliable than application-level checks.

Chat ID Tag Table​

Config​

Feedback Table​

File Table​

The meta field's expected structure:

{
    "name": string,          # Optional display name
    "content_type": string,  # MIME type
    "size": integer,         # File size in bytes
    # Additional metadata supported via ConfigDict(extra="allow")
}

Folder Table​

Things to know about the folder table:

• Primary key is composite (id, user_id)
• Folders can be nested (parent_id reference)
• Root folders have null parent_id
• Folder names must be unique within the same parent

Function Table​

Things to know about the function table:

• type can only be: ["filter", "action"]

Group Table​

Note: The user_ids column has been migrated to the group_member table.

Group Member Table​

Things to know about the group_member table:

• Unique constraint on (group_id, user_id) to prevent duplicate memberships
• Foreign key relationships with CASCADE delete to group and user tables

Knowledge Table​

Knowledge File Table​

Things to know about the knowledge_file table:

• Unique constraint on (knowledge_id, file_id) to prevent duplicate entries
• Foreign key relationships with CASCADE delete
• Indexed on knowledge_id, file_id, and user_id for performance

The access_control fields expected structure:

{
  "read": {
    "group_ids": ["group_id1", "group_id2"],
    "user_ids": ["user_id1", "user_id2"]
  },
  "write": {
    "group_ids": ["group_id1", "group_id2"],
    "user_ids": ["user_id1", "user_id2"]
  }
}

Memory Table​

Message Table​

Message Reaction Table​

Model Table​

Note Table​

OAuth Session Table​

Prompt Table​

Tag Table​

Things to know about the tag table:

• Primary key is composite (id, user_id)

Tool Table​

User Table​

Entity Relationship Diagram​

To help visualize the relationship between the tables, refer to the below Entity Relationship Diagram (ERD) generated with Mermaid.

Database Encryption with SQLCipher​

For enhanced security, Open WebUI supports at-rest encryption for its primary SQLite database using SQLCipher. This is recommended for deployments handling sensitive data where using a larger database like PostgreSQL is not needed.

Prerequisites​

SQLCipher encryption requires additional dependencies that are not included by default. Before using this feature, you must install:

• The SQLCipher system library (e.g., libsqlcipher-dev on Debian/Ubuntu, sqlcipher on macOS via Homebrew)
• The sqlcipher3-wheels Python package (pip install sqlcipher3-wheels)

For Docker users, this means building a custom image with these dependencies included.

Configuration​

To enable encryption, set the following environment variables:

# Required: Set the database type to use SQLCipher
DATABASE_TYPE=sqlite+sqlcipher

# Required: Set a secure password for database encryption
DATABASE_PASSWORD=your-secure-password

When these are set and a full DATABASE_URL is not explicitly defined, Open WebUI will automatically create and use an encrypted database file at ./data/webui.db.

Important Notes​

Related Database Environment Variables​

For more details, see the Environment Variable Configuration documentation.