Skip to content

docs: Document embedded PostgreSQL#704

Open
marcelomendoncasoares wants to merge 5 commits into
serverpod:mainfrom
marcelomendoncasoares:docs/embedded-postgres
Open

docs: Document embedded PostgreSQL#704
marcelomendoncasoares wants to merge 5 commits into
serverpod:mainfrom
marcelomendoncasoares:docs/embedded-postgres

Conversation

@marcelomendoncasoares

@marcelomendoncasoares marcelomendoncasoares commented Jul 21, 2026

Copy link
Copy Markdown
Collaborator

Summary

Embedded PostgreSQL is the default for the development and test run modes in new projects, and the configuration page introduces dataPath, but nothing explained what the setting actually does, where the files live, or when to move off it. This fills that in on the database connection page.

Changes

  • Replace "Development database" with an "Embedded PostgreSQL" section and move the Docker instructions into their own section.
  • Explain what dataPath starts, and link to the configuration page rather than repeating it.
  • Cover storage: relative path resolution, one directory per run mode, keeping it out of version control, the first-run binary download and its per-user cache location, and the supported platforms.
  • Cover lifecycle: startup before the connection pool, the Unix socket transport, attaching to a cluster another process already runs, persistence across restarts, and recovery after an unclean exit.
  • Document resetting the database by deleting dataPath, with a warning about the data loss.
  • State the production boundary and how to move to an externally managed instance.
  • Add an advanced section for using serverpod_embedded_postgres directly: start, transports, connection details, attach, prefetch, stop, reset, and the sealed exception type.
  • Update the SERVERPOD_DATABASE_DATA_PATH row in the configuration reference.

Reference

Break the section into subsections instead of a run of paragraphs, point
at the configuration page rather than repeating what dataPath does, phrase
the recovery and transport behavior in terms of what the reader observes,
and use noun-shaped section titles like the rest of the page.
Rewriting the connection page around the embedded database displaced the
Docker instructions, which are still the alternative for anyone who wants
to run Postgres themselves. Restore that page and give embedded
PostgreSQL a short reference page of its own instead: what it is, how the
dataPath setting turns it on, where the files live, what happens on
start, how to reset it, and why it stays out of production.
The server talks to the embedded database over a Unix socket, so psql and
pgAdmin cannot reach it while it runs that way. Point at
'serverpod database start', which serves the same database over TCP.
@marcelomendoncasoares
marcelomendoncasoares marked this pull request as ready for review July 21, 2026 20:42
@marcelomendoncasoares
marcelomendoncasoares requested a review from a team July 21, 2026 20:42
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