# kb-postgres

Postgres 16 + pgvector — KB spine on SOLARIA. Stores the frozen envelope schema shared by all KB pillars (mails, documents, photos, transactions).

Port: **5433** on SOLARIA (Tailscale-accessible to other nodes).

## Standard deploy (from SATURN)

```bash
# On SATURN — pushes to master, then deploy.sh SSHes to SOLARIA and runs deploy-node.sh
git push origin master
scripts/deploy/deploy.sh solaria
```

`deploy-node.sh` on SOLARIA automatically picks up the per-host override:
```
docker compose \
  -f services/kb-postgres/docker-compose.yml \
  -f hosts/solaria/runtime/kb-postgres/docker-compose.override.yml \
  up -d --remove-orphans
```

## First-time setup on SOLARIA (before first deploy)

The `.env` file must exist at `services/kb-postgres/.env` in the SOLARIA repo checkout
(alongside the compose file — that's where `env_file: .env` resolves to):

```bash
# On SOLARIA
cd ~/homelab-codex-ws
cp services/kb-postgres/env.example services/kb-postgres/.env
# Edit .env: set POSTGRES_PASSWORD to something strong
```

`.env` is gitignored (`*.env` rule in root `.gitignore`) — it will never be committed.

## Manual one-off (debugging / first boot)

```bash
# On SOLARIA, from repo root
docker compose \
  -f services/kb-postgres/docker-compose.yml \
  -f hosts/solaria/runtime/kb-postgres/docker-compose.override.yml \
  up -d
```

## Verify after first boot

```bash
# Host-side healthcheck
./services/kb-postgres/healthcheck.sh

# Inside the container
docker exec kb-postgres psql -U kb -d kb -c '\d envelope'
docker exec kb-postgres psql -U kb -d kb \
  -c "SELECT extname FROM pg_extension WHERE extname = 'vector';"
```

Expected `\d envelope` output:

```
                    Table "public.envelope"
  Column  |           Type           | Nullable |  Default
----------+--------------------------+----------+-----------
 id       | text                     | not null |
 source   | text                     | not null |
 ts       | timestamp with time zone | not null |
 geo      | jsonb                    |          |
 raw_ref  | text                     | not null |
 entities | jsonb                    | not null | '[]'::jsonb
Indexes:
    "envelope_pkey" PRIMARY KEY, btree (id)
    "envelope_source_idx" btree (source)
    "envelope_ts_idx" btree (ts)
```

## Schema contract

The `envelope` table is the frozen cross-source envelope (see `docs/kb/kb-00-overview.md` §Zasady przekrojowe). Adding columns is OK; removing or renaming existing ones is NOT.

Future migrations go in `init/` as `002_*.sql`, `003_*.sql`, …. Postgres runs `initdb` scripts only on a fresh volume — for existing instances apply migrations with `psql` directly.

## Connection string

```
postgresql://kb:<POSTGRES_PASSWORD>@solaria:5433/kb
```

Set `KB_TEST_DSN` to this value when running integration tests from `packages/kb-mail/`.