### Create and enter a directory for direct apply

Source: https://github.com/stokaro/ptah/blob/master/docs/site/src/content/docs/direct/apply.md

Start in an empty directory to set up the example environment for applying a desired schema.

```console
mkdir ptah-direct-apply
cd ptah-direct-apply
```

--------------------------------

### Set up the project and a throwaway PostgreSQL (Bash)

Source: https://github.com/stokaro/ptah/blob/master/docs/site/src/content/docs/operate/zero-downtime-changes.mdx

Creates the project directory and starts a disposable PostgreSQL 18 container named ptah-zero-downtime on port 55434. Use this before running any migration examples.

```bash
mkdir -p ptah-zero-downtime/migrations
cd ptah-zero-downtime
docker run -d --name ptah-zero-downtime \
  -e POSTGRES_USER=ptah -e POSTGRES_PASSWORD=ptah -e POSTGRES_DB=app \
  -p 55434:5432 postgres:18-alpine
```

--------------------------------

### Set up the project and a throwaway PostgreSQL (PowerShell)

Source: https://github.com/stokaro/ptah/blob/master/docs/site/src/content/docs/operate/zero-downtime-changes.mdx

Creates the project directory and starts a disposable PostgreSQL 18 container named ptah-zero-downtime on port 55434. Use this before running any migration examples.

```powershell
New-Item -ItemType Directory ptah-zero-downtime/migrations | Out-Null
Set-Location ptah-zero-downtime
docker run -d --name ptah-zero-downtime `
  -e POSTGRES_USER=ptah -e POSTGRES_PASSWORD=ptah -e POSTGRES_DB=app `
  -p 55434:5432 postgres:18-alpine
```

--------------------------------

### Example plan file (add_created_at.plan.json)

Source: https://github.com/stokaro/ptah/blob/master/docs/site/src/content/docs/direct/plan-and-approve.md

A JSON plan file that a reviewer reads. Contains format_version, name, dialect, fingerprints, destructive flag, and statements with SQL, severity, and reason. The from_fingerprint describes the schemas the database URL covers; to_fingerprint describes the desired schema. The file is what gets approved and applied.

```json
{
  "format_version": 1,
  "name": "add_created_at",
  "dialect": "sqlite",
  "from_fingerprint": "sha256:2259264fba37b68659268236f28164880e7618466b0ba779af09e68ce7f9a390",
  "to_fingerprint": "sha256:33a61bf8700833003ab4c1cfe185a96283ae5f009acc6830b47e303baeb9af58",
  "destructive": false,
  "statements": [
    {
      "sql": "ALTER TABLE \"users\" ADD COLUMN \"created_at\" TIMESTAMP",
      "severity": "safe",
      "reason": "does not remove data or tighten constraints"
    }
  ]
}
```

--------------------------------

### Run the extension ignore comparison example

Source: https://github.com/stokaro/ptah/blob/master/examples/extension_ignore/README.md

Run the example from the repository root. No PostgreSQL server is required.

```bash
go run ./examples/extension_ignore
```

--------------------------------

### Run non-site examples and inference tutorial

Source: https://github.com/stokaro/ptah/blob/master/docs/site/README.md

Execute the non-site examples and the service-backed inference tutorial from the repository root. The first script runs example checks; the second runs the inference quick-start check using the default Docker context.

```bash
scripts/check-examples.sh
PTAH_DOCKER_CONTEXT=default docs/site/scripts/check-inference-quick-start.sh
```

--------------------------------

### Create working directory for drift example

Source: https://github.com/stokaro/ptah/blob/master/docs/site/src/content/docs/direct/compare-and-drift.md

Creates and enters an empty directory for the drift example. Run before creating schema.sql.

```console
mkdir ptah-drift
cd ptah-drift
```

--------------------------------

### Inspect the installer before running it

Source: https://github.com/stokaro/ptah/blob/master/docs/site/src/content/docs/start/install-options.mdx

Download and inspect the installer script before running it. The downloaded files are the same scripts used by the one-line installer.

```bash
curl -fsSL https://ptah.run/install.sh -o install.sh
less install.sh
sh ./install.sh
```

```powershell
irm https://ptah.run/install.ps1 -OutFile install.ps1
Get-Content install.ps1 | more
& ./install.ps1
```

--------------------------------

### Verify Ptah installation with ptah version

Source: https://github.com/stokaro/ptah/blob/master/docs/site/src/content/docs/start/quick-start-postgresql.mdx

Confirms the Ptah binary is installed and on your PATH before starting the PostgreSQL quick start.

```console
ptah version
```

--------------------------------

### schema.yaml starting state

Source: https://github.com/stokaro/ptah/blob/master/docs/site/src/content/docs/schema/document.mdx

The schema file used as the starting point for all examples on this page. Save it as schema.yaml. It defines an order_status enum, customers and orders tables with columns, indexes, and a foreign key.

```yaml
enums:
  order_status:
    values: [pending, shipped, canceled]
tables:
  customers:
    columns:
      id:
        type: INTEGER
        primary: true
      email:
        type: TEXT
        not_null: true
      country:
        type: TEXT
        not_null: true
    indexes:
      idx_customers_country:
        fields: [country]
  orders:
    columns:
      id:
        type: INTEGER
        primary: true
      customer_id:
        type: INTEGER
        not_null: true
        foreign: customers(id)
      status:
        type: order_status
        not_null: true
        default: pending

```

--------------------------------

### Starting golang-migrate directory structure

Source: https://github.com/stokaro/ptah/blob/master/docs/site/src/content/docs/versioned/import.md

Shows the starting state of a golang-migrate directory where the second migration has no down file. This is the input to the import command.

```text
db/migrations/
  000001_create_users.up.sql
  000001_create_users.down.sql
  000002_add_posts.up.sql

```

--------------------------------

### Basic Usage: Parse SQL with parser.NewParser

Source: https://github.com/stokaro/ptah/blob/master/internal/parser/README.md

Shows the minimal setup to parse a SQL string using parser.NewParser and parser.Parse(). The example creates a table and prints the number of parsed statements. Requires importing 'ptah.run/internal/parser'.

```go
package main

import (
    "fmt"
    "log"
    
    "ptah.run/internal/parser"
)

func main() {
    sql := `CREATE TABLE users (
        id INTEGER PRIMARY KEY,
        email VARCHAR(255) NOT NULL UNIQUE,
        created_at TIMESTAMP DEFAULT NOW()
    );`
    
    parser := parser.NewParser(sql)
    statements, err := parser.Parse()
    if err != nil {
        log.Fatal(err)
    }
    
    fmt.Printf("Parsed %d statements\n", len(statements.Statements))
}
```

