amorfo77/paperless-ngx
1
0
Fork 0
mirror of https://github.com/paperless-ngx/paperless-ngx.git synced 2026-08-02 00:52:20 +00:00
Code Issues Projects Releases Wiki Activity

Feature: run pending LLM index migrations automatically on startup

Browse Source 
Add document_llmindex migrate, a cheap check-only path (no reindex) safe
to run unconditionally: has_pending_migration() short-circuits to a
metadata-only read once the store is current, so a healthy install pays
almost nothing. If a pending migration would require re-embedding, it
only logs a warning and leaves the index as-is -- re-embedding can be
slow and, for a metered embedding backend, cost money, so it stays a
deliberate manual action (document_llmindex rebuild), never automatic.

Wire it into the Docker image as a new init-llmindex-migrate oneshot
(modeled on init-search-index, gated on init-migrations), and document
the equivalent manual step for bare-metal upgrades.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
This commit is contained in:
stumpylog
2026-07-28 10:48:24 -07:00
co-authored by Claude Sonnet 5
parent b21d50645d
commit df8a6cc715
11 changed files with 181 additions and 4 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/administration.md
+23 -2
View File
@@ -104,7 +104,8 @@ $ docker compose down
docker compose up
```
Running `docker compose up` will also apply any new database migrations.
Running `docker compose up` will also apply any new database migrations,
and, if the LLM index is enabled, any pending LLM index schema migrations.
If you see everything working, press CTRL+C once to gracefully stop
paperless. Then you can start paperless-ngx with `-d` to have it run in
the background.
@@ -212,6 +213,17 @@ following:
This is a no-op if the index is already up to date, so it is safe to
run on every upgrade.
5. If the LLM index is enabled, apply any pending LLM index schema
migrations.
```shell-session
cd src
python3 manage.py document_llmindex migrate
```
This is a no-op if the index is already up to date (or the LLM index
is disabled), so it is safe to run on every upgrade.
### Database Upgrades
Paperless-ngx is compatible with Django-supported versions of PostgreSQL and MariaDB and it is generally
@@ -532,7 +544,7 @@ index is updated automatically on the schedule set by
can manage it manually:
```
document_llmindex {rebuild,update,compact}
document_llmindex {rebuild,update,compact,migrate}
```
Specify `rebuild` to build the index from scratch from all documents in the database. Use
@@ -544,6 +556,15 @@ scheduled task runs.
Specify `compact` to reclaim space and optimize the on-disk vector store.
Specify `migrate` to apply any pending index schema migrations without a full reindex.
This is a no-op if the index is already up to date, so it is safe to run on every
startup or upgrade; it is what the container's startup sequence and the
[bare-metal upgrade steps](#bare-metal-updating) run automatically. If a pending
migration would require re-embedding every document, `migrate` only logs a warning and
leaves the index as-is -- re-embedding can be slow and, for a metered embedding backend,
cost money, so it is never triggered automatically. Run `rebuild` yourself when you are
ready.
!!! note
These commands have no effect unless AI is enabled and an embedding backend is