postgres¶
PostgreSQL 16 with pgAdmin 4 as the optional web GUI.
spin up postgres # database only
spin up postgres --gui # database + pgAdmin
spin url postgres # print the connection string
spin cli postgres # psql, inside the container
Ports¶
| Service | Host port | Container | Env var |
|---|---|---|---|
| postgres | 5432 |
5432 | POSTGRES_PORT |
| pgadmin | 8080 (gui profile) |
80 | PGADMIN_PORT |
pgAdmin sits on 8080, not 80 as in the old script — port 80 collides with nginx and needs root on Linux.
Credentials¶
| What | Default |
|---|---|
| Postgres user | spinup |
| Postgres password | spinup |
| Database | spinup |
| pgAdmin login | admin@example.com |
| pgAdmin password | spinup |
These are development defaults on a local machine. Change them in
spin env postgres --edit, and never expose this stack to a network you do
not control.
Connecting from pgAdmin¶
pgAdmin runs in its own container, so localhost there is not your machine.
Register the server with:
- Host
postgres(the service name, notlocalhost) - Port
5432(the container port, notPOSTGRES_PORT) - Username / password as above
Seeding¶
Anything in init/ — .sql, .sql.gz or .sh — is executed once, in
alphabetical order, the first time the data volume is created:
It will not re-run on later starts. To reseed, spin destroy postgres
(which deletes the volume) and spin up postgres again.
Gotchas¶
POSTGRES_USER,POSTGRES_PASSWORDandPOSTGRES_DBare only read when the data volume is empty. Editing them later changes nothing until you destroy the volume — this surprises everyone at least once.spin downkeeps your data; onlyspin destroydeletes it.- The database initialises with
--locale=Cfor reproducible sort order across hosts. If you need locale-aware collation, setPOSTGRES_INITDB_ARGSbefore the first start. - pgAdmin takes noticeably longer to become healthy than Postgres does; it waits for Postgres to pass its healthcheck before starting at all.
PGADMIN_EMAILis validated by pgAdmin, which rejects reserved TLDs like.localand.testand crash-loops on startup if you use one. Stick to a real-looking domain.- Port 5432 or 8080 already taken? That is common if you run other Compose
projects. Override per machine with
spin env postgres --edit, or for one run withspin up postgres --port POSTGRES_PORT=15432. Defaults for every stack are listed indocs/PORTS.md.