--------------------------------

### Create a migration directory and navigate into it

Source: https://github.com/stokaro/ptah/blob/master/docs/site/src/content/docs/versioned/apply.md

Start in an empty directory to set up a migration workspace. This is the first step in the prerequisites.

```console
mkdir ptah-apply
cd ptah-apply
```

--------------------------------

### Create working directory

Source: https://github.com/stokaro/ptah/blob/master/docs/site/src/content/docs/start/adopt-an-existing-database.mdx

Creates and enters an empty directory for the adoption example.

```console
mkdir ptah-adopt
cd ptah-adopt
```

--------------------------------

### Install ptah with observability tag

Source: https://github.com/stokaro/ptah/blob/master/docs/site/src/content/docs/operate/trace-migrations.md

Installs a release of ptah with the observability build tag using go install.

```bash
go install -tags observability ptah.run/cmd/ptah@vX.Y.Z
```

--------------------------------

### Example migration filenames

Source: https://github.com/stokaro/ptah/blob/master/migration/generator/README.md

Examples of up and down migration filenames following the naming convention.

```text
1703123456_add_user_table.up.sql
```

```text
1703123456_add_user_table.down.sql
```

--------------------------------

### Quick Start Test Commands

Source: https://github.com/stokaro/ptah/blob/master/TESTING.md

Quick start commands for running the test suite. Use `test-all.ps1` for comprehensive testing, `test-new-methods.ps1` for new visitor methods, and `-Category unit` to skip database requirements.

```powershell
# Run all tests (recommended)
.\test-all.ps1

# Run only the new visitor methods tests
.\test-new-methods.ps1

# Run unit tests only (no databases needed)
.\test-all.ps1 -Category unit
```

--------------------------------

### Run example migration tests

Source: https://github.com/stokaro/ptah/blob/master/examples/migrator/README.md

Runs the example migration test from the repository root. The command exits 0 and reports the package as ok when the test passes.

```bash
go test ./examples/migrator -run TestExampleMigrations -count=1
```

--------------------------------

### Example up migration SQL

Source: https://github.com/stokaro/ptah/blob/master/migration/migrator/README.md

Example up migration file (0000000001_create_users_table.up.sql) that creates a users table and an index on the email column.

```sql
CREATE TABLE users (
    id SERIAL PRIMARY KEY,
    email VARCHAR(255) NOT NULL UNIQUE,
    name VARCHAR(255) NOT NULL,
    created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP
);

CREATE INDEX idx_users_email ON users(email);
```

--------------------------------

### Run annotation parser example

Source: https://github.com/stokaro/ptah/blob/master/examples/annotation_parser/README.md

Runs the annotation parser example from the repository root, reading the annotated Go structs in the specified file and rendering schema for PostgreSQL, MySQL, and MariaDB.

```bash
go run ./examples/annotation_parser ./examples/annotation_parser/models/example_entities.go
```

--------------------------------

### Example plan file JSON

Source: https://github.com/stokaro/ptah/blob/master/docs/site/src/content/docs/direct/apply.md

Example of a plan file generated by ptah schema plan. It records the ordered statements with per-statement safety severity and SHA-256 fingerprints of the starting and desired schema states.

```json
{
  "format_version": 1,
  "name": "plan_31a90d35a7bc",
  "dialect": "sqlite",
  "from_fingerprint": "sha256:f768e541305e03ee...",
  "to_fingerprint": "sha256:5fa9d95a6e87c76d...",
  "destructive": false,
  "statements": [
    {
      "sql": "ALTER TABLE \"users\" ADD COLUMN \"created_at\" TIMESTAMP",
      "severity": "safe",
      "reason": "does not remove data or tighten constraints"
    }
  ]
}
```

--------------------------------

### Development environment example

Source: https://github.com/stokaro/ptah/blob/master/docs/postgresql_extension_ignore.md

Configures options for a development environment, ignoring common pre-installed extensions like 'plpgsql' and 'adminpack', then runs a schema comparison with schemadiff.CompareWithOptions.

```go
// Development: ignore common pre-installed extensions
opts := config.WithIgnoredExtensions("plpgsql", "adminpack")
opts.Dialect = "postgres"
diff, err := schemadiff.CompareWithOptions(ctx, generated, database, opts, runtime)
if err != nil {
    panic(err)
}
```

--------------------------------

### Start schema server and expected output

Source: https://github.com/stokaro/ptah/blob/master/docs/site/src/content/docs/schema/serve.mdx

Starts the schema server with the given schema file and database URL. The expected output shows the server address, which is read from the listener, so using --addr 127.0.0.1:0 prints the actual chosen port.

```bash
ptah schema serve --schema-file schema.sql --db-url "sqlite://$PWD/shop.db"
```

```text
Serving a read-only schema view on http://127.0.0.1:7070
```

--------------------------------

### Quick Start: Run Integration Tests

Source: https://github.com/stokaro/ptah/blob/master/INTEGRATION_TEST_IMPLEMENTATION.md

Quick start commands for running the integration test suite. The first command uses the Makefile target, while the second runs the same tests directly via Docker Compose with an HTML report.

```bash
# Run all tests with HTML report
make integration-test

# Or directly with Docker Compose
docker compose --profile test run --rm ptah-tester --report=html
```

--------------------------------

### Expected installer output

Source: https://github.com/stokaro/ptah/blob/master/docs/site/src/content/docs/start/install.mdx

Stable output lines from the installer. The version, platform, archive, and destination vary by machine. The Version: line comes from the installed binary, which the script runs before reporting success.

```text
ptah: sha256 verified against checksums.txt
ptah: installed ptah, ptah-compat, ptah-ls in <install directory>
Version: <installed version>
```

--------------------------------

### Echo hello with expected output

Source: https://github.com/stokaro/ptah/blob/master/internal/quickstart/testdata/broken/stream-missing.mdx

A bash command that prints 'hello' to standard output. The expected output is shown as 'hello' on a single line. This example is part of a quickstart that demonstrates an output block without naming a specific stream.

```bash
echo hello

```

```text
hello

```

--------------------------------

### Run with embedded-field details

