docs: Document embedded PostgreSQL

docs/06-concepts/03-data-and-the-database/02-database/14-connection.md

@@ -4,7 +4,7 @@ description: The database connection is defined in Serverpod's configuration and
 
 # Connection
 
-The connection details and password for the database live in the `config` directory of your server package, and Serverpod connects using them when the server starts. For local development, no setup is needed by default: the server runs an [embedded PostgreSQL](../../server-fundamentals/configuration#database-backends) and manages it for you. This page is for connecting to a database you run yourself: a local or Docker Postgres, a remote server, or a managed instance such as Cloud SQL or RDS.
+The connection details and password for the database live in the `config` directory of your server package, and Serverpod connects using them when the server starts. For local development, no setup is needed by default: the server runs an [embedded PostgreSQL](./embedded-postgres) and manages it for you. This page is for connecting to a database you run yourself: a local or Docker Postgres, a remote server, or a managed instance such as Cloud SQL or RDS.
 
 ## Connection details
 
@@ -84,9 +84,9 @@ development:
 
 ## The development database
 
-By default, the development database is an embedded PostgreSQL, started and stopped with the server; see [Running your server](../../server-fundamentals/running-your-server). Nothing on this page is needed for it.
+By default, the development database is an [embedded PostgreSQL](./embedded-postgres), started and stopped with the server; see [Running your server](../../server-fundamentals/running-your-server). Nothing on this page is needed for it.
 
-Projects set up with the Docker alternative instead run their development database from the server package's `docker-compose.yaml`. Start it from the root of the `server` package:
+Projects set up with the Docker alternative instead run their development database from the server package's `docker-compose.yaml`. To use it in a project configured for the embedded PostgreSQL, first remove `dataPath` from the run mode's configuration. Start the database from the root of the `server` package:
 
 ```bash
 $ docker compose up --build --detach

docs/06-concepts/03-data-and-the-database/02-database/19-embedded-postgres.md

@@ -0,0 +1,81 @@
+---
+description: Embedded PostgreSQL is a real PostgreSQL server that Serverpod starts and stops with your server, for local development and testing without Docker.
+---
+
+# Embedded PostgreSQL
+
+New projects run an embedded PostgreSQL in the `development` and `test` run modes. It is a real PostgreSQL server that Serverpod starts and stops together with your server, so local development gets the same database engine as production without installing PostgreSQL or running Docker.
+
+It is meant for local development and testing only. There are no backups, no replication, and nothing supervising the process, so staging and production connect to a managed or separately operated PostgreSQL instead. See [Connection](./connection) for those setups.
+
+## Enable it
+
+Embedded PostgreSQL is enabled by the `dataPath` setting, which generated projects already include:
+
+```yaml title="config/development.yaml"
+database:
+  host: localhost
+  port: 8090
+  name: myproject
+  user: postgres
+  dataPath: .serverpod/development/pgdata
+```
+
+The rest of the database settings stay as they are. Serverpod uses `name` and `user` when it creates the database and reads the password from `config/passwords.yaml`, exactly as it would for an external instance. Remove `dataPath` to connect to the `host` and `port` instead.
+
+A relative `dataPath` is resolved from the root of the server package, and each run mode needs its own directory, for example `.serverpod/test/pgdata` in `config/test.yaml`. The directory holds a complete database, so keep it out of version control.
+
+## What happens when the server starts
+
+The first start downloads the PostgreSQL binaries for your operating system and architecture into a per-user cache, which every later start and every other project reuses. Binaries are available for Linux and macOS on x64 and Arm64, and for Windows on x64.
+
+Serverpod starts the database before it opens its connection pool, and connects over a Unix domain socket instead of a TCP port, so several projects can run at once without competing for ports. If another Serverpod process already runs a database in the same `dataPath`, the new process attaches to it rather than starting a second one.
+
+The files under `dataPath` are kept when the server stops, so your data is still there on the next start. After an unclean exit, Serverpod clears the leftover process state and brings the database back up.
+
+## Connect a database tool
+
+Most clients like `psql` and `pgAdmin` connect over TCP, not the Unix socket the server uses. To inspect the data with one of them, start the database on its own while the server is stopped:
+
+```bash
+$ serverpod database start
+```
+
+It boots the database configured for the `development` run mode and keeps it listening on the configured port until you stop it with Ctrl+C. Connect with the `name` and `user` from that run mode's configuration, and the password from `config/passwords.yaml`.
+
+Pass `--mode` to pick another run mode and `--port` to listen somewhere else:
+
+```bash
+$ serverpod database start --mode test --port 9090
+```
+
+## Run integration tests
+
+Integration tests bring their own database, so there is nothing to install or start first:
+
+```bash
+$ dart test
+```
+
+The started database server will be held open until the test process exits. Every suite in a test process shares the same database server, but each `withServerpod` group creates a randomly named database of its own on it that will be dropped on teardown. That is where the isolation comes from: groups run in parallel without seeing each other's data or leaving anything behind between runs.
+
+The data directory is not temporary. Like the one for `development`, it stays after the tests, and only the server process is reclaimed when the test process exits. See [Get started with testing](../../testing/get-started) for the rest of the setup.
+
+:::note
+If a test process is hard-killed, the database server will not be stopped and data can be left behind. This data won't harm future runs because of the named database isolation, but it can occupy disk space. If the directory happens to grow too large, it is fully safe to delete it and let the next test recreate it from scratch.
+:::
+
+## Reset the database
+
+To start from an empty database, stop the server and delete the directory `dataPath` points at. Serverpod creates a new one on the next start.
+
+:::warning
+Deleting `dataPath` permanently deletes the database and all local data stored in it.
+:::
+
+## Related
+
+- [Connection](./connection): connecting to a PostgreSQL instance you run yourself.
+- [Configuration](../../server-fundamentals/configuration#database-backends): the database section of the run mode configuration.
+- [`serverpod database`](../../cli/commands/database): every option of the command above.
+- [serverpod_embedded_postgres](https://pub.dev/packages/serverpod_embedded_postgres): the package behind this, for tools that need a PostgreSQL process of their own.

docs/06-concepts/lookups/configuration-reference.md

@@ -47,7 +47,7 @@ Ports, hosts, and connection settings for the API, Insights, and web servers, th
 | SERVERPOD_DATABASE_MAX_CONNECTION_COUNT   | database.maxConnectionCount   | 10        | The maximum number of connections in the database pool. Set to 0 or a negative value for unlimited connections.                                                                   |
 | SERVERPOD_DATABASE_FILE_PATH              | database.filePath             | -         | The SQLite database file path. Set this instead of host/port/name/user when using SQLite.                                                                                         |
 | SERVERPOD_DATABASE_DIALECT                | database.dialect              | postgres  | The database dialect. Valid options are `postgres` and `sqlite`.                                                                                                                  |
-| SERVERPOD_DATABASE_DATA_PATH              | database.dataPath             | -         | Directory for the embedded PostgreSQL cluster. When set, the server boots a managed Postgres before connecting. PostgreSQL only; ignored for SQLite.                              |
+| SERVERPOD_DATABASE_DATA_PATH              | database.dataPath             | -         | Directory for the embedded PostgreSQL cluster, relative to the server package unless absolute. When set, Serverpod starts or attaches to the cluster before connecting. PostgreSQL only; ignored for SQLite. |
 | SERVERPOD_REDIS_HOST                      | redis.host                    | -         | The host address of the Redis server                                                                                                                                              |
 | SERVERPOD_REDIS_PORT                      | redis.port                    | -         | The port number for the Redis server                                                                                                                                              |
 | SERVERPOD_REDIS_USER                      | redis.user                    | -         | The user name for Redis authentication                                                                                                                                            |