psql access

README.md

@@ -55,10 +55,10 @@ claude doctor   # diagnose installation issues
 
 ## Volumes
 
-| Volume | Purpose |
-|---|---|
+| Volume                | Purpose                                                   |
+| --------------------- | --------------------------------------------------------- |
 | `claude-home` (named) | Persists Claude Code binary, config, and auth credentials |
-| `$PROJECT_DIR` (bind) | Your project code — swap freely between sessions |
+| `$PROJECT_DIR` (bind) | Your project code — swap freely between sessions          |
 
 To wipe the Claude install and start fresh:
 
@@ -68,9 +68,84 @@ docker compose down -v   # removes the claude-home volume
 
 ## Security notes
 
-- Runs as a non-root user (`coder`, uid 1000)
-- All Linux capabilities are dropped (`cap_drop: ALL`)
+- Runs as a non-root user (`coder`, uid 1001)
+- All Linux capabilities are dropped except `NET_BIND_SERVICE`
 - Privilege escalation is disabled (`no-new-privileges`)
 - The container has no network restrictions beyond what Docker provides —
   add a custom network or `--network none` with `--add-host` if you want
   to lock that down further
+
+## Connecting to a host PostgreSQL database
+
+The container can reach a PostgreSQL server running on the host, but
+`127.0.0.1` inside the container refers to the container itself, not the
+host. The solution is to connect via the Docker bridge gateway IP instead,
+which both the host and the container can see.
+
+### 1. Find the gateway IP
+
+```bash
+docker network inspect bridge | grep Gateway
+```
+
+This is typically `172.17.0.1`. Use the value specific to your machine
+in all steps below.
+
+### 2. Configure PostgreSQL on the host
+
+Edit `/etc/postgresql/<version>/main/postgresql.conf`:
+
+```
+listen_addresses = 'localhost,172.17.0.1'
+```
+
+Edit `/etc/postgresql/<version>/main/pg_hba.conf` and add:
+
+```
+host    all    all    172.17.0.0/16    scram-sha-256
+```
+
+Restart PostgreSQL:
+
+```bash
+sudo systemctl restart postgresql
+```
+
+### 3. Configure your app
+
+Use the gateway IP as the database host. Since it is reachable from both
+the host and the container, a single `DATABASE_URL` works in both contexts:
+
+```
+DATABASE_URL=postgresql://user:password@172.17.0.1:5432/mydb
+```
+
+Set this in your `.env` file or shell profile on the host, and pass it
+through in `docker-compose.yml`:
+
+```yaml
+environment:
+  - DATABASE_URL=${DATABASE_URL}
+```
+
+### Collation version warning
+
+If you see a warning like:
+
+```
+WARNING: database "mydb" has a collation version mismatch
+DETAIL: The database was created using collation version 2.41, but the
+operating system provides version 2.42.
+```
+
+This is caused by the container's glibc version differing from the host's.
+It is a warning only and will not break anything. To silence it, run once
+on the host:
+
+```bash
+psql -d mydb -c "ALTER DATABASE mydb REFRESH COLLATION VERSION;"
+```
+
+Note: the warning will reappear inside the container because its glibc
+version differs from the host. The long-term fix is to rebase the Docker
+image on the same Ubuntu release as the host so glibc versions match.