Source: https://github.com/stokaro/ptah/blob/master/examples/annotation_parser/README.md

Runs the example with SHOW_DETAILS=1 to include the embedded-field inventory, using the embedded_example.go model file.

```bash
SHOW_DETAILS=1 go run ./examples/annotation_parser ./examples/annotation_parser/models/embedded_example.go
```

--------------------------------

### Install ptah-compat and ptah-ls with Go toolchain

Source: https://github.com/stokaro/ptah/blob/master/docs/site/src/content/docs/start/install-options.mdx

Installs the compatibility binary and language server separately using the Go toolchain. The binaries land in GOBIN, or in $(go env GOPATH)/bin when GOBIN is unset, which is not automatically on PATH.

```bash
go install ptah.run/cmd/ptah-compat@vX.Y.Z
go install ptah.run/cmd/ptah-ls@vX.Y.Z
```

--------------------------------

### Testing environment example

Source: https://github.com/stokaro/ptah/blob/master/docs/postgresql_extension_ignore.md

Configures options for a testing environment with an empty ignore list to manage all extensions, then runs a schema comparison.

```go
// Testing: manage all extensions for complete control
opts := config.WithIgnoredExtensions() // Empty - manage everything
opts.Dialect = "postgres"
diff, err := schemadiff.CompareWithOptions(ctx, generated, database, opts, runtime)
if err != nil {
    panic(err)
}
```

--------------------------------

### Example UP migration SQL

Source: https://github.com/stokaro/ptah/blob/master/migration/generator/README.md

Example of a generated UP migration that creates a users table and an index.

```sql
-- Migration generated from schema differences
-- Generated on: 2023-12-21T10:30:56Z
-- Direction: UP

CREATE TABLE users (
    id SERIAL PRIMARY KEY,
    email VARCHAR(255) NOT NULL UNIQUE,
    name VARCHAR(100) NOT NULL,
    created_at TIMESTAMP NOT NULL DEFAULT NOW()
);

CREATE INDEX idx_users_email ON users(email);
```

--------------------------------

### Production environment example

Source: https://github.com/stokaro/ptah/blob/master/docs/postgresql_extension_ignore.md

Configures options for a production environment, adding more extensions to ignore (adminpack, pg_stat_statements, pg_buffercache) on top of defaults, then runs a schema comparison.

```go
// Production: be more conservative, ignore more extensions
opts := config.WithAdditionalIgnoredExtensions(
    "adminpack",
    "pg_stat_statements", 
    "pg_buffercache",
)
opts.Dialect = "postgres"
diff, err := schemadiff.CompareWithOptions(ctx, generated, database, opts, runtime)
if err != nil {
    panic(err)
}
```

--------------------------------

### Preflight output example

Source: https://github.com/stokaro/ptah/blob/master/docs/site/src/content/docs/atlas/adoption.md

Example output from the preflight command, showing the database adoption report. It indicates the history is in the Atlas-compatible layout, all revisions finished, and all revisions name migrations in the directory. The section is printed whether or not --preflight was passed.

```text
Database adoption:
  ~ the history is in the Atlas-compatible layout, in atlas_schema_revisions.atlas_schema_revisions
    native Ptah reads this layout only when the project names it: set the migration revision
    format to atlas in the native project file, or Ptah writes its own layout, reads this
    database as never migrated, and applies every recorded migration again
  ✓ every recorded revision finished
  ✓ every recorded revision names a migration this directory contains
```

--------------------------------

### Install ptah with curl

Source: https://github.com/stokaro/ptah/blob/master/README.md

Installs ptah, ptah-compat, and ptah-ls on Linux, macOS, or Windows (via WSL or similar) by downloading the current release and verifying its checksum. The installer places the binaries under your home directory.

```bash
curl -fsSL https://ptah.run/install.sh | sh
```

--------------------------------

### SQL example: Creating domains and a table with domain-typed columns

Source: https://github.com/stokaro/ptah/blob/master/docs/site/src/content/docs/atlas/schema-commands.mdx

Shows how domains are created and used in a table, illustrating the identity-based comparison rule for domains.

```sql
CREATE DOMAIN waypoint AS integer CHECK (VALUE > 0);
CREATE DOMAIN context  AS integer;
CREATE TABLE t (id serial PRIMARY KEY, a waypoint NOT NULL, b context NOT NULL);
```

--------------------------------

### Start MCP session with workspace and allow-write for migrations

Source: https://github.com/stokaro/ptah/blob/master/docs/site/src/content/docs/operate/ai-agent-changes.md

Prerequisite command to start an MCP session with a workspace, migrations directory, and target dialect. Add --allow-write for the class only if this session may apply.

```bash
ptah mcp --workspace . --migrations-dir ./migrations --dialect postgres \
  --allow-write migrations
```

--------------------------------

### Start local docs dev server

Source: https://github.com/stokaro/ptah/blob/master/docs/site/README.md

Start the local development server for the docs site. Telemetry is disabled for the Astro command.

```bash
ASTRO_TELEMETRY_DISABLED=1 npm run dev
```

--------------------------------

### Example down migration SQL

Source: https://github.com/stokaro/ptah/blob/master/migration/migrator/README.md

Example down migration file (0000000001_create_users_table.down.sql) that drops the index and table created by the corresponding up migration.

```sql
DROP INDEX IF EXISTS idx_users_email;
DROP TABLE IF EXISTS users;
```

--------------------------------

### .ptah-lint.yaml configuration example

Source: https://github.com/stokaro/ptah/blob/master/docs/site/src/content/docs/versioned/lint.md

Example configuration file for ptah lint. Sets the dialect to postgres, server version to 17, disables rules MF103 and family MY, and customizes severities for DS103, DS104, and DS102 with an exclusion pattern for legacy files.

```yaml
dialect: postgres
server-version: "17"
disabled-rules:
  - MF103
  - MY
rules:
  DS103:
    severity: warning
  DS104:
    severity: info
  DS102:
    severity: error
    exclude:
      - legacy/**
```

--------------------------------

### Run reusable components tests

Source: https://github.com/stokaro/ptah/blob/master/docs/site/src/content/docs/extend/components.md

Validates the complete copy-pasteable examples in the reusable_components_test.go file. Run from the repository root.

```bash
go test ./examples/reusable_components
```

--------------------------------

### Start MCP server with schema root

Source: https://github.com/stokaro/ptah/blob/master/docs/site/src/content/docs/operate/ai-agents.md

