# Atlas docs coverage

Current Atlas documentation crosswalk for Ptah compatibility, implementation, conformance, and follow-up work.

Source: https://docs.ptah.run/v0.8.0/atlas/docs-coverage/

The matrix below maps the reviewed Atlas documentation areas to Ptah pages,
implementation status and conformance coverage. It measures documentation
coverage, not full parity.

Research date: July 28, 2026.

Every status field below was re-measured against the built binaries on
2026-09-09. A section reading `Partial` names what remains and links the issue
that owns it, so the field points at something a reader can follow. The
[feature matrix](../feature-matrix/) is generated per capability and is the
maintained answer for anything it covers. Update this page when the conformance
assets it cites change, and re-measure a status field rather than re-tensing
it.

Official Atlas sources reviewed:

- [Atlas documentation home](https://atlasgo.io/docs)
- [Feature compatibility](https://atlasgo.io/features)
- [CLI reference](https://atlasgo.io/cli-reference)
- [Schema inspection](https://atlasgo.io/inspect)
- [Declarative schema apply](https://atlasgo.io/declarative/apply)
- [Declarative schema diff](https://atlasgo.io/declarative/diff)
- [Versioned migrations introduction](https://atlasgo.io/versioned/intro)
- [Versioned migration apply](https://atlasgo.io/versioned/apply)
- [Versioned migration lint](https://atlasgo.io/versioned/lint)
- [Down migrations](https://atlasgo.io/versioned/down)
- [Import existing databases or migrations](https://atlasgo.io/versioned/import)
- [Pre-execution checks](https://atlasgo.io/versioned/checks)
- [Migration directory checkpoints](https://atlasgo.io/versioned/checkpoint)
- [Pre-apply drift detection](https://atlasgo.io/versioned/drift-detection)
- [Atlas HCL syntax](https://atlasgo.io/atlas-schema/hcl)
- [Atlas project configuration](https://atlasgo.io/atlas-schema/projects)
- [Dev database](https://atlasgo.io/concepts/dev-database)
- [Atlas Registry](https://atlasgo.io/cloud/features/registry)
- [Atlas Cloud deployment reporting](https://atlasgo.io/cloud/deployment)
- [Schema testing](https://atlasgo.io/testing/schema)
- [Migration testing](https://atlasgo.io/testing/migrate)
- [Migration plan testing](https://atlasgo.io/testing/plan)

Availability classifications below are based on those official pages,
especially the Atlas [feature compatibility](https://atlasgo.io/features) page
when it separates Open, Pro, and Cloud behavior.

## Status terms

| Status | Meaning |
| --- | --- |
| Documented | Ptah docs explain the supported behavior and link to exact reference material. |
| Partial | Ptah implements or documents part of the Atlas area, but gaps remain. |
| Out of scope | The area is Atlas Pro, Cloud, registry, account, UI, or commercial behavior rather than an Atlas OSS drop-in target. |
| Native | Atlas keeps the workflow in its Pro or Cloud build, and Ptah implements it natively and free. It sits beside Out of scope rather than inside it: the same Atlas gating, and the opposite answer here. |
| Measured | `ptah-atlas-conformance` has probes for this area. |
| Unmeasured | The behavior may exist, but current conformance reports do not prove it. |

## Coverage matrix

Each area below records how Atlas documents it, where Ptah documents it, the
implementation status and the conformance status. This table is the index; the
sections carry the detail.

| Atlas docs area | Ptah status |
| --- | --- |
| [Top-level docs structure and getting started](#top-level-docs-structure-and-getting-started) | Documented |
| [Installation and CLI entry points](#installation-and-cli-entry-points) | Documented |
| [CLI command and flag reference](#cli-command-and-flag-reference) | Partial |
| [Schema inspection](#schema-inspection) | Partial |
| [Declarative schema apply](#declarative-schema-apply) | Documented |
| [Declarative schema diff](#declarative-schema-diff) | Documented |
| [Desired-state sources](#desired-state-sources) | Documented |
| [Atlas HCL schema syntax](#atlas-hcl-schema-syntax) | Partial |
| [Atlas project config (`atlas.hcl`)](#atlas-project-config-atlashcl) | Partial |
| [Dev database](#dev-database) | Documented |
| [Versioned migrations overview](#versioned-migrations-overview) | Documented |
| [Migration apply](#migration-apply) | Documented |
| [Migration down and rollback](#migration-down-and-rollback) | Documented |
| [Migration diff generation](#migration-diff-generation) | Partial |
| [Migration linting](#migration-linting) | Partial |
| [Migration directory integrity, hash, and validation](#migration-directory-integrity-hash-and-validation) | Documented |
| [Migration import](#migration-import) | Partial |
| [Manual migrations and troubleshooting](#manual-migrations-and-troubleshooting) | Documented |
| [Drift detection](#drift-detection) | Native |
| [Checkpoints](#checkpoints) | Native |
| [Pre-migration checks and policy workflows](#pre-migration-checks-and-policy-workflows) | Partial |
| [Testing framework](#testing-framework) | Native |
| [Declarative reference data](#declarative-reference-data) | Native |
| [Supported databases](#supported-databases) | Documented |
| [Database object kinds](#database-object-kinds) | Partial |
| [Atlas Registry](#atlas-registry) | Out of scope |
| [Atlas Cloud deployment reporting](#atlas-cloud-deployment-reporting) | Out of scope |
| [Cloud-only workflows and account commands](#cloud-only-workflows-and-account-commands) | Out of scope |
| [CI integrations](#ci-integrations) | Documented |
| [Conformance evidence](#conformance-evidence) | Documented |
| [License and implementation boundary](#license-and-implementation-boundary) | Documented |

### Top-level docs structure and getting started

**Atlas availability.** Open docs

**Ptah documentation.** [Quick start](../../start/quick-start/), [Choose a workflow](../../start/choose-a-workflow/)

**Implementation status.** Documented for Ptah workflows. Not a one-to-one Atlas docs clone.

**Conformance status.** Unmeasured; docs structure is not a runtime behavior.

### Installation and CLI entry points

**Atlas availability.** Open docs

**Ptah documentation.** [Install Ptah](../../start/install/), [Native commands](../../reference/native-commands/), [Atlas compatibility overview](../overview/)

**Implementation status.** Documented. Atlas-compatible invocations run the separate `ptah-compat` drop-in binary.

**Conformance status.** Partially measured by command-resolution probes.

### CLI command and flag reference

**Atlas availability.** Open for OSS commands; Pro/Cloud commands excluded from OSS target

**Ptah documentation.** [Native commands](../../reference/native-commands/), [Atlas-compatible commands](../../reference/atlas-commands/), [Exit codes](../../reference/exit-codes/)

**Implementation status.** Partial. Core command paths are documented and the flag reference is generated from the command tree, so it cannot drift from what Ptah registers. Nothing measures that surface against the Atlas CE flag reference, so a CE flag Ptah does not register stays invisible; [`stokaro/ptah#3109`](https://github.com/stokaro/ptah/issues/3109) owns it.

**Conformance status.** Measured for selected command paths and flags only.

### Schema inspection

**Atlas availability.** Open

**Ptah documentation.** [Atlas-compatible commands](../../reference/atlas-commands/), [Capabilities](../../reference/capabilities/), [Feature matrix](../feature-matrix/)

**Implementation status.** Partial. `ptah db read` remains the native Ptah schema-read path, and `ptah-compat schema inspect` reads `atlas.hcl` exporter blocks and the documented `--exclude` field selectors. The split `--out-dir` export writes no entry point, so it does not round-trip the way Atlas documents; [`stokaro/ptah#3110`](https://github.com/stokaro/ptah/issues/3110) owns it.

`ptah-compat schema inspect` emits Atlas-shaped output without Ptah status
banners: HCL by default, or HCL, SQL, and JSON through their explicit helper
templates. Bare `--format hcl`, `--format sql`, and `--format json` write the
literal value with no line feed. Surrounding whitespace is also preserved byte
for byte. Those literal cases match Atlas CE v1.3.0.

Custom templates use the supported inspect helpers. HCL/SQL split-write file
exports use the documented Atlas split strategies: per object by default,
`split "schema"`, `split "type"`, and an optional file-extension argument. The
command also supports OSS `--exclude` resource filters, including the
Atlas-documented `*[type=extension].version` field selector with
schema-qualified globs.

Local schema files, migration directories, and `env://` references are inspected through required `--dev-url` dev-database evaluation (reset, materialize, introspect). Other field-level exclude selectors fail explicitly; exporter blocks remain tracked gaps.

`ptah-compat schema inspect --include` positively selects which top-level resources the output keeps, through the same selector engine as `schema apply` and `schema diff`: `--schema` names the universe for schema-owned resources, `--include` picks resources, and `--exclude` subtracts. Database-wide extensions remain visible across schema selection. An extension-only include controls which extension identities inspection renders; when a non-extension resource matches, all extensions ride as support even beside extension selectors. On comparison verbs that support is non-removing, while schema-only and extension-only scopes remain authoritative. Exclusions still subtract afterward. The pinned Atlas CE binary does not register the flag on this command and rejects it as an unknown flag, so this is a Pro-surface spelling Ptah implements openly rather than a CE parity target.

**Conformance status.** Partially measured by live SQLite HCL/SQL/JSON/custom-template/split-write/exclude/compat probes and CLI flag probes.

### Declarative schema apply

**Atlas availability.** Open

**Ptah documentation.** [Feature matrix](../feature-matrix/), [Atlas schema commands](../schema-commands/)

**Implementation status.** Documented. `ptah schema apply` is the native path and `ptah-compat schema apply` is the Atlas spelling over it. The compatibility verb diffs a live database against local `.hcl`, `.yaml`, `.sql` and `.dbml` desired files, a database URL, a replayed migration directory or an `env://` reference; honors `--dry-run`, `--edit`, the three Atlas transaction modes, `--exclude`/`--include`/`--schema` scoping, and a saved `--plan` file; rehearses the ordered plan on `--dev-url` before touching the target; and refuses a plan the selected env's `lint` policy rates as an error unless `--skip-lint` is passed.

`ptah-compat schema apply` reads a live database, diffs it against local
`file://` `.hcl`, `.yaml`, `.yml`, or `.sql` desired schema files, prints
planned SQL, and applies after interactive confirmation or explicit
`--auto-approve`. It also:

- can take defaults from evaluated local `atlas.hcl` env expressions including `env.url`, `env.src`, `env.schema.src`, `env.dev`, `env.exclude`, `env.schema.mode`, `format.schema.apply`, and supported `diff` policy
- supports `--dry-run`
- supports Atlas transaction modes `file`, `all`, and `none` for the generated plan
- supports `--exclude` and disabled `schema.mode` resource filters for the local-file comparison
- can use PostgreSQL concurrent index creation when `--tx-mode none` is set
- supports `--edit` to open the planned SQL in `$VISUAL`/`$EDITOR` before approval so the edited SQL is what gets applied

`--plan file://<path>` executes a pre-approved local plan file saved by `schema plan`, and `--lock-timeout` bounds waiting for the session advisory lock that serializes concurrent applies against one target, with an explicit unlocked-with-note decision on dialects without advisory locks.

`--to` also accepts one directly connectable database URL, one migration directory (`file://` directory containing `atlas.sum`) replayed on the required `--dev-url` dev database, or one `env://` reference resolved through the evaluated `atlas.hcl` env; unsupported schemes such as `atlas://` fail before the target database is contacted.

Before a non-dry-run apply, `--dev-url` rehearses the exact ordered plan on the reset dev database with the target's current schema recreated first; a failed rehearsal refuses the apply with the target unchanged.

`--schema` and `--include` positively scope both comparison sides with union
semantics, exclusion subtraction, and cross-scope dependency diagnostics. An
explicit include selection matching neither side refuses instead of reporting
a synced schema.

**Conformance status.** Partially measured with local schema files and live SQLite apply/no-op/dry-run/transaction-mode/exclude/config-driven format/schema-mode coverage, plus CLI-surface flag probes.

### Declarative schema diff

**Atlas availability.** Open

**Ptah documentation.** [Feature matrix](../feature-matrix/), [Atlas schema commands](../schema-commands/)

**Implementation status.** Documented. `ptah schema diff` is the native path and `ptah-compat schema diff` the Atlas spelling. Both sides of the comparison accept a database URL, a desired-schema file, a replayed migration directory or an `env://` reference, and the output is the ordered SQL that reconciles them.

`ptah-compat schema diff` supports local `file://` schema-file diffs for `.hcl`, `.yaml`, `.yml`, and `.sql` sources, Atlas-style SQL/custom output formatting with `--format`, `sql`, and `.MarshalSQL`, `--exclude` and disabled `schema.mode` resource filters over the local inputs, and evaluated `atlas.hcl` defaults for `env.schema.src`, `env.dev`, `env.exclude`, `env.schema.mode`, `format.schema.diff`, and supported `diff` policy.

`--from` and `--to` also accept one directly connectable database URL, one migration directory replayed on the required `--dev-url` dev database, or one `env://` reference resolved through the evaluated `atlas.hcl` env, with the dialect pinned by `--dev-url` first and then by database URLs.

`--schema` and `--include` positively scope both diff sides with the same selection semantics as `schema apply`. Dev-database simulation and export remain incomplete. The pinned Atlas CE flag surface does not register `schema diff --web`. Ptah registers it and writes a self-contained HTML ERD of the compared schemas locally, marking each table added, changed or removed; nothing is published.

**Conformance status.** Partially measured with local schema-file default, custom-template, no-op-template, invalid-template, exclude, config-driven skip-drop probes, and CLI-surface flag probes.

### Desired-state sources

**Atlas availability.** The Atlas docs describe SQL, HCL, and external schema integrations, with some data sources Pro. Measured 2026-08-01: the pinned Atlas CE v1.2.0 binary rejects `data "external_schema"` with "not supported by the community version", so the external-schema data source is not an Open capability

**Ptah documentation.** [Composite desired schema](../../schema/composite/), [ORM and external loaders](../../schema/orm-and-external/), [OCI registry artifacts](../../operate/oci-registry/), [HCL schema](../../schema/hcl/)

**Implementation status.** Documented. Native Ptah reads YAML, Go annotations, supported HCL, SQL, live databases, external programs and canonical desired-schema artifacts from a bring-your-own OCI registry, and the same `ptah.yaml external_schema` block feeds render, compare, drift and migration generation. `--schema-file` is repeatable on every verb that takes it, `schema inspect` included, and repeated values merge into one composite schema.

The native OCI source is available to `schema compare` and `drift` through
`--schema-file`; it is not Atlas Registry parity or an `atlas://` source for
Atlas-compatible commands. Atlas HCL `data "external_schema"` is implemented
for both binaries, gated behind `--allow-external-schema` (native) or
`PTAH_ALLOW_EXTERNAL_SCHEMA=1` (`ptah-compat`). The native `ptah.yaml
external_schema` block carries the same gate rather than running unguarded:
without the flag a render refuses with `ptah.yaml external_schema is disabled by
default; pass --allow-external-schema to execute it`. The Atlas OSS `data "sql"`,
`data "external"`, `data "runtimevar"`, and `data "template_dir"` project
sources are also implemented. Registry-backed desired-state sources remain
outside the supported compatibility subset.

**Conformance status.** Native external programs are measured by a deterministic 20-observation SQL/HCL/YAML workflow through render, compare, drift, plan, generate, apply, live SQLite facts, and convergence. A separate zero-gap tier exercises pinned GORM and SQLAlchemy providers. The native OCI round trip remains covered by Ptah's own command and integration tests rather than Atlas conformance.

### Atlas HCL schema syntax

**Atlas availability.** Open for core HCL schema; advanced objects and product-gated areas vary by feature matrix

**Ptah documentation.** [HCL schema](../../schema/hcl/), site [HCL schema reference](../../reference/hcl-schema/)

**Implementation status.** Partial. Ptah parses a strict supported subset and fails explicitly for unsupported constructs: core tables, columns, indexes, constraints, enums, schemas, selected generated and identity forms, and PostgreSQL include columns. A `view` or `materialized` block takes `column` blocks and `depends_on`, a `trigger` takes an `execute` block naming a declared function, and a `table` takes `depends_on` and `qualifier`. The subset is still a subset, and the [HCL schema reference](../../reference/hcl-schema/) states it attribute by attribute rather than this page restating a list that drifts.

**Conformance status.** Measured for current imported fixtures; not complete Atlas HCL coverage.

### Atlas project config (`atlas.hcl`)

**Atlas availability.** Open for local env config; Cloud/registry constructs are out of scope

**Ptah documentation.** [Configuration](../../reference/configuration/), site [Atlas project config reference](../project-config/)

**Implementation status.** Partial. The parser reads the env, schema, migration, lint, format and diff blocks the compatibility surface acts on. `diff.skip` acts on `drop_table` and `drop_schema` and type-checks the other thirteen CE names without acting on them; [`stokaro/ptah#3111`](https://github.com/stokaro/ptah/issues/3111) owns that and the neighboring variable-validation and `object()` gaps.

Ptah reads a documented subset into project config IR, including local env
settings, `schema.src`, `schema.mode`, output formats, supported diff and lint
policy, local variable defaults, typed variables (`string`, `number`, `bool`,
`list(string)`, `map(string)`) with `sensitive` support, string/list `--var`
overrides, locals, `getenv`, `file`, `fileset`, `format`, `jsondecode`,
`jsonencode`, `toset`,
`atlas.env`, `each.key`, `each.value`, the supported `hcl_schema`, `sql`,
`external`, `runtimevar`, and `template_dir` project data sources, and
migration-lint changeset selectors. Atlas-compatible `migrate apply` expands
labeled or unlabeled env `for_each` collections into ordered database targets.

Whole-document structural validation classifies every environment before one is
selected. Unsupported shapes fail in selected and unselected environments.
Names that Atlas CE accepts without acting on are preserved in project config
and reported once per source location. Recognized project data sources are
evaluated lazily in dependency order from selected settings, global policy,
top-level attributes, and locals; valid unreferenced sources are not opened or
executed.

Cloud and registry data sources beyond the recognized lazy subset, variable
`validation` blocks, other variable type constraints such as `object(...)`,
Atlas check-level lint policy, custom lint rules, unsupported lint analyzer
options, unsupported format blocks, unsupported diff policy fields, and remote
directory behavior are not implemented.

**Conformance status.** The committed companion reports do not yet measure
dynamic env expansion. Main-repository parser, adapter, command, and live SQLite
tests cover the supported local subset, whole-document structural decisions,
selected-environment evaluation, dependency-ordered project data sources,
multi-target apply with partial failure and retry, and ignored-name warnings.

### Dev database

**Atlas availability.** Core concept for Atlas diff/apply/lint planning; Docker/dev blocks include Pro-only baseline forms in current Atlas docs

**Ptah documentation.** [Configuration](../../reference/configuration/), [Feature matrix](../feature-matrix/)

**Implementation status.** Documented. A `--dev-url` names a disposable database the command resets before use, and it accepts a `docker://` image, an in-memory SQLite URL, or an ordinary server URL. The commands that need one say so and refuse without it rather than guessing.

**Conformance status.** Partially measured for migrate validate, migrate lint, and selected migrate diff/schema paths.

### Versioned migrations overview

**Atlas availability.** Open

**Ptah documentation.** [Versioned migrations](../../versioned/overview/), [Atlas migrate commands](../migrate-commands/), [Feature matrix](../feature-matrix/)

**Implementation status.** Documented for Ptah native workflow and Atlas-compatible command names. Runtime parity still depends on command-specific rows below.

**Conformance status.** Partially measured.

### Migration apply

**Atlas availability.** Open

**Ptah documentation.** [Apply migrations](../../versioned/apply/), [Atlas migrate commands](../migrate-commands/), [Configuration](../../reference/configuration/)

**Implementation status.** Documented. `ptah migrations up` is the native path and `ptah-compat migrate apply` the Atlas spelling. Both run under a session advisory lock where the dialect has one, record revisions, honor `--dry-run`, `--tx-mode`, `--baseline` and `--allow-dirty`, and refuse pending migrations carrying destructive statements until reviewed.

`ptah-compat migrate apply` executes Atlas-format migration directories with Atlas revision-table metadata by default, reads `env.url`, `migration`, and `format.migrate.apply` from `atlas.hcl`, and supports positional `amount`, `--baseline`, `--allow-dirty`, `--tx-mode`, `--exec-order`, `--revisions-schema`, `--lock-timeout`, `--lock-name`, `--skip-lock`, `--to-version`, `--dry-run`, and Go-template `--format` output over a Ptah apply result that mirrors Atlas's public apply-template fields.

External Atlas OSS directory formats (`golang-migrate`, `goose`, `flyway`, `liquibase`, `dbmate`) are read and converted in memory to Atlas single-file, up-only migrations and applied directly, sharing format parsers and up/down semantics with `ptah-compat migrate import`; native Atlas directories preserve `R`/`<number>R` repeatable migration tokens and execute them once, while converted Flyway repeatables are represented as one-time versioned migrations. Conventional Liquibase import additionally splits changesets into numeric Atlas files, while direct apply retains its numbered-file requirement and source-file boundary. Unknown formats still fail before the target database is opened.

Directory URL `?format=` overrides `migration.format` whether the URL comes from project config or CLI.

Three of those flags come from the wider Atlas distribution's documented flag surface rather than from the pinned community binary's. That binary answers `unknown flag: --to-version`, `unknown flag: --lock-name`, and `unknown flag: --skip-lock`, word for word the answer it gives a misspelled flag, so it does not register them at all. Ptah implements all three anyway, as adopted compatibility spellings decided in [`stokaro/ptah#951`](https://github.com/stokaro/ptah/issues/951). That is a statement about three flags, not a parity claim about any non-community Atlas distribution.

Behavior below was executed against a `ptah-compat` build from this repository, on PostgreSQL 17.10 unless a line says otherwise:

- `--to-version` bounds the run inclusively. Pointed at the second of three pending migrations, it applies the first two, leaves the third unapplied, and stamps two revision rows. A version the directory does not carry is refused with `target version ... was not found in the migration provider` before any migration executes, and the bound cannot be combined with the positional `amount`.
- `--lock-name` renames the session advisory lock, `ptah_migrate` by default. With `ptah_migrate` held by another session, a default run fails with `timed out acquiring migration lock "ptah_migrate"` and applies nothing, while the same run under `--lock-name deploy_lock_1354` proceeds: two runs serialize only when they name the same lock. An empty value is refused rather than falling back to the default.
- `--skip-lock` acquires no lock. With `ptah_migrate` still held elsewhere, a run with nothing pending still times out under the default lock, and exits `0` under `--skip-lock` in the same state. It cannot be combined with `--lock-name`, and on SQLite an explicit `--lock-name` prints a stderr note naming the lock that was not acquired.

**Conformance status.** Measured for selected migration-directory and live SQLite amount, baseline, `LINEAR_SKIP` state semantics, dry-run baseline, JSON format, custom template, config-driven format, per-format up-only external-format execution (goose, dbmate, liquibase, golang-migrate, flyway), CLI and project URL-format precedence, unknown-format pre-connect rejection, no-op format, invalid-template preflight, redacted URL, failed-apply format cases, and the CLI-surface tier, which projects out the three adopted flags through its closed per-command allowlist and rejects any other flag the pinned binary does not register.

### Migration down and rollback

**Atlas availability.** Open

**Ptah documentation.** [Roll back migrations](../../versioned/rollback/), [Atlas migrate commands](../migrate-commands/), [Feature matrix](../feature-matrix/)

**Implementation status.** Documented. Ptah rolls back through pre-planned down files. `ptah-compat migrate down --dev-url` replays and verifies the rollback plan on the dev database before touching the target (native `ptah migrations down --shadow-db`), and `--format` renders an Atlas Go-template report. `--skip-checks` waives the pre-migration checks on that verification replay as well as on the target, so the flag composes with a dev database.

`--to-tag` resolves against the tags `ptah migrations tag` records in the
database rather than against a hosted registry, `--skip-checks` bypasses the
pre-migration checks the down bodies carry, and `--plan` derives the rollback
from the schema difference instead of running the down bodies. Atlas's
registry-approved down planning stays out of scope.

**Conformance status.** Partially measured.

### Migration diff generation

**Atlas availability.** Open

**Ptah documentation.** [Generate migrations](../../versioned/generate/), [Atlas migrate commands](../migrate-commands/), [Feature matrix](../feature-matrix/)

**Implementation status.** Partial. Native Ptah generates migrations from schema differences, and `ptah-compat migrate diff` reads a `docker://` dev database and the `atlas.hcl` `diff.concurrent_index` policy. The `diff.skip` policy is read for two of its fifteen CE names; [`stokaro/ptah#3111`](https://github.com/stokaro/ptah/issues/3111) owns it.

`ptah-compat migrate diff` now validates an existing `atlas.sum`, replays a
local Atlas migration directory on a directly connectable dev database, and
writes Atlas-style migration files. It:

- compares it to local schema files, one directly connectable database URL, one local Atlas migration directory, or one `env://` reference
- updates `atlas.sum` only after every file was written
- reads `env.schema.src`, `env.dev`, `migration.dir`, `format.migrate.diff`, and supported `diff` policy from `atlas.hcl` including `diff.concurrent_index.create` with `-- atlas:txmode none` file tagging and transactional/concurrent file splitting
- supports the Atlas-hidden `--dry-run` flag to print generated SQL without writing a migration file or `atlas.sum`
- supports `--lock-timeout` for Ptah's local migration-directory lock
- supports Atlas-style `--format` templates with `sql` and `.MarshalSQL` for the generated migration SQL
- supports `--schema` scoping for the resolved desired state plus the replayed dev database state
- supports `--edit` to open the generated migration in `$VISUAL`/`$EDITOR` before `atlas.sum` is finalized

`--qualifier` applies Atlas's single-schema custom qualifier to every object in the generated statements on PostgreSQL, CockroachDB, YugabyteDB, MySQL, and MariaDB dev databases, failing explicitly before any file or checksum write for invalid values, unsupported dialects, multi-schema plans, and not-yet-qualifiable statement kinds. Docker dev databases remain incomplete.

**Conformance status.** Partially measured with local SQLite dev DB, local schema-file, schema-filter, custom-format, config-driven format/env defaults, dry-run, invalid-format, lock-timeout, qualifier, and txmode-split coverage, CLI-surface flag probes, and a real-PostgreSQL end-to-end test for database desired-state scoping, concurrent-index metadata, and qualifier artifacts, plus real MySQL and MariaDB source-preservation and convergence tests.

### Migration linting

**Atlas availability.** Mixed in current Atlas docs: feature page lists migration linting CLI as Pro while also listing a basic Open lint-rule set

**Ptah documentation.** [CI](../../testing/ci/), [Integrity and safety](../../versioned/integrity-and-safety/), [Feature matrix](../feature-matrix/)

**Implementation status.** Partial. Both lint verbs run the whole rule registry, gated by dialect, and `ptah-compat migrate lint` reports in Atlas's format under the `atlas.hcl` `lint` policy. The `lint.naming` policy block drives the diagnostics and the exit code, and the run reports it as honored. What still keeps this section short of complete is the gap list below, which has not been re-measured since the capabilities in it moved.

Ptah ships native linting, SARIF, inline suppression, severity config, and `ptah-compat migrate lint`; `--dir-format` defaults to `atlas`, `--latest`, `--git-base`, `--git-dir`, and matching `atlas.hcl` defaults select the linted changeset, including Atlas repeatable keys `R` and `<number>R`; `--dev-url` infers lint dialect and treats directly connectable dev databases as scratch databases by cleaning and replaying migrations; `--format`, `format.migrate.lint`, and Atlas `lint { log = "…" }` render Atlas-style Go templates over `.Env`, `.Steps`, and `.Files`, and the no-template default reproduces measured Atlas wording, analyzer links, wrapping, and suggested-fix layout for mapped diagnostics while visibly labeling Ptah-only findings without fabricated Atlas links; native `ptah migrations lint` retains Ptah's fuller diagnostic prose; supported `atlas.hcl` analyzer policy maps severity for matching Ptah lint rule families.

Atlas check-level policy, custom rules, force/allow-list analyzer options, Docker dev databases, web reports, and external migration-tool `--dir-format` execution remain gaps.

**Conformance status.** Partially measured with static lint, explicit Atlas dir-format latest selection, Git changeset selection, config-driven latest selection, policy-driven severity, compatibility-wrapper env policy, live SQLite dev-database replay, and Atlas Go-template output coverage.

### Migration directory integrity, hash, and validation

**Atlas availability.** Open versioned workflow concept

**Ptah documentation.** [Integrity and safety](../../versioned/integrity-and-safety/), [Atlas migrate commands](../migrate-commands/), [Exit codes](../../reference/exit-codes/)

**Implementation status.** Partial. Ptah supports `ptah.sum`, Atlas-compatible `atlas.sum`, hash, validate and `migrate validate --dev-url` SQL replay. `ptah-compat migrate hash` and `validate` register Atlas `--dir-format` with default `atlas`; external migration-tool formats are read directly, and `migrate new` plus `migrate diff` write them. A Flyway migration that has to run outside a transaction publishes its `<migration>.sql.conf` sidecar beside the migration; the integrity snapshot counts that sidecar on both sides of its own comparison, so such a directory does not read as changed. `atlas.sum` covers the migration files, as it does for a Flyway directory Flyway itself wrote.

**Conformance status.** Measured for selected directory fixtures, Atlas-default hash output, and live SQLite dev-database replay.

### Migration import

**Atlas availability.** Open for local migration-directory formats

**Ptah documentation.** [Atlas migrate commands](../migrate-commands/), [Feature matrix](../feature-matrix/)

**Implementation status.** Partial. Ptah imports local `file://` directories into an Atlas single-file directory and writes `atlas.sum`; Flyway repeatable migrations become one-time versioned files rather than Atlas `R`-suffixed ones. An Atlas single-file migration holds no rollback, so a source layout's undo file or down section cannot come across; the import names each source file it left one in, on stderr, rather than dropping them without a word. Carrying the rollback across would mean writing a txtar file with a `down.sql` section, which is not what the community binary's import produces, so the repeatable-migration mapping above is what keeps this section short of complete.

**Conformance status.** Partially measured.

### Manual migrations and troubleshooting

**Atlas availability.** Open docs

**Ptah documentation.** [Generate migrations](../../versioned/generate/), [Troubleshooting](../../operate/troubleshooting/), [Exit codes](../../reference/exit-codes/)

**Implementation status.** Documented for Ptah-native behavior. Atlas-specific troubleshooting strings and repair flows are not fully mirrored.

**Conformance status.** Partially measured.

### Drift detection

**Atlas availability.** Feature page lists drift detection as Pro

**Ptah documentation.** [CI](../../testing/ci/), [Feature matrix](../feature-matrix/)

**Implementation status.** Ptah has native `ptah schema drift`; Atlas Cloud/Pro drift monitoring is out of scope.

**Conformance status.** Ptah-native behavior is tested in repo; Atlas Cloud parity is not a target.

### Checkpoints

**Atlas availability.** Feature page lists checkpoints as Pro

**Ptah documentation.** [Feature matrix](../feature-matrix/), [Conformance](../conformance/)

**Implementation status.** Implemented natively and free. `ptah migrations checkpoint` squashes a directory's history into a cumulative-schema checkpoint that fresh databases bootstrap from, and `ptah-compat migrate checkpoint` forwards to it on the Atlas-compatible surface — a workflow Atlas keeps in its Pro build.

Checkpoint output covers both conventions. `--dir-format=atlas` — the default on the compat surface — writes Atlas's single up-only `<version>_<name>.sql` carrying the `-- atlas:checkpoint` directive on its first line and refreshes `atlas.sum`; `--dir-format=ptah` writes the reversible `.checkpoint.up.sql` / `.checkpoint.down.sql` pair and refreshes `ptah.sum`. `--dir-format=auto` is refused, because writing under it would have to guess the convention and the integrity file. The read side honors Atlas's `-- atlas:checkpoint` directive whoever wrote it: checkpoint directories bootstrap fresh databases from the latest checkpoint and are silently skipped on databases that already applied pre-checkpoint history, matching measured Atlas behavior.

**Conformance status.** Measured by native command tests and Atlas-compatibility tests that verify `ptah-compat migrate checkpoint` forwards to the native implementation.

### Pre-migration checks and policy workflows

**Atlas availability.** Feature page lists pre-migration checks as Pro

**Ptah documentation.** [CI](../../testing/ci/), [Feature matrix](../feature-matrix/)

**Implementation status.** Partial. The local assertion half is implemented in both spellings: the native `-- +ptah check` directive and Atlas txtar `checks.sql` / `checks/*.sql` sections, including file-level `atlas:assert oneof`. They are enforced as pre-migration gates rather than executed as plain SQL. The apply report's `.Checks` field carries them: each applied file lists the assertions its migration declares, and a refusal marks the assertion that made it. The Atlas Cloud approval-policy half stays out of scope, which is what keeps this section short of complete.

**Conformance status.** Measured against Atlas: a failing txtar assertion aborts the apply before any body statement on both binaries, and no revision row is recorded. Ptah also covers Atlas's documented named check files and one-of grouping.

### Testing framework

**Atlas availability.** Feature page lists testing framework as Pro

**Ptah documentation.** [Feature matrix](../feature-matrix/), [Conformance](../conformance/)

**Implementation status.** Implemented natively and free. `ptah migrations test` and `ptah schema test` run declarative test cases against a throwaway database, a workflow Atlas keeps in its Pro build. Input variables are not supplied from outside the test files; [`stokaro/ptah#3119`](https://github.com/stokaro/ptah/issues/3119) owns that.

The Atlas-compatible `ptah-compat migrate test` and `ptah-compat schema test` verbs forward to the native runners with Atlas-shaped flags (`--dir`/`-u --url`, `--dev-url`, `--run`, project flags) and the native exit-code contract; either a Ptah-native YAML/Go file or an Atlas `.test.hcl` file is the executable payload; and the language surface is implemented — iteration, the restricted evaluation context, expected failures, boolean assertions, logging, cleanup, authorized external steps and parallel isolation.

**Conformance status.** Measured by native command tests and Atlas-compatibility tests that exercise these forwards.

### Declarative reference data

**Atlas availability.** Feature page lists declarative data management as Pro

**Ptah documentation.** [Feature matrix](../feature-matrix/), [Reference data](../../versioned/reference-data/)

**Implementation status.** Implemented natively and free. `ptah migrations data` diffs declarative reference rows against a live table and writes a reversible data migration (`INSERT`/`UPDATE`/`DELETE`) with an exact inverse `down` — a workflow Atlas keeps in its Pro build and Atlas CE cannot inspect declaratively.

**Conformance status.** Measured by native command and round-trip reversibility tests.

### Supported databases

**Atlas availability.** Open for PostgreSQL, MySQL, MariaDB, SQLite, TiDB, LibSQL in current Atlas feature matrix; many other drivers are Pro

**Ptah documentation.** [Capabilities](../../reference/capabilities/), [Feature matrix](../feature-matrix/)

**Implementation status.** Documented. The engines Ptah renders, plans and reads are declared in `core/platform`, and [Capabilities](../../reference/capabilities/) records what each dialect renders. The release lines this repository tests are the generated support matrix. Neither count is repeated here.

**Conformance status.** Partially measured by local, live, and conformance tests.

### Database object kinds

**Atlas availability.** Core object kinds open for common drivers; advanced PostgreSQL objects such as partitions, views, functions, sequences, extensions, and RLS are listed as Pro examples in Atlas docs

**Ptah documentation.** [Capabilities](../../reference/capabilities/), [HCL schema](../../schema/hcl/), site [HCL schema reference](../../reference/hcl-schema/)

**Implementation status.** Partial and not product-identical. Ptah models objects Atlas gates behind Pro. The kinds are no longer carried in their minimal form: a sequence names its owning column by reference, a row-security declaration binds the table's owner, a policy is permissive or restrictive, a routine carries its configuration settings, its `LEAKPROOF` and `PARALLEL` properties and a set- or table-returning result, and a view names its output columns. What keeps this Partial is that the remaining gap has not been measured attribute by attribute rather than any named attribute being absent.

**Conformance status.** Partially measured.

### Atlas Registry

**Atlas availability.** Cloud

**Ptah documentation.** [OCI registry artifacts](../../operate/oci-registry/), [License boundary](../license-boundary/), [Feature matrix](../feature-matrix/)

**Implementation status.** Atlas Registry remains out of scope: Ptah has no Atlas Cloud dependency, account model, `atlas://` resolver, hosted UI, or Atlas deployment API. Ptah independently provides native `ptah migrations push/pull`, `ptah schema push/pull`, and `ptah oci referrers` commands for bring-your-own OCI registries, plus direct native consumers and best-effort deployment-report referrers.

The referrers command lists descriptor metadata but does not pull report payloads. The Atlas-compatible `migrate push` and `schema push` paths remain registered but not implemented and use Ptah-owned diagnostics.

**Conformance status.** Atlas-compatible push stubs remain measured by CLI-surface conformance. Native OCI behavior is tested in Ptah and is not evidence of Atlas Cloud parity.

### Atlas Cloud deployment reporting

**Atlas availability.** Cloud

**Ptah documentation.** [License boundary](../license-boundary/), [Feature matrix](../feature-matrix/)

**Implementation status.** Out of scope. Ptah can be used in CI, but it does not report deployments to Atlas Cloud.

**Conformance status.** Not measured.

### Cloud-only workflows and account commands

**Atlas availability.** Cloud/Pro

**Ptah documentation.** [License boundary](../license-boundary/), [Feature matrix](../feature-matrix/)

**Implementation status.** Out of scope. Login, the Atlas Registry, the Cloud UI, monitoring, and the Cloud APIs are account-bound services rather than Atlas OSS drop-in targets.

Out of scope is the hosted service, not the capability: Ptah publishes and promotes through any [OCI registry](../../operate/oci-registry/).

**Conformance status.** Not measured.

### CI integrations

**Atlas availability.** Mixed: local CLI usage is open; Atlas Cloud deployment and lint reporting can require Pro/Cloud

**Ptah documentation.** [CI](../../testing/ci/), [Conformance](../conformance/)

**Implementation status.** Documented for Ptah-native CI and conformance interpretation. Atlas's official integrations are not cloned one by one.

**Conformance status.** Ptah CI is measured by repository workflows; Atlas integration parity is unmeasured.

### Conformance evidence

**Atlas availability.** Atlas docs do not define Ptah conformance; this is Ptah-owned evidence

**Ptah documentation.** [Conformance](../conformance/), [Feature matrix](../feature-matrix/)

**Implementation status.** Documented. Regression budget and full-conformance gates are intentionally separate.

**Conformance status.** Measured in `ptah-atlas-conformance`, with current limits documented there.

### License and implementation boundary

**Atlas availability.** Atlas source is a separate third-party project; Ptah compatibility must stay license-clean

**Ptah documentation.** [License boundary](../license-boundary/), [Feature matrix](../feature-matrix/)

**Implementation status.** Documented. Ptah does not import, vendor, port, or derive implementation code from Atlas. Public interfaces and separately held test assets are compatibility inputs.

**Conformance status.** Not a runtime conformance area.

## Follow-up issue coverage

The docs pass recorded here opened four trackers, and each has closed:
[`stokaro/ptah#510`](https://github.com/stokaro/ptah/issues/510) for Atlas
command runtime and flag semantics,
[`stokaro/ptah#511`](https://github.com/stokaro/ptah/issues/511) for HCL schema
and project config parity,
[`stokaro/ptah#498`](https://github.com/stokaro/ptah/issues/498) for the
documentation revision, and
[`stokaro/ptah-atlas-conformance#167`](https://github.com/stokaro/ptah-atlas-conformance/issues/167)
for conformance breadth. The remainders those trackers carried are now owned
per section, by the issues each `Partial` field links.

When a future Atlas docs audit finds a concrete unsupported OSS behavior, file
a focused implementation or conformance issue before claiming the area as
covered.

## How to use this matrix

Use this page before changing Atlas-compatible behavior or documentation:

1. Find the Atlas docs area and official source link.
2. Check whether Ptah behavior is documented, partial, a gap, or out of scope.
3. If the row is partial or a gap, update the linked issue or create a focused
   follow-up issue before claiming support.
4. Update conformance only when the behavior can be measured by command,
   fixture, live database, or Atlas CE differential probes.

Do not turn a green docs build into a product parity claim. Product parity needs
current implementation evidence, conformance evidence, and a closed gap row.