Skip to content

docs: warn that v4 removes the bundled postgres and document the migration#1121

Open
dkrizan wants to merge 3 commits into
mainfrom
dkrizan/slim-ee-image
Open

docs: warn that v4 removes the bundled postgres and document the migration#1121
dkrizan wants to merge 3 commits into
mainfrom
dkrizan/slim-ee-image

Conversation

@dkrizan

@dkrizan dkrizan commented Jun 22, 2026

Copy link
Copy Markdown
Member

What

Two changes:

  1. platform/self_hosting/running_with_docker.mdx — warns that Tolgee v4 removes the bundled PostgreSQL from the tolgee/tolgee image, and adds a Migrate from the bundled database section with the actual procedure.
  2. .github/workflows/update-generated-code.yaml — the docs codegen job booted ghcr.io/tolgee/tolgee-ee standalone and relied on its embedded postgres. The EE image is becoming slim (no bundled DB), so the job now starts a postgres service and points the app at it.

Why

In v4 the bundled postgres goes away, so anyone running it has to move to an external database first. The good news is that this needs no dump and restore: the bundled server keeps its files in data/postgres on the volume users already mount, which is exactly where a separate postgres container looks for them. Pin the container to postgres:13 and it adopts the directory in place.

This also fixes a live trap. The existing external-database example runs postgres:15 and mounts ./data/postgres:/var/lib/postgresql/data — the same directory a bundled user already has. Copy-pasting it as a migration fails hard:

FATAL:  database files are incompatible with server
DETAIL: The data directory was initialized by PostgreSQL version 13,
        which is not compatible with this version 15.17

That example is fine for fresh installs and now says it's for fresh installs.

Verified end-to-end

Against the real tolgee/tolgee:v3.212.0 image, not by reasoning:

  • Booted with the bundled DB, confirmed PG_VERSION is 13 at data/postgres, created a marker translation key via the API.
  • postgres:15 on that directory → exits(1), incompatible-files error above.
  • postgres:13 on that directory → starts, all 103 tables intact.
  • Tolgee with postgres-autostart.enabled=false against the external postgres:13 → boots, starts no embedded server, original admin password still works, marker key still present.

Notes for review

@netlify

netlify Bot commented Jun 22, 2026

Copy link
Copy Markdown

Deploy Preview for tolgee-docs ready!

Name Link
🔨 Latest commit 7374ad7
🔍 Latest deploy log https://app.netlify.com/projects/tolgee-docs/deploys/6a5a13c39cd60e0008bc7440
😎 Deploy Preview https://deploy-preview-1121--tolgee-docs.netlify.app
📱 Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

@dkrizan
dkrizan force-pushed the dkrizan/slim-ee-image branch 2 times, most recently from 1d35a59 to a28eeb1 Compare June 23, 2026 09:54
@dkrizan
dkrizan force-pushed the dkrizan/slim-ee-image branch 2 times, most recently from ed5bbe2 to 8854090 Compare July 16, 2026 13:45
@dkrizan dkrizan changed the title docs: document slim Docker image and run codegen against external postgres docs: warn that v4 removes the bundled postgres Jul 16, 2026
@dkrizan
dkrizan marked this pull request as ready for review July 16, 2026 14:29
@dkrizan
dkrizan force-pushed the dkrizan/slim-ee-image branch 4 times, most recently from 4faf2c2 to 5b64a9a Compare July 16, 2026 14:51
@dkrizan dkrizan changed the title docs: warn that v4 removes the bundled postgres docs: warn that v4 removes the bundled postgres and document the migration Jul 16, 2026
@dkrizan
dkrizan force-pushed the dkrizan/slim-ee-image branch from 5b64a9a to 958696d Compare July 17, 2026 10:03
The EE image is becoming slim and bundles no postgres server, so the job needs
a database of its own. Postgres 13 went end of life in November 2025.
@dkrizan
dkrizan force-pushed the dkrizan/slim-ee-image branch from 958696d to e9d063d Compare July 17, 2026 10:13
…ation

The bundled server is PostgreSQL 13, end of life since November 2025, so the
migration leads with a dump into PostgreSQL 17 and keeps reusing the existing
files on 13 as the quicker alternative.

The external database example sets up an empty database, which is the wrong
thing to copy for a migration: a newer PostgreSQL refuses to start on the files
the bundled server leaves behind.
@dkrizan
dkrizan force-pushed the dkrizan/slim-ee-image branch from e9d063d to 58f7476 Compare July 17, 2026 11:28
@dkrizan
dkrizan requested review from Barush and JanCizmar July 17, 2026 11:37
Your projects, translations and users are all still there, and your existing passwords keep working. Once you have
checked everything is in place, you can delete the old `data/postgres` directory.

### Keep the existing files on PostgreSQL 13

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would call the documentation sections in this form such as "Keeping ...". Saying "Keep something" sounds like encouraging the user to do such a thing.

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.

2 participants