Starts a bare MCP server with only schema reading tools. No schema root, database, or workspace is configured until you add each scope explicitly.

```bash
ptah mcp --schema-source-root ./models
```

--------------------------------

### Start PostgreSQL and pgvector and set environment variables (Bash)

Source: https://github.com/stokaro/ptah/blob/master/docs/site/src/content/docs/inference/quick-start.md

Sets environment variables to pin ports and project name, starts PostgreSQL and pgvector via the helper script, and exports the spec path, database URL, and run ID for subsequent ptah commands. The helper writes the provider URL to `.ptah-inference/spec.yaml` and uses the Docker context named by `PTAH_DOCKER_CONTEXT` or `default`.

```bash
export PTAH_INFERENCE_POSTGRES_PORT=55432
export PTAH_INFERENCE_EMBED_PORT=58080
export PTAH_INFERENCE_PROJECT=ptah-inference-quick-start
./run.sh up

export PTAH_SPEC="$PWD/.ptah-inference/spec.yaml"
export PTAH_DB_URL="postgres://ptah:ptah@127.0.0.1:${PTAH_INFERENCE_POSTGRES_PORT}/ptah?sslmode=disable"
export PTAH_RUN_ID=quick-start
```

--------------------------------

### Principle of least privilege - good vs avoid

Source: https://github.com/stokaro/ptah/blob/master/docs/POSTGRESQL_ROLES.md

Grant only the minimum privileges required. The 'Good' example uses specific privileges, while the 'Avoid' example unnecessarily grants superuser.

```go
// Good: Specific privileges for specific purposes
//ptah:schema:role name="backup_service" login="true" replication="true" comment="Backup service role"
//ptah:schema:grant role="analytics_reader" privilege="SELECT" on_table="events"

// Avoid: Unnecessary superuser privileges
//ptah:schema:role name="backup_service" login="true" superuser="true" comment="Backup service role"
```

--------------------------------

### Install Ptah with curl and PowerShell

Source: https://github.com/stokaro/ptah/blob/master/docs/site/README.md

Commands that fetch and run the installers from the project site. The bash command uses curl with -fsSL and pipes to sh; the PowerShell command uses irm and pipes to iex. These are the current commands given to readers, replacing the older root-hosted URLs.

```bash
curl -fsSL https://ptah.run/install.sh | sh
```

```powershell
irm https://ptah.run/install.ps1 | iex
```

--------------------------------

### Create working directory and schema.sql

Source: https://github.com/stokaro/ptah/blob/master/docs/site/src/content/docs/start/quick-start.mdx

Creates the working directory and the desired-schema file schema.sql. The Bash and PowerShell tabs are equivalent alternatives for the same setup step.

```bash
mkdir ptah-quick-start
cd ptah-quick-start
cat > schema.sql <<'SQL'
CREATE TABLE users (
    id    INTEGER PRIMARY KEY,
    email TEXT NOT NULL
);
SQL
```

```powershell
New-Item -ItemType Directory ptah-quick-start | Out-Null
Set-Location ptah-quick-start
@'
CREATE TABLE users (
    id    INTEGER PRIMARY KEY,
    email TEXT NOT NULL
);
'@ | Set-Content schema.sql
```

--------------------------------

### Create schema.sql with users table

Source: https://github.com/stokaro/ptah/blob/master/docs/site/src/content/docs/direct/compare-and-drift.md

Desired schema for the drift example. Save as schema.sql in the working directory.

```sql
CREATE TABLE users (
    id INTEGER PRIMARY KEY
);
```

--------------------------------

### Seed file for demo users (dev environment)

Source: https://github.com/stokaro/ptah/blob/master/docs/site/src/content/docs/operate/seed-data.md

Example seed file `002_demo_users.dev.sql` that inserts a demo user and applies only with `--env dev`.

```sql
-- seeds/002_demo_users.dev.sql
INSERT INTO users (email, display_name) VALUES ('dev@example.com', 'Dev User');
```

--------------------------------

### Serial column sequence setup

Source: https://github.com/stokaro/ptah/blob/master/docs/site/src/content/docs/databases/ydb.md

Declares a Serial column and sets its sequence settings with ALTER SEQUENCE. The sequence path must be absolute and belong to the explicit database root. START and INCREMENT may appear independently, with optional WITH and BY. RESTART is refused in desired schemas.

```sql
CREATE TABLE `app/orders` (id BigSerial NOT NULL, PRIMARY KEY (id));
ALTER SEQUENCE `/local/app/orders/_serial_column_id` START WITH 100 INCREMENT BY 5;
```

--------------------------------

### Display migration log with ptah migrations log

Source: https://github.com/stokaro/ptah/blob/master/docs/site/src/content/docs/versioned/migration-log.md

Run `ptah migrations log` to display the migration log. The output shows the start timestamp, version, operation, outcome, actor, and source for each attempt. The example output shows a down operation that rolled back, an up operation that applied, and an up operation that failed.

```bash
ptah migrations log --db-url "$DATABASE_URL"
```

```text
STARTED               VERSION  OPERATION  OUTCOME       ACTOR         SOURCE
2026-09-21T06:11:04Z  43       down       rolled_back   release-bot   provided
2026-09-21T05:58:12Z  43       up         applied       release-bot   provided
2026-09-21T05:57:40Z  43       up         failed        release-bot   provided
```

--------------------------------

### Rebuild initial state (Bash)

Source: https://github.com/stokaro/ptah/blob/master/docs/site/src/content/docs/start/quick-start-direct.mdx

Creates the ptah-quick-start directory, writes schema.sql with the users table, and applies it with ptah schema apply. Use this if you removed the directory from the default quick start.

```bash
mkdir ptah-quick-start
cd ptah-quick-start
cat > schema.sql <<'SQL'
CREATE TABLE users (
    id    INTEGER PRIMARY KEY,
    email TEXT NOT NULL
);
SQL
ptah schema apply --schema-file schema.sql --db-url sqlite://app.db --auto-approve
```

--------------------------------

### Prepare and backfill a live table migration

Source: https://github.com/stokaro/ptah/blob/master/docs/site/src/content/docs/inference/guides/migrate-a-live-table.md

Run 'ptah inference prepare' to install the companion table and triggers and record the boundary, then run 'ptah inference backfill' to embed the source as of that boundary.

