Skip to content

docs: write pending changes into webui.db before exporting it - #1441

Merged
silentoplayz merged 1 commit into
open-webui:mainfrom
silentoplayz:docs/database-export-wal
Sep 29, 2026
Merged

silentoplayz merged 1 commit into
open-webui:mainfrom
silentoplayz:docs/database-export-wal

Conversation

@silentoplayz

Copy link
Copy Markdown
Collaborator

Summary

The export steps on the database page stop the container and then copy webui.db on its own. Open WebUI runs SQLite in WAL mode by default since v0.9.0, and a clean docker stop leaves recent committed changes in webui.db-wal, so that copy can be missing them. On a freshly set up instance, webui.db alone held no users and no chats at all.

This adds one export step that writes the pending changes into webui.db with a checkpoint. It runs from the container's own image while the container is stopped, and the quick-commands summary gets the same line. The first step's sentence now says why the container is stopped. The import steps are unchanged.

Related issue or discussion

None.

Checklist

  • I have reviewed the relevant documentation and matched the existing style.
  • This PR meets Open WebUI's contribution standards: it is accurate, relevant to users, narrowly scoped, maintainable, and not promotional content, advertising, lead generation, SEO placement, or a request to list a product, service, provider, integration, gateway, tool, or company primarily for visibility.
  • I understand that PRs that do not meet these standards may be closed without review and will not be merged. Repeated, low-quality, off-topic, promotional, or intentionally misleading submissions may result in the contributor being blocked from future participation in Open WebUI repositories.

Notes for reviewers

  • Checked on v0.11.4 and on the dev image (176d31d1d), each stopped with docker stop (exit code 0). In each run, the webui.db copied without the new step was missing the rows written since the container last started. After it, the copy had all of them, and the page's import steps on a fresh install brought every one across.
  • The checkpoint uses the image's own Python, so neither the host nor the image needs a sqlite3 binary. It follows the --volumes-from pattern the import step already uses for rm. On a database with WAL turned off, the pragma returns (0, -1, -1) and changes nothing.
  • Open WebUI's shutdown doesn't close its SQLite connections, so SQLite's final checkpoint doesn't run and the changes stay in the WAL. SQLite's WAL documentation says: "The WAL file is part of the persistent state of the database and should be kept with the database if the database is copied or moved."
  • The page is the only thing to maintain after merge. It applies to SQLite installs only, as the page already says, and PostgreSQL is untouched. If it ever came out, the export would go back to a copy that can miss recent changes. It sits alongside the unchanged import steps, which already remove the destination's sidecar files. It also fits the intro's advice to copy the whole data directory.

Open WebUI runs SQLite in WAL mode by default since v0.9.0, and a clean
`docker stop` leaves recent committed changes in webui.db-wal. The export
steps copied webui.db alone, so the copy could miss them.

Add a step that runs PRAGMA wal_checkpoint(TRUNCATE) from the container's
own image while it is stopped, using the same --volumes-from pattern the
import step already uses, and add the line to the quick-commands summary.
The import steps are unchanged.
@silentoplayz
silentoplayz merged commit 8508f02 into open-webui:main Sep 29, 2026
1 check passed
@silentoplayz
silentoplayz deleted the docs/database-export-wal branch September 29, 2026 08:26
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant