[PR #1441] [MERGED] docs: write pending changes into webui.db before exporting it #1404

New issue

Closed

opened 2026-10-18 14:19:27 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-10-18 14:19:27 +00:00

Owner

📋 Pull Request Information

Original PR: https://github.com/open-webui/docs/pull/1441
Author: @silentoplayz
Created: 9/29/2026
Status: ✅ Merged
Merged: 9/29/2026
Merged by: @silentoplayz

Base: main ← Head: docs/database-export-wal

📝 Commits (1)

130da3d docs: write pending changes into webui.db before exporting it

📊 Changes

1 file changed (+11 additions, -4 deletions)

View changed files

📝 docs/tutorials/maintenance/database.mdx (+11 -4)

📄 Description

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.

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.

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

## 📋 Pull Request Information **Original PR:** https://github.com/open-webui/docs/pull/1441 **Author:** [@silentoplayz](https://github.com/silentoplayz) **Created:** 9/29/2026 **Status:** ✅ Merged **Merged:** 9/29/2026 **Merged by:** [@silentoplayz](https://github.com/silentoplayz) **Base:** `main` ← **Head:** `docs/database-export-wal` --- ### 📝 Commits (1) - [`130da3d`](https://github.com/open-webui/docs/commit/130da3d958cd3de13e93ceee007bced78cb5777a) docs: write pending changes into webui.db before exporting it ### 📊 Changes **1 file changed** (+11 additions, -4 deletions) <details> <summary>View changed files</summary> 📝 `docs/tutorials/maintenance/database.mdx` (+11 -4) </details> ### 📄 Description ## 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 - [x] I have reviewed the relevant documentation and matched the existing style. - [x] 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. - [x] 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](https://sqlite.org/wal.html) 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. --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

bsakaguchi

2026-10-18 14:19:27 +00:00