```bash
ptah inference prepare  --spec spec.yaml --db-url "$DB" --run-id "$RUN"
ptah inference backfill --spec spec.yaml --db-url "$DB" --run-id "$RUN"

```

--------------------------------

### Install ptah with PowerShell

Source: https://github.com/stokaro/ptah/blob/master/README.md

Installs ptah, ptah-compat, and ptah-ls on Windows using PowerShell. The installer selects the current release, verifies its checksum, and installs the binaries under your home directory.

```powershell
irm https://ptah.run/install.ps1 | iex
```

--------------------------------

### Create schema and set DB URL (Bash)

Source: https://github.com/stokaro/ptah/blob/master/docs/site/src/content/docs/start/quick-start-postgresql.mdx

Creates a project directory, writes a schema.sql file with a users table, and sets the DB environment variable to the connection URL for the quick-start database. Use this in a Bash shell.

```bash
mkdir ptah-postgres-quick-start
cd ptah-postgres-quick-start
cat > schema.sql <<'SQL'
CREATE TABLE users (
    id    BIGSERIAL PRIMARY KEY,
    email TEXT NOT NULL
);
SQL
export DB='postgres://ptah:ptah@localhost:55432/app?sslmode=disable'
```

--------------------------------

### Start PostgreSQL and pgvector and set environment variables (PowerShell)

Source: https://github.com/stokaro/ptah/blob/master/docs/site/src/content/docs/inference/quick-start.md

Sets environment variables to pin ports and project name, starts PostgreSQL and pgvector via the helper script, and exports the spec path, database URL, and run ID for subsequent ptah commands. The helper writes the provider URL to `.ptah-inference/spec.yaml` and uses the Docker context named by `PTAH_DOCKER_CONTEXT` or `default`.

```powershell
$env:PTAH_INFERENCE_POSTGRES_PORT = '55432'
$env:PTAH_INFERENCE_EMBED_PORT = '58080'
$env:PTAH_INFERENCE_PROJECT = 'ptah-inference-quick-start'
.\run.ps1 up

$env:PTAH_SPEC = (Resolve-Path .\.ptah-inference\spec.yaml).Path
$env:PTAH_DB_URL = "postgres://ptah:ptah@127.0.0.1:$($env:PTAH_INFERENCE_POSTGRES_PORT)/ptah?sslmode=disable"
$env:PTAH_RUN_ID = 'quick-start'
```

--------------------------------

### Seed file for countries (all environments)

Source: https://github.com/stokaro/ptah/blob/master/docs/site/src/content/docs/operate/seed-data.md

Example seed file `001_countries.all.sql` that inserts country rows and applies in every environment.

```sql
-- seeds/001_countries.all.sql
INSERT INTO countries (code, name) VALUES ('US', 'United States');
INSERT INTO countries (code, name) VALUES ('DE', 'Germany');
```

--------------------------------

### Add install directory to PATH on Linux and macOS

Source: https://github.com/stokaro/ptah/blob/master/docs/site/src/content/docs/start/install.mdx

Exports the default install directory to PATH for the current terminal. The installer prints this only when the destination is not already on PATH. Add it to your shell startup file to keep it.

```bash
export PATH="$HOME/.local/bin:$PATH"
```

--------------------------------

### Example DOWN migration SQL

Source: https://github.com/stokaro/ptah/blob/master/migration/generator/README.md

Example of a generated DOWN migration that drops the index and table created by the UP migration.

```sql
-- Migration rollback
-- Generated on: 2023-12-21T10:30:56Z
-- Direction: DOWN

DROP INDEX IF EXISTS idx_users_email;
DROP TABLE IF EXISTS users;
```

--------------------------------

### Install ptah with Homebrew

Source: https://github.com/stokaro/ptah/blob/master/docs/site/src/content/docs/start/install-options.mdx

Installs the newest tagged release of ptah on macOS or Linux using Homebrew.

```bash
brew install stokaro/ptah/ptah
```

--------------------------------

### Expected output headings

Source: https://github.com/stokaro/ptah/blob/master/examples/extension_ignore/README.md

Stable output headings from the example. The final case reports both 'adminpack' and 'plpgsql' for removal because its explicit empty ignore list manages every extension.

```text
1. Default Behavior (ignores 'plpgsql'):
2. Custom Ignore List (ignore 'adminpack' only):
3. Additional Ignored Extensions (default + 'adminpack'):
4. Manage All Extensions (no ignoring):
```

--------------------------------

### Install ptah edge (master) with Homebrew

Source: https://github.com/stokaro/ptah/blob/master/docs/site/src/content/docs/start/install-options.mdx

Installs the current master branch of ptah via Homebrew. The edge formula builds from source, installing Go as a build dependency, and represents the development branch, not a released or signed archive.

```bash
brew install --HEAD stokaro/ptah/ptah-edge
```

--------------------------------

### Build and render a table AST with ast.NewCreateTable and builtin.RenderSQL

Source: https://github.com/stokaro/ptah/blob/master/docs/site/src/content/docs/extend/components.md

Complete example using only public packages to build a table AST and render it to PostgreSQL SQL. The output shows the expected SQL shape with a comment header and quoted identifiers.

```go
package main

import (
	"fmt"
	"log"

	"ptah.run/core/ast"
	"ptah.run/engine/builtin"
)

func main() {
	table := ast.NewCreateTable("users").
		AddColumn(ast.NewColumn("id", "SERIAL").SetPrimary()).
		AddColumn(ast.NewColumn("email", "TEXT").SetNotNull().SetUnique())

	sql, err := builtin.RenderSQL("postgres", table)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(sql)
}
```

```sql
-- POSTGRES TABLE: users --
CREATE TABLE "users" (
  "id" SERIAL PRIMARY KEY NOT NULL,
  "email" TEXT UNIQUE NOT NULL
);
```

--------------------------------

### Rebuild initial state (PowerShell)

Source: https://github.com/stokaro/ptah/blob/master/docs/site/src/content/docs/start/quick-start-direct.mdx

Creates the ptah-quick-start directory, writes schema.sql with the users table, and applies it with ptah schema apply. Use this if you removed the directory from the default quick start.

```powershell
New-Item -ItemType Directory ptah-quick-start | Out-Null
Set-Location ptah-quick-start
@'
CREATE TABLE users (
    id    INTEGER PRIMARY KEY,
    email TEXT NOT NULL
);
'@ | Set-Content schema.sql
ptah schema apply --schema-file schema.sql --db-url sqlite://app.db --auto-approve
```

