fix(docker): install pg and mysql2 in the official runtime image

`@objectstack/driver-sql` declares `pg`, `mysql2` and `tedious` as OPTIONAL
peer dependencies, and npm skips optional peers, so the official runtime
image -- built by `npm install -g @objectstack/cli` and nothing else -- had
no `pg` in it. Every documented Postgres path landed on that image: the
`docker run ... -e OS_DATABASE_URL=postgres://...` invocation in
docker/README.md, the same invocation in this Dockerfile's own header, and
`npm create objectstack` followed by `docker compose up` against the
generated `postgres:17` service. All of them failed fast at boot with
`Cannot find module 'pg'`.

Per the maintainer ruling on #14510 (direction B'): the image installs the
drivers, and docker/README.md publishes which ones it carries as a
maintained public promise. The scaffolder is unchanged.

The version ranges are copied verbatim from driver-sql's
`peerDependencies`, so the image satisfies the driver's own contract rather
than a second one; both packages are pure JavaScript with no native build.

A promise with nothing holding it to the artifact drifts silently, so
`check-docs-image-tag` -- the gate that already owns exactly this file pair
-- grows a third limb comparing the Dockerfile's install line against the
README's published table: package set, version ranges, and an anti-vacuity
rule on both sides. Every new finding kind is observed failing in
`--self-test` (94 assertions), and the limb was proven red against the
pre-change tree before the docker files were touched.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016yfqQh2dBgPAymYd7xipza

Author: claude

docker/Dockerfile

@@ -40,7 +40,36 @@ FROM node:22-slim
 # Pinned by CI to the @objectstack/cli release that triggered the publish.
 # `latest` is only the fallback for ad-hoc local builds of this file.
 ARG OS_CLI_VERSION=latest
-RUN npm install -g @objectstack/cli@${OS_CLI_VERSION} \
+
+# The SQL drivers ship WITH the image, not with the app (#14510).
+#
+# `@objectstack/driver-sql` declares `pg`, `mysql2` and `tedious` as OPTIONAL
+# peer dependencies. npm 7+ installs peer dependencies automatically but SKIPS
+# the optional ones, so `npm install -g @objectstack/cli` on its own produced a
+# tree with no `pg` in it -- while the header of this very file, README.md, and
+# the `docker-compose.yml` that `npm create objectstack` generates (whose `db`
+# service is `postgres:17`) all hand this image a `postgres://` URL. Every one
+# of those paths died at boot on `Cannot find module 'pg'`, with the loud
+# fail-fast ADR-0062 D5 requires but nothing documented to act on. Installing
+# the drivers here is the "whoever makes the promise installs it" half of the
+# fix; the other half is that README.md publishes the list.
+#
+# The ranges are copied VERBATIM from driver-sql's `peerDependencies`, so the
+# image satisfies the driver's own contract rather than a second one invented
+# here. Both packages are pure JavaScript with no native build step, which is
+# why they are affordable for every user of the image. `tedious` (SQL Server)
+# and `@objectstack/driver-turso` are deliberately NOT installed -- extend the
+# image when you need one, as README.md shows.
+#
+# This install line is a PUBLIC PROMISE, published as the driver table in
+# ./README.md. Adding or removing a package here changes which databases a
+# deployment can reach, so the two files must move in the same commit:
+# `pnpm check:docs-image-tag` fails when the install line and that table
+# disagree on the package set or on a version range.
+RUN npm install -g \
+      @objectstack/cli@${OS_CLI_VERSION} \
+      "pg@^8.0.0" \
+      "mysql2@^3.0.0" \
  && npm cache clean --force
 
 LABEL org.opencontainers.image.source="https://github.com/objectstack-ai/objectstack" \

docker/README.md

@@ -46,6 +46,44 @@ docker run -p 8080:8080 \
 `OS_ARTIFACT_PATH` also accepts an `https://` URL, so the artifact can come
 straight from your release storage.
 
+## Database drivers in the image
+
+**This list is a public promise.** The dialects below need nothing installed —
+their driver is already in the image, which is why the `postgres://` invocation
+above works exactly as written.
+
+| `OS_DATABASE_URL` scheme | Driver package installed in the image |
+|:---|:---|
+| `postgres://`, `postgresql://` | `pg@^8.0.0` |
+| `mysql://`, `mysql2://` | `mysql2@^3.0.0` |
+
+The ranges are `@objectstack/driver-sql`'s own optional-peer ranges, so the
+image satisfies the driver's contract rather than a second one. Both packages
+are pure JavaScript — they add no native build step and no compiler to the
+image.
+
+Two more dialects work without appearing above, because they arrive with
+`@objectstack/cli` rather than from that install line: SQLite (`better-sqlite3`,
+for a `file:…` path — one box only, wrong for multi-node) and MongoDB
+(`mongodb://…`, **single-tenant only**; see
+[Drivers](https://objectstack.ai/docs/data-modeling/drivers)).
+
+**Not in the image:** `tedious` (SQL Server) and `@objectstack/driver-turso`
+(`libsql://…` / Turso). Add one by extending the image:
+
+```dockerfile
+FROM ghcr.io/objectstack-ai/objectstack:17.2.0
+USER root
+RUN npm install -g tedious
+USER node
+COPY --chown=node:node dist/objectstack.json /srv/app/objectstack.json
+```
+
+Changing this table is a change to what deployments can connect to, so it does
+not move on its own: `pnpm check:docs-image-tag` compares it against
+[`Dockerfile`](./Dockerfile)'s install line and fails if the two disagree on the
+package set or on a version range.
+
 ## What the image presets
 
 - `OS_ARTIFACT_PATH=/srv/app/objectstack.json`, `OS_PORT=8080`,