# Scooter notification migration example

The article proposes using Ptah Compat for Scooter's PostgreSQL function and
trigger migrations. It does not claim that upstream has adopted the proposal.

## Source and attribution

Scooter source: https://github.com/chadac/scooter

- Upstream starting point: `0c01a6a`.
- Integration head: `277f83301a496421bb1b06104892131a5a95ef37`.
- Proposal: https://github.com/chadac/scooter/pull/693.
- Fork proof head: `96b4f1de4740f7bb10dd8d9420ef3a1c3a46a2c6`.
- Released-binary proof: https://github.com/denisvmedia/scooter/actions/runs/37046715387.

`agent_host/`, `atlas.hcl`, and `ptah-compat.nix` are copied from that
integration head. The historical migration files and original `atlas.sum`
are byte-identical to the source. Scooter's MIT license is included as
`SCOOTER-LICENSE.txt`. `probe.sql` is a test-only derivative of its desired
schema, changing the notification channel and adding `phase` to the UPDATE
trigger condition. These probe changes are not application changes in the PR.

## Reproduce the CLI example

Work on a copy of this directory: `migrate diff` appends a migration and
updates that copy's `atlas.sum`. Install the released Ptah Compat 0.12.0.

Use a dedicated, disposable PostgreSQL 16.15 server. Create separate empty
`dev` and `target` databases. Set `ATLAS_DEV_URL` to the dev URL, including
`sslmode=disable&search_path=public`, and `DATABASE_URL` to the target URL.
For this isolated local server, the recorded URLs were:

- `postgres://postgres:article-proof@postgres:5432/dev?sslmode=disable&search_path=public`
- `postgres://postgres:article-proof@postgres:5432/target?sslmode=disable`

The password above is a disposable test fixture value, not a deployment credential.
Enable `PTAH_DEV_SERVER_DISPOSABLE=1` for `migrate diff`. This declaration
requires ownership of the whole server, not just the dev database. The apply
commands were executed without this flag.

Run the commands in these files, from this directory, in order:

1. `commands/baseline.txt`: original history matches the complete desired schema.
2. `commands/apply-history.txt`: create the target from the six original migrations.
3. `commands/generate.txt`: generate the test-only function and trigger change.
4. `commands/apply-change.txt`: apply the new migration to the target.
5. `commands/settled.txt`: confirm the next diff is empty.

Run `notifications.sql` in a single psql session connected to the target with
`ON_ERROR_STOP=1`. It subscribes before writing, so each following statement
also exposes any notification it caused. The insert, phase update, and delete
each notify; the activity-only update does not.

`atlas.hcl` is the unchanged generated config from Scooter. It defines the
other service environments as well; this focused fixture contains only
`agent_host`. The broader fork proof covered all five service databases.

## Recorded output

The focused article run used the released `stokaro/ptah:0.12.0` image and
PostgreSQL 16.15 on October 3, 2026, in containers on the
`remote-dev-container` Docker context. The target and dev databases lived on
the task's isolated server. All task containers and its network were removed
after the run.

`measured/commands.json` records each Ptah invocation, exit code, and whether
the dev-server setting was present. `measured/*.txt` and the paired stderr
files retain the complete streams. Generated SQL is stored in
`measured/generated.sql`. Its timestamp belongs to this run; a rerun uses a
new migration timestamp. PostgreSQL's backend PID in `notifications.txt` is
also specific to this run.

`measured/notification-checks.json` records assertions against the notification
stream, including the absence of an event after the activity-only update.
The Nix excerpt in the article matches `ptah-compat.nix`, whose package and
migration image were built in the linked fork proof.

`measured/fork-validation.excerpt.txt` selects the migration, handover, baseline,
notification, and unit-test results from the October 2 fork run. ANSI color
sequences and the workflow/job columns were removed; test results were not
changed. The full log remains available through the linked run. It also records
successful type checks, ORM regeneration, and the Nix migration image build.

The full `just test` entry point stopped at cluster setup because k3s was not
installed in the isolated environment. Cluster and browser end-to-end acceptance
are not claimed. The article's direct database checks do not depend on them.