--------------------------------

### Verify Homebrew install

Source: https://github.com/stokaro/ptah/blob/master/docs/release_process.md

Install and verify the Homebrew tap. Runs the version commands for ptah, ptah-ls, and ptah-compat.

```bash
brew update
brew install stokaro/ptah/ptah
ptah version
ptah-ls --version
ptah-compat migrate --help
```

--------------------------------

### Role naming best practices

Source: https://github.com/stokaro/ptah/blob/master/docs/POSTGRESQL_ROLES.md

Use descriptive names that clearly indicate the role's purpose, as shown in these examples for read-only, read-write, and admin roles.

```go
//ptah:schema:role name="app_readonly" login="true" comment="Application read-only access"
//ptah:schema:role name="app_readwrite" login="true" comment="Application read-write access"
//ptah:schema:role name="app_admin" login="true" superuser="true" comment="Application administrator"
```

--------------------------------

### Publish release and run in environments

Source: https://github.com/stokaro/ptah/blob/master/docs/site/src/content/docs/inference/strategies/production-rollout.md

Publishes a release with --publish-evidence and then runs plan and prepare in each environment using --release. The first command runs once from the machine holding the file; the subsequent commands run in each environment without needing the file or a ConfigMap.

```bash
# Once, from the machine that holds the file.
ptah inference plan --spec spec-v2.yaml --db-url "$DEV" \
  --publish-evidence oci://registry.example.com/search-embeddings:release

# In each environment afterwards. No file, and no ConfigMap to keep in step.
ptah inference plan     --release "$RELEASE" --db-url "$STAGING"
ptah inference prepare  --release "$RELEASE" --db-url "$STAGING" --run-id "$RUN"
```

--------------------------------

### Run backfill with batch and timeout flags

Source: https://github.com/stokaro/ptah/blob/master/docs/site/src/content/docs/inference/strategies/plan-provider-capacity.md

Command to run a backfill with recommended starting values for a hosted provider: --batch-inputs 64, --batch-rows 500, --provider-timeout 60s. --batch-inputs is the number of texts per request (provider limit is the ceiling), --batch-rows bounds cancellation wait, and --provider-timeout bounds one request.

```bash
ptah inference backfill --spec spec.yaml --db-url "$DB" --run-id "$RUN" \
  --batch-rows 500 \
  --batch-inputs 64 \
  --provider-timeout 60s
```

--------------------------------

### Start ALTER without timeout

Source: https://github.com/stokaro/ptah/blob/master/docs/site/src/content/docs/operate/zero-downtime-changes.mdx

Starts an ALTER TABLE that waits for the lock without a timeout, running in the background.

```console
docker exec -d ptah-zero-downtime psql -U ptah -d app -c "ALTER TABLE users ADD COLUMN nickname TEXT;"

```

--------------------------------

### Render YAML schema via CLI

Source: https://github.com/stokaro/ptah/blob/master/docs/site/src/content/docs/extend/components.md

CLI equivalent of the YAML schema rendering example. Renders SQL from a YAML schema file for the postgres dialect.

```bash
ptah schema render --schema-file schema.yaml --dialect postgres
```

--------------------------------

### Verify all three binaries

Source: https://github.com/stokaro/ptah/blob/master/docs/site/src/content/docs/start/install.mdx

Runs each binary's version command to confirm installation. Each command prints a version, commit, build date, Go toolchain, and platform. Note that ptah-compat uses a version command rather than a --version flag.

```console
ptah version
ptah-compat version
ptah-ls --version
```

--------------------------------

### Install ptah CLI with Go toolchain

Source: https://github.com/stokaro/ptah/blob/master/docs/site/src/content/docs/start/install-options.mdx

Installs the native ptah CLI from a tagged module version using the Go toolchain.

```bash
go install ptah.run/cmd/ptah@vX.Y.Z
```

--------------------------------

### Basic Migration Execution with NewFSMigrator

Source: https://github.com/stokaro/ptah/blob/master/migration/migrator/README.md

Connects to a PostgreSQL database with a 10-second timeout context, creates a filesystem from the migrations directory, and runs all pending migrations via migrator.NewFSMigrator and MigrateUp. Panics on connection or migration errors.

```go
package main

import (
    "context"
    "os"
    "time"

    "ptah.run/dbschema"
    "ptah.run/migration/migrator"
)

func main() {
    // Connect to database. Supply a context so the initial Ping cannot block
    // indefinitely on a stuck host.
    ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
    defer cancel()
    conn, err := dbschema.ConnectToDatabase(ctx, 
```

--------------------------------

### Create the up migration file

Source: https://github.com/stokaro/ptah/blob/master/docs/site/src/content/docs/versioned/apply.md

Save this SQL as `migrations/1785255952_init.up.sql` to define the initial schema.

```sql
CREATE TABLE users (
    id    INTEGER PRIMARY KEY,
    email TEXT NOT NULL
);
```

--------------------------------

### Example error from FILE category

Source: https://github.com/stokaro/ptah/blob/master/docs/site/src/content/docs/schema/protobuf.md

Example error message when using the FILE category on a generated schema, showing a deleted field failure.

```text
acme/shop/v1/schema.proto:8:1:Previously present field "3" with name "nickname" on message "Customer" was deleted.

```

--------------------------------

### Create schema and set DB URL (PowerShell)

Source: https://github.com/stokaro/ptah/blob/master/docs/site/src/content/docs/start/quick-start-postgresql.mdx

Creates a project directory, writes a schema.sql file with a users table, and sets the $DB variable to the connection URL for the quick-start database. Use this in PowerShell.

```powershell
New-Item -ItemType Directory ptah-postgres-quick-start | Out-Null
Set-Location ptah-postgres-quick-start
@'
CREATE TABLE users (
    id    BIGSERIAL PRIMARY KEY,
    email TEXT NOT NULL
);
'@ | Set-Content schema.sql
$DB = 'postgres://ptah:ptah@localhost:55432/app?sslmode=disable'
```

--------------------------------

### Example schema.hcl content

Source: https://github.com/stokaro/ptah/blob/master/docs/site/src/content/docs/direct/inspect.md

Example HCL content that `ptah schema inspect` writes to `schema.hcl`, showing a `users` table with columns and a primary key.

