---
type: reference
description: "PostgreSQL is the database backend for Gitea."
tags:
  - dankclaw
  - postgres
timestamp: 2026-09-03
---

# Postgres

PostgreSQL is the database backend for Gitea. It runs on the same podman network as Gitea and holds the repository metadata, users, and issue data.

**Host:** Dankclaw — **Docs:** https://www.postgresql.org/docs

## Facts

| Item | Value |
|------|-------|
| Image | `docker.io/library/postgres:16-alpine` |
| Port | 5432 (internal only) |
| Data volume | `/home/dank/Containers/gitea/postgres:/var/lib/postgresql/data` (live bind, verified from the unit) |

## Configuration

```yaml
services:
  postgres:
    image: docker.io/library/postgres:16-alpine
    restart: unless-stopped
    environment:
      POSTGRES_USER: gitea
      POSTGRES_PASSWORD: "${GITEA_DB_PASSWORD}"
      POSTGRES_DB: gitea
    volumes:
      - /opt/gitea/data/gitea-postgres:/var/lib/postgresql/data
```

## Gitea Connection

Gitea reaches the database over the `systemd-gitea` network (quadlet-managed live, compose-managed after the full-stack deploy):

```yaml
environment:
  DATABASE_TYPE: postgres
  DATABASE_HOST: gitea-postgres
  DATABASE_NAME: gitea
  DATABASE_USER: gitea
  DATABASE_PASSWD: "${GITEA_DB_PASSWORD}"
```

The live `app.ini` on the host overrides env vars. When you rename the database container, update its `[database] HOST` line. See [[Gitea]] Gotchas.

## Layout (current)

The live `gitea-postgres` unit mounts its data at
`/home/dank/Containers/gitea/postgres:/var/lib/postgresql/data` — the old
`/opt/gitea/data/gitea-postgres` compose-era path is gone. Secrets come from
the host-local env file `/home/dank/Containers/gitea/env` (0600) via
`EnvironmentFile=`; `POSTGRES_PASSWORD` never enters this repo. See [[Gitea]].

## Healthcheck

Use `pg_isready`:

```yaml
healthcheck:
  test: ["CMD-SHELL", "pg_isready -U gitea"]
  interval: 30s
  timeout: 5s
  retries: 3
```

## Gotchas

- The database password must match between the `postgres` service and Gitea's `DATABASE_PASSWD`; both come from the same `.env` variable.
- Do not change the Gitea `SECRET_KEY` or `INTERNAL_TOKEN` after migration — encrypted data becomes unreadable.
- Back up with `pg_dump`; see [[Gitea]] (knowledge base).

## See Also

- [[Gitea]]
- [[Dankclaw Stack]]