```hcl
table "users" {
  column "email" {
    type = TEXT
    unique = true
  }
  column "id" {
    type = INTEGER
    auto_increment = true
  }
  column "name" {
    type = TEXT
    null = true
  }
  primary_key {
    columns = [column.id]
  }
}
```

--------------------------------

### Run all docs checks and build

Source: https://github.com/stokaro/ptah/blob/master/docs/site/README.md

Run the full set of documentation checks and build for the Ptah docs site. Requires Node.js and npm; telemetry is disabled for the Astro commands. The sequence installs dependencies, runs self-tests and checks for links, route retirement, core doc links, page health, content inventory, support matrix, exit codes, examples, visual assets, navigation, search ranking, accessibility, and visual snapshots, then builds the site and audits dependencies.

```bash
npm ci
ASTRO_TELEMETRY_DISABLED=1 npm run check:links:selftest
ASTRO_TELEMETRY_DISABLED=1 npm run check:links
ASTRO_TELEMETRY_DISABLED=1 npm run check:route-retirement:selftest
ASTRO_TELEMETRY_DISABLED=1 npm run check:route-retirement
ASTRO_TELEMETRY_DISABLED=1 npm run check:core-doc-links
ASTRO_TELEMETRY_DISABLED=1 npm run check:page-health:selftest
ASTRO_TELEMETRY_DISABLED=1 npm run check:page-health
ASTRO_TELEMETRY_DISABLED=1 npm run check:content-inventory:selftest
ASTRO_TELEMETRY_DISABLED=1 npm run check:support-matrix:selftest
ASTRO_TELEMETRY_DISABLED=1 npm run check:support-matrix
ASTRO_TELEMETRY_DISABLED=1 npm run check:exit-codes
ASTRO_TELEMETRY_DISABLED=1 npm run check:examples:selftest
ASTRO_TELEMETRY_DISABLED=1 npm run check:examples
ASTRO_TELEMETRY_DISABLED=1 npm run check:visual-assets:selftest
ASTRO_TELEMETRY_DISABLED=1 npm run check:visual-assets
ASTRO_TELEMETRY_DISABLED=1 npm run check:navigation:selftest
ASTRO_TELEMETRY_DISABLED=1 npm run check:search-ranking:selftest
ASTRO_TELEMETRY_DISABLED=1 npm run check:accessibility:selftest
ASTRO_TELEMETRY_DISABLED=1 npm run check:visual-snapshots:selftest
ASTRO_TELEMETRY_DISABLED=1 npm run build
ASTRO_TELEMETRY_DISABLED=1 npm run check:accessibility
ASTRO_TELEMETRY_DISABLED=1 npm run check:visual-snapshots -- --output /tmp/ptah-docs-snapshots
ASTRO_TELEMETRY_DISABLED=1 npm run check:navigation
ASTRO_TELEMETRY_DISABLED=1 npm run check:search-ranking
npm run versions:selftest
npm run root-assets:selftest
npm run check:pages-root:selftest
npm run check:pages-root
npm audit --audit-level=low
```

--------------------------------

### Create migration pair (Bash and PowerShell)

Source: https://github.com/stokaro/ptah/blob/master/docs/site/src/content/docs/start/quick-start-migrations.mdx

Creates the migration directory and writes the up and down SQL files for version 1700000000. The up file creates the users table; the down file drops it. Use the fixed version so output matches the tutorial.

```bash
mkdir -p ptah-versioned/migrations
cd ptah-versioned
cat > migrations/1700000000_create_users.up.sql <<'SQL'
CREATE TABLE users (
    id    INTEGER PRIMARY KEY,
    email TEXT NOT NULL
);
SQL
cat > migrations/1700000000_create_users.down.sql <<'SQL'
DROP TABLE users;
SQL

```

```powershell
New-Item -ItemType Directory ptah-versioned/migrations | Out-Null
Set-Location ptah-versioned
@'
CREATE TABLE users (
    id    INTEGER PRIMARY KEY,
    email TEXT NOT NULL
);
'@ | Set-Content migrations/1700000000_create_users.up.sql
@'
DROP TABLE users;
'@ | Set-Content migrations/1700000000_create_users.down.sql

```

--------------------------------

### Quick Start Commands for Running Tests

Source: https://github.com/stokaro/ptah/blob/master/README-TESTING.md

Run unit tests, specific tests with verbose output, new visitor methods tests, or the comprehensive test suite using the provided PowerShell scripts.

```powershell
# Run unit tests only (fast, no databases needed)
.\test-simple.ps1

# Run specific test with detailed output
.\run-integration-tests.ps1 -TestPattern "TestNewVisitorMethods_UnitTests" -Verbose

# Run all new visitor methods tests
.\test-new-methods.ps1

# Run comprehensive test suite
.\test-all.ps1
```

--------------------------------

### Expected output fragments

Source: https://github.com/stokaro/ptah/blob/master/examples/annotation_parser/README.md

Stable output fragments from the example command, reporting four tables and sections for each dialect. The repository example gate checks these fragments.

```text
Found 4 tables
=== POSTGRES ===
CREATE TABLE "users"
=== MYSQL ===
=== MARIADB ===

```

--------------------------------

### Set Serial column start and increment in Go and YDB ALTER SEQUENCE

Source: https://github.com/stokaro/ptah/blob/master/docs/site/src/content/docs/databases/ydb.md

These two blocks form a single workflow: the Go marker declares the Serial column's identity start and increment, and the SQL statement, written by the planned migration after the table, applies them. The ALTER SEQUENCE requires the sequence's absolute path, which begins with the database's own; START alone changes the recorded start but never moves the next value, so the RESTART is needed for a new table.

```go
//ptah:schema:field name="id" type="BIGSERIAL" primary="true" identity_start="1000" identity_increment="10"
```

```sql
ALTER SEQUENCE `/local/orders/_serial_column_id` START WITH 1000 INCREMENT BY 10 RESTART WITH 1000;
```

--------------------------------

### Apply initial schema with ptah schema apply

Source: https://github.com/stokaro/ptah/blob/master/docs/site/src/content/docs/direct/apply.md

Apply the initial schema to create the database and make it match the file. Uses `--auto-approve` to skip the approval prompt.

```console
ptah schema apply --db-url "sqlite://app.db" --schema-file schema.sql --auto-approve
```

--------------------------------

### Run conformance suite with make conformance

Source: https://github.com/stokaro/ptah/blob/master/docs/conformance.md

Runs the conformance suite from the repository root.

```bash
make conformance
```

--------------------------------

### Example SQL output from ptah db read

Source: https://github.com/stokaro/ptah/blob/master/docs/site/src/content/docs/direct/inspect.md

Example of the SQL output produced by `ptah db read` for a SQLite database. Standard output contains SQL only.

```sql
CREATE TABLE "users" (
  "id" INTEGER PRIMARY KEY AUTOINCREMENT,
  "email" TEXT NOT NULL UNIQUE,
  "name" TEXT
);
```

--------------------------------

### CREATE TRIGGER examples for PostgreSQL

Source: https://github.com/stokaro/ptah/blob/master/docs/site/src/content/docs/databases/postgresql.md

Two example trigger definitions showing supported syntax: one with UPDATE OF, WHEN condition, and FOR EACH ROW; another with transition tables and FOR EACH STATEMENT.

```sql
CREATE TRIGGER orders_touch BEFORE UPDATE OF total, status OR INSERT ON orders
  FOR EACH ROW WHEN (NEW.total > 0) EXECUTE FUNCTION touch_order();
CREATE TRIGGER orders_audit AFTER UPDATE ON orders
  REFERENCING OLD TABLE AS before_rows NEW TABLE AS after_rows
  FOR EACH STATEMENT EXECUTE FUNCTION audit_orders();
```

--------------------------------

### Build the state: create directory and file

Source: https://github.com/stokaro/ptah/blob/master/internal/quickstart/testdata/journey/start/first.mdx

Creates a working directory, writes 'kept' to note.txt, and displays the file contents. Expected output is 'kept'.

```console
mkdir work
cd work
printf 'kept\n' > note.txt
cat note.txt
```

--------------------------------

### Preview the apply with a dry run

Source: https://github.com/stokaro/ptah/blob/master/docs/site/src/content/docs/versioned/apply.md

Run this command to preview the migration without touching the database. The expected output is shown in the next block.

```console
ptah migrations up --db-url "sqlite://app.db" --migrations-dir ./migrations --dry-run
```

--------------------------------

### Start a long-running transaction

Source: https://github.com/stokaro/ptah/blob/master/docs/site/src/content/docs/operate/zero-downtime-changes.mdx

Starts a transaction that reads the users table and sleeps for 20 seconds, simulating a slow query or long report. Runs in the background with -d.

```console
docker exec -d ptah-zero-downtime psql -U ptah -d app -c "BEGIN; SELECT count(*) FROM users; SELECT pg_sleep(20);"

```

--------------------------------

### Run all reusable components tests

Source: https://github.com/stokaro/ptah/blob/master/examples/reusable_components/README.md

Runs all tests in the reusable components example package from the repository root. The command exits 0 and reports the package as ok, opening no listener and connecting to no database.

```bash
go test ./examples/reusable_components -count=1
```

--------------------------------

### Example output of ptah db verify

Source: https://github.com/stokaro/ptah/blob/master/docs/site/src/content/docs/operate/verify-a-release.md

Example stdout from the ptah db verify command showing a verified and a failed check, including the assertion that failed and the final verdict.

```text
STATUS    NAME                  SOURCE
verified  every user has a tier  release-checks/010_tier_backfill.sql
failed    no user lost an email  release-checks/010_tier_backfill.sql

failed: no user lost an email
  assert: SELECT COUNT(*) = 0 FROM users WHERE email IS NULL

Verdict: failed (1 verified, 1 failed, 0 errored of 2)
```

--------------------------------

### Run live root check with --live

Source: https://github.com/stokaro/ptah/blob/master/docs/site/README.md

Runs the live check that requests every root file, requires a 200, and verifies each installer matches its source under public/. It is scheduled in .github/workflows/install-smoke.yml, not on push, to avoid racing the Pages deploy.

```bash
node scripts/check-pages-root.mjs --live
```

--------------------------------

### Start interactive session with ptah assist

Source: https://github.com/stokaro/ptah/blob/master/docs/site/src/content/docs/operate/ai-assist.md

Starts an interactive Ptah assist session. At a terminal, the prompt is an edited line with key bindings for navigation and editing. The answer is rendered as Markdown once complete.

```bash
ptah assist
```

--------------------------------

### Unit Test Commands (No Database)

Source: https://github.com/stokaro/ptah/blob/master/README-TESTING.md

Run AST tests and core renderer unit tests for new visitor methods using Go's test command.

```powershell
# AST tests - test the AST node functionality
go test -C core/ast -v

# Core renderer unit tests - test new visitor methods
go test -C engine/builtin -run "TestNewVisitorMethods_UnitTests" -v
```

--------------------------------

### test-all.ps1 Usage Examples

Source: https://github.com/stokaro/ptah/blob/master/TESTING.md

Examples of using `test-all.ps1` with various options: `-Category` for test categories (unit, integration, new-methods, all), `-Dialect` for database dialects (postgresql, mysql, mariadb, all), and `-Quick` for essential tests only.

```powershell
# Run all tests
.\test-all.ps1

# Run only unit tests (fast, no databases)
.\test-all.ps1 -Category unit

# Run integration tests for specific dialect
.\test-all.ps1 -Category integration -Dialect postgresql

# Run essential tests only (faster)
.\test-all.ps1 -Quick

# Test specific dialect
.\test-all.ps1 -Dialect mysql
```

--------------------------------

### Canonical HCL schema example

Source: https://github.com/stokaro/ptah/blob/master/docs/site/src/content/docs/schema/validate-and-format.md

Example of a canonically formatted HCL schema file after running `ptah schema fmt`. The rewrite uses HashiCorp HCL's canonical layout and changes no declared values.

```hcl
schema "public" {}
table "customers" {
  schema = schema.public
  column "id" {
    type = int
  }
  column "email" {
    type = varchar(255)
    null = false
  }
}
```

--------------------------------

### Start disposable PostgreSQL container

Source: https://github.com/stokaro/ptah/blob/master/docs/site/src/content/docs/start/quick-start-postgresql.mdx

Starts a disposable PostgreSQL 18 container named ptah-quick-start on port 55432 to avoid collisions with an existing local PostgreSQL. Credentials are hard-coded because the database is meant to be thrown away.

```bash
docker run -d --name ptah-quick-start \
  -e POSTGRES_USER=ptah -e POSTGRES_PASSWORD=ptah -e POSTGRES_DB=app \
  -p 55432:5432 postgres:18-alpine
```