ariga/atlas

"owner": {     "name": "Ariga",     "url": "https://atlasgo.io"

"name": "Ariga",     "url": "https://atlasgo.io"   },

"url": "https://atlasgo.io"

"author": {         "name": "Ariga",         "url": "https://atlasgo.io"

"name": "Ariga",         "url": "https://atlasgo.io"       },

"url": "https://atlasgo.io"

},       "homepage": "https://atlasgo.io/guides/ai-tools/agent-skills"     }

"homepage": "https://atlasgo.io/guides/ai-tools/agent-skills"

This skill is `SKILL.md` plus fourteen reference files under `references/`, each served at `https://atlasgo.io/skills/atlas-action/references/<name>`. Read a reference when the task needs it:

This skill is `SKILL.md` plus fourteen reference files under `references/`, each served at `https://atlasgo.io/skills/atlas-action/references/<name>`. Read a reference when the task needs it:

`https://atlasgo.io/skills/atlas-action/references/<name>`. Read a reference when the task needs it:

`https://atlasgo.io/skills/atlas-action/references/<name>`. Read a reference when the task needs it:

The `atlas` skill, installed next to this one (`../atlas/SKILL.md`). If it is missing, download https://atlasgo.io/skills/atlas/SKILL.md to `../atlas/SKILL.md` and each reference file listed in its

The `atlas` skill, installed next to this one (`../atlas/SKILL.md`). If it is missing, download https://atlasgo.io/skills/atlas/SKILL.md to `../atlas/SKILL.md` and each reference file listed in its

https://atlasgo.io/skills/atlas/SKILL.md to `../atlas/SKILL.md` and each reference file listed in its

https://atlasgo.io/skills/atlas/SKILL.md to `../atlas/SKILL.md` and each reference file listed in its

`references/troubleshooting.md`. Reproduce against dev databases only. 13. Commit migration files with LF line endings (`* text=auto eol=lf` in `.gitattributes`): a CRLF     checkout breaks `atlas.sum` (https://atlasgo.io/faq/checksum-misma

`references/troubleshooting.md`. Reproduce against dev databases only. 13. Commit migration files with LF line endings (`* text=auto eol=lf` in `.gitattributes`): a CRLF     checkout breaks `atlas.sum` (https://atlasgo.io/faq/checksum-misma

checkout breaks `atlas.sum` (https://atlasgo.io/faq/checksum-mismatch).

checkout breaks `atlas.sum` (https://atlasgo.io/faq/checksum-mismatch).

| `command requires 'atlas login'` | `cloud-token` is missing or empty in this job: fork pull requests and protected variables get no secrets | | Which secrets go in which job? | One bot token, a repository secret, in every job. Database UR

| `command requires 'atlas login'` | `cloud-token` is missing or empty in this job: fork pull requests and protected variables get no secrets | | Which secrets go in which job? | One bot token, a repository secret, in every job. Database UR

| Which secrets go in which job? | One bot token, a repository secret, in every job. Database URLs only in deploy and scheduled jobs, from environments only the default branch can use; a read-only user's for drift, scan, and monitoring (`re

| Which secrets go in which job? | One bot token, a repository secret, in every job. Database URLs only in deploy and scheduled jobs, from environments only the default branch can use; a read-only user's for drift, scan, and monitoring (`re

| A merge job cannot push or approve after protected flows were turned on | Give the bot the Writer role on the repo (https://atlasgo.io/cloud/roles-and-permissions) |

| A merge job cannot push or approve after protected flows were turned on | Give the bot the Writer role on the repo (https://atlasgo.io/cloud/roles-and-permissions) |

| `missing scheme for dir url` or `"<path>" is not a dir` from `migrate/apply` | `dir` takes a migration directory URL with its scheme (`file://migrations`, `atlas://app`); a schema file deploys with `schema/apply` | | `connected database i

| `missing scheme for dir url` or `"<path>" is not a dir` from `migrate/apply` | `dir` takes a migration directory URL with its scheme (`file://migrations`, `atlas://app`); a schema file deploys with `schema/apply` | | `connected database i

| `connected database is not clean` on the first deploy | `baseline = "<version>"` in the deploy env's migration block | | A renamed table or column shows as a drop and a create in the plan or lint comment | CI cannot answer the rename prom

| `connected database is not clean` on the first deploy | `baseline = "<version>"` in the deploy env's migration block | | A renamed table or column shows as a drop and a create in the plan or lint comment | CI cannot answer the rename prom

| A renamed table or column shows as a drop and a create in the plan or lint comment | CI cannot answer the rename prompt: declare the rename with `renamed_from` (HCL) or `-- atlas:renamed_from` (SQL), not with `nolint` (https://atlasgo.io/

| A renamed table or column shows as a drop and a create in the plan or lint comment | CI cannot answer the rename prompt: declare the rename with `renamed_from` (HCL) or `-- atlas:renamed_from` (SQL), not with `nolint` (https://atlasgo.io/

- GitHub Actions: https://atlasgo.io/integrations/github-actions

- GitHub Actions: https://atlasgo.io/integrations/github-actions

- GitLab CI components: https://atlasgo.io/integrations/gitlab-ci-components

- GitLab CI components: https://atlasgo.io/integrations/gitlab-ci-components

- CircleCI orb: https://atlasgo.io/integrations/circleci-orbs

- CircleCI orb: https://atlasgo.io/integrations/circleci-orbs

- Bitbucket pipes: https://atlasgo.io/integrations/bitbucket-pipes

- Bitbucket pipes: https://atlasgo.io/integrations/bitbucket-pipes

- Azure DevOps: https://atlasgo.io/integrations/azure-devops

- Azure DevOps: https://atlasgo.io/integrations/azure-devops

- Versioned CI/CD: https://atlasgo.io/versioned/setup-cicd

- Versioned CI/CD: https://atlasgo.io/versioned/setup-cicd

- Declarative CI/CD: https://atlasgo.io/declarative/setup-cicd

- Declarative CI/CD: https://atlasgo.io/declarative/setup-cicd

- Pre-approval and ad-hoc approval: https://atlasgo.io/integrations/github-actions/pre-approval,

- Pre-approval and ad-hoc approval: https://atlasgo.io/integrations/github-actions/pre-approval,

https://atlasgo.io/integrations/github-actions/ad-hoc-approval

https://atlasgo.io/integrations/github-actions/ad-hoc-approval

- Modern database CI/CD: https://atlasgo.io/guides/modern-database-ci-cd

- Modern database CI/CD: https://atlasgo.io/guides/modern-database-ci-cd

- Bot tokens: https://atlasgo.io/cloud/bots

- Bot tokens: https://atlasgo.io/cloud/bots

|-------|----------|---------|-------------| | `exclude` |  |  | List of glob patterns used to select which resources to filter in inspection. | | `from` |  |  | URL(s) of the current schema state. If not provided, Atlas uses the [`url`](ht

| `exclude` |  |  | List of glob patterns used to select which resources to filter in inspection. | | `from` |  |  | URL(s) of the current schema state. If not provided, Atlas uses the [`url`](https://atlasgo.io/hcl/config#env.url) from the

| `from` |  |  | URL(s) of the current schema state. If not provided, Atlas uses the [`url`](https://atlasgo.io/hcl/config#env.url) from the config file. If that is also not set, Atlas defaults to the last known state in the Atlas Registry 

|-------|----------|---------|-------------| | `exclude` |  |  | List of glob patterns used to select which resources to filter in inspection. | | `from` |  |  | URL(s) of the current schema state. If not provided, Atlas uses the [`url`](ht

| `exclude` |  |  | List of glob patterns used to select which resources to filter in inspection. | | `from` |  |  | URL(s) of the current schema state. If not provided, Atlas uses the [`url`](https://atlasgo.io/hcl/config#env.url) from the

| `from` |  |  | URL(s) of the current schema state. If not provided, Atlas uses the [`url`](https://atlasgo.io/hcl/config#env.url) from the config file. If that is also not set, Atlas defaults to the last known state in the Atlas Registry 

| `ignore` |  |  | CVE identifier(s) not to report. For example: `CVE-2017-18359`. | | `min-severity` |  |  | The lowest severity to report. For example, `HIGH` reports only the `HIGH` and `CRITICAL` issues. Values: `NORMAL`, `ELEVATED`, `H

| `urls` |  |  | URL(s) of the target databases, one per line. For example: `postgres://localhost:5432/app?sslmode=disable`. If not set, Atlas uses the [`url`](https://atlasgo.io/hcl/config#env.url) from the config file. |

(`atlas cloud migration list`, `atlas/references/cloud.md`). A deploy from a `file://` directory is   recorded only when the env's `migration` block sets `report = true` and a `repo { name = "..." }`   (https://atlasgo.io/cloud/deployment).

recorded only when the env's `migration` block sets `report = true` and a `repo { name = "..." }`   (https://atlasgo.io/cloud/deployment). A recorded deploy sends each applied file's contents to Atlas   Cloud: mark statements that carry sec

(https://atlasgo.io/cloud/deployment). A recorded deploy sends each applied file's contents to Atlas

Cloud: mark statements that carry secrets with `-- atlas:sensitive`   (https://atlasgo.io/atlas-schema/sql#sensitive-values). - Preview and test databases: `skip_report = true` in the env's `migration` block keeps their deploys

(https://atlasgo.io/atlas-schema/sql#sensitive-values).

- Preview and test databases: `skip_report = true` in the env's `migration` block keeps their deploys   out of the deployment history (https://atlasgo.io/cloud/deployment#skipping-cloud-reporting). - A directory kept in S3 deploys through a

out of the deployment history (https://atlasgo.io/cloud/deployment#skipping-cloud-reporting).

- A directory kept in S3 deploys through a `blob_dir` data source in the env, which needs the login   (https://atlasgo.io/faq/s3-dirs). - `dry-run: true` prints the pending SQL without running it; pre-execution checks still run.

(https://atlasgo.io/faq/s3-dirs).

- The first deploy to a database that already has objects aborts with   `connected database is not clean`. Set `baseline` to the version of the baseline file   (https://atlasgo.io/versioned/apply#existing-databases). Use `allow-dirty` only 

`connected database is not clean`. Set `baseline` to the version of the baseline file   (https://atlasgo.io/versioned/apply#existing-databases). Use `allow-dirty` only when the user confirms   the existing objects stay outside the directory

(https://atlasgo.io/versioned/apply#existing-databases). Use `allow-dirty` only when the user confirms

one database wait on each other unless each env sets its own `lock_name`. Set `skip_lock = true` only   where something else guarantees a single deploy   (https://atlasgo.io/versioned/apply#controlling-advisory-locks).

where something else guarantees a single deploy   (https://atlasgo.io/versioned/apply#controlling-advisory-locks). - Out-of-order files and `exec-order`: `references/rebase.md`.

(https://atlasgo.io/versioned/apply#controlling-advisory-locks).

(`environment: production`). The lower environment's deploys must be recorded, from `atlas://` or with `report = true`, or `cloud_databases` has no version to read. Guide: https://atlasgo.io/guides/environment-promotion.

https://atlasgo.io/guides/environment-promotion.

Prefer rolling forward with a new migration. Before a revert drops anything, Atlas runs pre-migration checks that stop it if the objects to drop hold data (https://atlasgo.io/versioned/down). On engines

checks that stop it if the objects to drop hold data (https://atlasgo.io/versioned/down). On engines

as applied, and the rows of later versions are removed. Use it after a change was applied by hand, to move the recorded version back when later files never ran (https://atlasgo.io/faq/revisions-table-delete-latest), and in the out-of-order 

move the recorded version back when later files never ran (https://atlasgo.io/faq/revisions-table-delete-latest), and in the out-of-order flow (`references/rebase.md`). On a shared database it rewrites deployment history: only with the user

(https://atlasgo.io/faq/revisions-table-delete-latest), and in the out-of-order flow

- Give `schema/apply` the dev database too (the env's `dev`, or `dev-url`). Without one, the plan can   hold incorrect or unnecessary changes, and every run proposes them again   (https://atlasgo.io/concepts/dev-database#diffing).

hold incorrect or unnecessary changes, and every run proposes them again   (https://atlasgo.io/concepts/dev-database#diffing). - Each poll re-inspects the target: keep `wait-interval` at `30s` or more for long waits.

(https://atlasgo.io/concepts/dev-database#diffing).

`error`. - Engines without transactional DDL: `tx-mode: none`. - Guides: https://atlasgo.io/declarative/plan,

- Engines without transactional DDL: `tx-mode: none`. - Guides: https://atlasgo.io/declarative/plan,   https://atlasgo.io/integrations/github-actions/pre-approval,

- Guides: https://atlasgo.io/declarative/plan,

https://atlasgo.io/integrations/github-actions/pre-approval,

https://atlasgo.io/integrations/github-actions/ad-hoc-approval.

production env, a `check "schema_apply"` block with a `deny` rule refuses a version staging has not run, with the staging version read by a `cloud_databases` data source (https://atlasgo.io/guides/environment-promotion-declarative).

(https://atlasgo.io/guides/environment-promotion-declarative).

The check is the one in https://atlasgo.io/faq/desired-state-drift. `migrate/lint` already fails a

Inspects a database and pushes a snapshot to Atlas Cloud Schema Monitoring (https://atlasgo.io/monitoring), which records each change to the schema over time.

(https://atlasgo.io/monitoring), which records each change to the schema over time.

- Comparing with the registry also catches non-linear changes: a branch that edits, deletes, or reorders   a file the registry already has. They are warnings by default; the policy can make them errors   (https://atlasgo.io/lint/analyzers#n

a file the registry already has. They are warnings by default; the policy can make them errors   (https://atlasgo.io/lint/analyzers#non-linear-changes). `atlas.sum` alone does not catch them. - The action always passes `--base atlas://<dir-

(https://atlasgo.io/lint/analyzers#non-linear-changes). `atlas.sum` alone does not catch them.

The step then needs `GITHUB_TOKEN` in its `env`, which resolves team membership (the built-in `github.token` works for public and internal repositories), `fetch-depth: 0` on the checkout, and `env` naming the env with the policy (https://at

`env` naming the env with the policy (https://atlasgo.io/guides/schema-ownership).

[Credential-related source omitted]

[Credential-related source omitted]

[Credential-related source omitted]

[Credential-related source omitted]

[Credential-related source omitted]

[Credential-related source omitted]

- script: curl -sSf https://atlasgo.sh | sh

- script: curl -sSf https://atlasgo.sh | sh

On CI systems without an Atlas integration, such as Jenkins, TeamCity, Buildkite, Cloud Build, or Argo Workflows, run the CLI: install it (`curl -sSf https://atlasgo.sh | sh`, or the `arigaio/atlas` image),

Workflows, run the CLI: install it (`curl -sSf https://atlasgo.sh | sh`, or the `arigaio/atlas` image),

Workflows, run the CLI: install it (`curl -sSf https://atlasgo.sh | sh`, or the `arigaio/atlas` image),

[Credential-related source omitted]

- A `backup` list in the env's `repo` block replicates each push to storage such as S3: the push   succeeds when Atlas Cloud or one backup accepts it, and `atlas://` reads fall back to the backups in   order (https://atlasgo.io/guides/backu

order (https://atlasgo.io/guides/backup-continuity-migration-versioned).

Teams that deploy branches to shared environments before merge (git-flow hotfixes, a `develop` branch ahead of `main`) apply files out of order there. `migrate apply` refuses that by default (`migration file ... was added out of order`, htt

ahead of `main`) apply files out of order there. `migrate apply` refuses that by default (`migration file ... was added out of order`, https://atlasgo.io/versioned/apply#non-linear-error). The execution order decides:

(`migration file ... was added out of order`, https://atlasgo.io/versioned/apply#non-linear-error). The

ariga/atlas-action has a detection step for that. The job holds that database's URL, which the branch's code can read: use the flow only for a shared development database. Guide: https://atlasgo.io/faq/out-of-order-migrations.

https://atlasgo.io/faq/out-of-order-migrations.

- With `env`, the step uses the env's `security` block (`min_severity`, `fail_on`, `cve { ignore }`,   and `notify` endpoints), so the thresholds live in `atlas.hcl`   (https://atlasgo.io/guides/security-scan#configuration).

and `notify` endpoints), so the thresholds live in `atlas.hcl`   (https://atlasgo.io/guides/security-scan#configuration). - Each finding carries its fix in `Suggestion`. For an extension built into the engine, such as

(https://atlasgo.io/guides/security-scan#configuration).

finding with its `check` (the CVE) and `level`. To gate on it, run it in a script step piped to   `jq '.nodes[] | select(.reports[]?.level == "critical")'`, and fail the step when that prints   anything: `jq` exits 0 either way (https://atl

`jq '.nodes[] | select(.reports[]?.level == "critical")'`, and fail the step when that prints   anything: `jq` exits 0 either way (https://atlasgo.io/cloud/features/security-graph). - Guide: https://atlasgo.io/guides/security-scan.

anything: `jq` exits 0 either way (https://atlasgo.io/cloud/features/security-graph).

- Guide: https://atlasgo.io/guides/security-scan.

CI authenticates with an Atlas Cloud bot token, not a person's login. An organization admin creates a bot in Atlas Cloud under Settings > Bots (https://atlasgo.io/cloud/bots); its token is shown once. A

bot in Atlas Cloud under Settings > Bots (https://atlasgo.io/cloud/bots); its token is shown once. A

those events hand the repository's secrets to code from forks. - With protected flows on a registry repo, only members and bots with the Writer role can push to it   or approve its plans, so the bot needs that role (https://atlasgo.io/cloud

- With protected flows on a registry repo, only members and bots with the Writer role can push to it   or approve its plans, so the bot needs that role (https://atlasgo.io/cloud/roles-and-permissions).   Protected flows are an Atlas Pro fea

or approve its plans, so the bot needs that role (https://atlasgo.io/cloud/roles-and-permissions).

`aws_dsql_token`, and `azure_db_token` (Microsoft Entra ID) data sources in `atlas.hcl` mint a   short-lived token from the runner's cloud identity, and `runtimevar` reads the password from a secret   manager when the step runs (https://atl

short-lived token from the runner's cloud identity, and `runtimevar` reads the password from a secret   manager when the step runs (https://atlasgo.io/guides/deploying/secrets). Azure SQL takes the   identity through `fedauth` in its `azure

manager when the step runs (https://atlasgo.io/guides/deploying/secrets). Azure SQL takes the

identity through `fedauth` in its `azuresql://` URL   (https://atlasgo.io/concepts/url#supported-schemes). - The other platforms keep database URLs on the default branch the same way: protected variables on

(https://atlasgo.io/concepts/url#supported-schemes).

- Pin the organization in `atlas.hcl`: a step that reads the file then fails unless the job is logged   in to that organization, so a missing or wrong token stops the job instead of losing objects   (https://atlasgo.io/atlas-schema/projects

in to that organization, so a missing or wrong token stops the job instead of losing objects   (https://atlasgo.io/atlas-schema/projects#atlas-block). The pin applies to steps that read the file,   so select an env in every step.

(https://atlasgo.io/atlas-schema/projects#atlas-block). The pin applies to steps that read the file,

The dev URL above is schema-scoped (`search_path=public`), so the migration files hold unqualified names, and the target URL must name the same schema. A directory that spans several schemas uses database-scoped URLs for both (https://atlas

database-scoped URLs for both (https://atlasgo.io/concepts/url#scope).

A password with `@`, `#`, `/`, or another reserved character breaks the URL. Keep the password in its own secret and escape it in `atlas.hcl` with `urlescape` (https://atlasgo.io/faq/url-special-chars):

own secret and escape it in `atlas.hcl` with `urlescape` (https://atlasgo.io/faq/url-special-chars):

- Deploy, drift, scan, monitoring, and script steps connect from the runner to the database. A   GitHub-hosted runner reaches only a database open to its IP ranges; otherwise use a self-hosted runner   in the database's network (https://atl

GitHub-hosted runner reaches only a database open to its IP ranges; otherwise use a self-hosted runner   in the database's network (https://atlasgo.io/guides/deploying/connect-to-db-from-github-actions).   GitHub-hosted runners have no IPv6

in the database's network (https://atlasgo.io/guides/deploying/connect-to-db-from-github-actions).

- On PostgreSQL, `template = true` on the dev database's `docker` block runs each test group on a   fresh copy of the desired schema, which keeps a large suite fast   (https://atlasgo.io/guides/postgres/schema-test-template-databases).

fresh copy of the desired schema, which keeps a large suite fast   (https://atlasgo.io/guides/postgres/schema-test-template-databases). - Plans have their own tests (`atlas schema plan test`), which no action wraps: run the CLI in a step

(https://atlasgo.io/guides/postgres/schema-test-template-databases).

| `looking up atlas-cli: exec: "atlas": executable file not found in $PATH` | No `setup-atlas` before the step | Add `ariga/setup-atlas@v0` to the job | | `no action found for the current environment` | The binary ran outside a supported CI

| `no action found for the current environment` | The binary ran outside a supported CI (no `GITHUB_ACTIONS`, `GITLAB_CI`, `CIRCLECI`, `BITBUCKET_PIPELINE_UUID`, `TF_BUILD`, or `TEAMCITY_VERSION`) | Run it as a CI step; on other CI systems 

| `The specified Atlas version does not exist or is no longer supported.` | `setup-atlas` is pinned to a CLI version that was retired (https://atlasgo.io/cli-reference#distributed-binaries) | Move `version` to a current release, and keep mo

| `version 'GLIBC_2.34' not found` | An old atlas-action release | Upgrade: current binaries are static | | `Node.js 20 actions are deprecated` | An old release pinned | Upgrade to a current v1 release (Node 24) | | `ariga/atlas-action@v0`,

| `Node.js 20 actions are deprecated` | An old release pinned | Upgrade to a current v1 release (Node 24) | | `ariga/atlas-action@v0`, `ariga/atlas-sync-action`, or `ariga/atlas-deploy-action` in the workflow | Actions deprecated in October

| `ariga/atlas-action@v0`, `ariga/atlas-sync-action`, or `ariga/atlas-deploy-action` in the workflow | Actions deprecated in October 2023, without updates (https://atlasgo.io/blog/2023/10/12/atlas-actions-v1) | `migrate/lint@v1` (with `dir-

| `<feature> is no longer supported by this release`, such as `data.external_schema is no longer supported by this release` | The job installed the community build | Install the standard build with `ariga/setup-atlas` or `curl -sSf https://

| `<feature> is no longer supported by this release`, such as `data.external_schema is no longer supported by this release` | The job installed the community build | Install the standard build with `ariga/setup-atlas` or `curl -sSf https://

| A pipeline broke with no change in the repository | `setup-atlas` installs `latest`, and a new CLI release changed behavior | Pin `version: v<last good>` in `setup-atlas`, report the regression, upgrade when fixed | | `migrate diff` fails

| `migrate diff` fails or plans wrong statements after an ORM or Go upgrade, with no Atlas change | The ORM's schema loader does not support the new version | Upgrade the ORM's Atlas provider (such as `atlas-provider-gorm`), or Ent itself f

| A job that runs scripts in the `arigaio/atlas` image cannot start a shell | The default image is distroless: it holds only Atlas | Use `arigaio/atlas:latest-alpine`, which has `/bin/sh` (https://atlasgo.io/guides/atlas-in-docker) |

| `'atlas login' is required for organization <org> as specified in atlas.hcl` | The token belongs to another organization | A bot token from the organization `atlas.hcl` pins | | `required input "cloud-token" is missing` | `monitor/schema`

| `required input "cloud-token" is missing` | `monitor/schema` without its own token | Pass `cloud-token` to that step | | A merge job cannot push or approve after protected flows were turned on | The bot has no role on the repo | Give the 

| A merge job cannot push or approve after protected flows were turned on | The bot has no role on the repo | Give the bot the Writer role on the repo (https://atlasgo.io/cloud/roles-and-permissions) |

[Credential-related source omitted]

[Credential-related source omitted]

| `--git-base` reports no changes, though `--latest 1` lints the new file | Git-based detection sees committed files only | Commit the file, or lint against the registry | | `` `atlas migrate lint` report was not uploaded to Atlas Cloud `` 

| `checksum mismatch` | `atlas.sum` does not match the files: a file edited without rehashing, CRLF line endings from a Windows checkout, or a directory format mismatch | Unapplied file: `atlas migrate hash` and commit. Line endings: `* tex

|---------|-------|-----| | `connected database is not clean: ... baseline version or allow-dirty is required` | First deploy to a database with existing objects | `baseline = "<version>"` in the env's migration block | | `invalid port ":<t

| `connected database is not clean: ... baseline version or allow-dirty is required` | First deploy to a database with existing objects | `baseline = "<version>"` in the env's migration block | | `invalid port ":<text>" after host` or `net/

| `invalid port ":<text>" after host` or `net/url: invalid userinfo` | The password in the URL secret has characters URLs reserve, such as `#`, `?`, `@`, or `/` | Store the password percent-encoded, or in its own secret that `atlas.hcl` esc

| `missing scheme for dir url. Did you mean "file://<path>"?` | `dir` has no scheme | `dir: file://migrations` or `atlas://<repo>` | | `"<path>" is not a dir` | `dir` points at a schema file, not a migration directory | A migration director

| `"<path>" is not a dir` | `dir` points at a schema file, not a migration directory | A migration directory; desired-state files deploy with `schema/apply` | | `migration file ... was added out of order` | A pending file is older than the 

| `migration file ... was added out of order` | A pending file is older than the database's version | Rebase the branch's files (`references/rebase.md`); `exec-order` only with approval (https://atlasgo.io/versioned/apply#non-linear-error) 

| The deploy stopped on the drift check | The target differs from its migration history | Run `migrate/drift` to see the difference (`references/drift.md`) | | `The INSERT permission was denied on the object 'atlas_schema_revisions'` on a d

| `The INSERT permission was denied on the object 'atlas_schema_revisions'` on a dry run | Old CLI versions wrote to the revisions table on a dry run with `--env` and a token | Upgrade the CLI, or grant the role write access to the revision

| `unexpected transaction status idle` | `BEGIN`/`COMMIT` in a file Atlas already wraps | Remove them, or put `-- atlas:txmode none` at the top of the file; lint reports them as nested transactions (https://atlasgo.io/lint/analyzers#nested-

| `migrate/apply` runs `.down.sql` files, or fails on a statement from one | A golang-migrate directory read in the Atlas format | `format = golang-migrate` in the env's `migration` block, or `dir: file://<path>?format=golang-migrate` (http

| `exec: "docker": executable file not found in $PATH` | `docker://` dev URL where Docker is missing (container job, Atlas image, container agent) | A service container and its URL (`references/setup.md`) | | `connect: connection refused` |

| `connect: connection refused` | The service is not healthy yet, or the host is wrong | Add health checks; `localhost` from the runner, the service name from a container job | | `timeout: postgres: querying system variables: dial tcp <addr

| `timeout: postgres: querying system variables: dial tcp <address>:<port>`, or `read tcp [::1]:<port>`, with a `docker://` dev URL | Atlas cannot reach the port Docker published for the dev container: some self-hosted runners, or Atlas in 

| `connected database is not clean` (dev), such as `found schema "atlas_schema_revisions"` | The dev database is not empty, or the dev URL points at a real database | An empty database or schema used only by Atlas (https://atlasgo.io/faq/mi

| `modify schema "public" is not allowed when migration plan is scoped to one schema` | The dev database's schema differs from the target's in charset, collation, or comment, or the dev URL's scope differs from the target's | Give the dev d

| `pq: type "<type>" does not exist` or `pq: function <name>() does not exist`, for an extension's type or function (`geometry`, `geography`, `citext`, `uuid_generate_v4`) | The job is logged out, and extensions are managed only with the lo

| `extension "<name>" has no installation script nor update path for version "<v>"` | The dev image lacks the target's extension version | A dev image with the target's extension versions, or exclude extension versions (https://atlasgo.io/f

| `pq: out of shared memory` | The dev database's lock table is too small for the schema | Raise `max_locks_per_transaction` with the `docker` block's `command` (https://atlasgo.io/faq/out-of-shared-memory) |

| A MySQL or MariaDB plan or drift report keeps showing a generated column changed from `_latin1'...'` to `_utf8mb4'...'` | The dev database's charset or collation differs from the target's | Start the dev database with the target's charset

|----------|--------| | Install only the CLI, for the job's own scripts | `ariga/setup-atlas` puts `atlas` on the `PATH` for the later steps; without `cloud-token` it does not log in | | Install with `go install` | Not supported: use `setup

| Install only the CLI, for the job's own scripts | `ariga/setup-atlas` puts `atlas` on the `PATH` for the later steps; without `cloud-token` it does not log in | | Install with `go install` | Not supported: use `setup-atlas` or the install

| Install with `go install` | Not supported: use `setup-atlas` or the install script (https://atlasgo.io/faq/go-install-deprecation) |

| Secrets from a secret manager | The `runtimevar` data source reads them when the step runs (https://atlasgo.io/guides/deploying/secrets), or a `data "external"` block runs the manager's CLI; an environment variable read with `getenv()` al

| Lint every file, not only the new ones | With the CLI: `atlas migrate lint --env ci --latest <N>`, with `N` the number of files in the directory | | Run `SET ROLE` or another statement before each migration | Migration hooks in the deploy

| Run `SET ROLE` or another statement before each migration | Migration hooks in the deploy env, which need the login (https://atlasgo.io/versioned/apply#migration-hooks) |

This skill is `SKILL.md` plus seven reference files under `references/`, each served at `https://atlasgo.io/skills/atlas-clickhouse/references/<name>`. Read a reference when the task needs it:

`https://atlasgo.io/skills/atlas-clickhouse/references/<name>`. Read a reference when the task needs it:

The `atlas` skill, installed next to this one (`../atlas/SKILL.md`). If it is missing, download https://atlasgo.io/skills/atlas/SKILL.md to `../atlas/SKILL.md` and each reference file listed in its

https://atlasgo.io/skills/atlas/SKILL.md to `../atlas/SKILL.md` and each reference file listed in its

- ClickHouse HCL reference: https://atlasgo.io/hcl/clickhouse

- Getting started: https://atlasgo.io/guides/clickhouse

- Dev database: https://atlasgo.io/concepts/dev-database

- Clusters: https://atlasgo.io/guides/clickhouse/cluster-mode

- ClickHouse Cloud: https://atlasgo.io/guides/clickhouse/clickhouse-cloud-atlas

- Security: https://atlasgo.io/guides/clickhouse/security-declarative,

https://atlasgo.io/guides/clickhouse/security-versioned

- Lint checks: https://atlasgo.io/lint/analyzers

- Guides for each database: https://atlasgo.io/databases

the user states a convention, write a custom rule in Atlas's HCL rule language. A rule can check the attributes Atlas exposes for each ClickHouse object, and `atlas schema lint` and `atlas migrate lint` enforce it on every change (https://a

attributes Atlas exposes for each ClickHouse object, and `atlas schema lint` and `atlas migrate lint` enforce it on every change (https://atlasgo.io/lint/rules). Lint needs `atlas login`, as the ClickHouse driver does. If `atlas whoami` sho

enforce it on every change (https://atlasgo.io/lint/rules). Lint needs `atlas login`, as the ClickHouse

Rules live in `.rule.hcl` files. The language reference is https://atlasgo.io/hcl/rule.

The attributes ClickHouse objects expose to predicates, and the child objects a predicate or rule can walk into (https://atlasgo.io/hcl/rule):

walk into (https://atlasgo.io/hcl/rule):

From the rule tests and docs (https://atlasgo.io/lint/rules). Adapt the closest one before writing a

Add the rule files to `atlas.hcl`, globally or inside an env (https://atlasgo.io/lint/rules):

The dev database is a temporary database Atlas uses to load the desired state, replay migrations, and compute plans (https://atlasgo.io/concepts/dev-database). For ClickHouse it must match the target's

compute plans (https://atlasgo.io/concepts/dev-database). For ClickHouse it must match the target's

The URL's path names a database, and decides what Atlas covers (https://atlasgo.io/concepts/url):

The `docker://` driver starts a fresh `clickhouse/clickhouse-server:<tag>` container for each run. The URL path holds the image tag, then an optional database that Atlas creates in the container (https://atlasgo.io/concepts/dev-database):

(https://atlasgo.io/concepts/dev-database):

`atlas tool docker` creates a named container from a `docker://` URL and prints its connection URL. It also cleans the database if it is not empty, so never run it against a container that holds data to keep (https://atlasgo.io/cli-referenc

keep (https://atlasgo.io/cli-reference). The container runs until `atlas tool docker kill --name my-db`:

A `docker "clickhouse"` block configures the dev container: `image` (required), `schema`, `baseline`, `init`, `volumes`, `env`, `command`, `args`, `platform`, `build`, and more (https://atlasgo.io/hcl/config#docker.clickhouse). The `docker`

(https://atlasgo.io/hcl/config#docker.clickhouse). The `docker` and `dev` blocks need `atlas login`.

A `dev "clickhouse"` block, or a plain `clickhouse://` dev URL, connects to an existing database instead of a container (https://atlasgo.io/hcl/config). The database must be empty and dedicated to Atlas.

of a container (https://atlasgo.io/hcl/config). The database must be empty and dedicated to Atlas.

When the target defines a `cluster` macro, the dev database must be on a cluster too, or commands fail with `dev database must also be in a cluster configuration`. `docker://` starts a single node, so it cannot serve a clustered target (htt

cannot serve a clustered target (https://atlasgo.io/guides/clickhouse/cluster-mode):

`has_user_defined_zookeeper_path`. Pin the dev image to the Cloud service's version yourself. - The dev database can be a separate Cloud service, which matches the target fully, or a Docker   container on OSS engines (https://atlasgo.io/gui

- The dev database can be a separate Cloud service, which matches the target fully, or a Docker   container on OSS engines (https://atlasgo.io/guides/clickhouse/clickhouse-cloud-atlas). - Inspection skips Cloud's own users and roles: users 

container on OSS engines (https://atlasgo.io/guides/clickhouse/clickhouse-cloud-atlas).

Atlas connects over the native protocol: port `9000`, or `9440` with TLS (`secure=true`), the port ClickHouse Cloud uses (https://atlasgo.io/guides/clickhouse/clickhouse-cloud-atlas). Two query

ClickHouse Cloud uses (https://atlasgo.io/guides/clickhouse/clickhouse-cloud-atlas). Two query

parameters belong to Atlas and are removed before connecting; every other parameter is passed to the server, and ClickHouse settings passed this way apply to every query of the session (https://atlasgo.io/guides/clickhouse/session-settings)

(https://atlasgo.io/guides/clickhouse/session-settings):

The rules of the HCL schema language that matter on ClickHouse, and the places where HCL behaves differently from SQL. The language: https://atlasgo.io/atlas-schema/hcl. Every ClickHouse block and

differently from SQL. The language: https://atlasgo.io/atlas-schema/hcl. Every ClickHouse block and

attribute: https://atlasgo.io/hcl/clickhouse. Expressions for engines, types, defaults, and TTLs:

https://atlasgo.io/guides/clickhouse/advanced-hcl-schema.

- Name ClickHouse schema files `*.ch.hcl` and test files `*.test.hcl`, so editors apply the right   schema (https://atlasgo.io/atlas-schema/hcl).

schema (https://atlasgo.io/atlas-schema/hcl).

- A WASM function sets `lang = WASM`, `module`, `returns`, `source`, and `arg` blocks instead of `as`,   and takes `abi`, `deterministic`, `hash`, and `settings`. A `wasm_module` block takes `code` and an   optional `hash`, both as `sql()` 

and takes `abi`, `deterministic`, `hash`, and `settings`. A `wasm_module` block takes `code` and an   optional `hash`, both as `sql()` expressions (https://atlasgo.io/guides/clickhouse/wasm). - A `named_collection` holds `item` blocks with 

optional `hash`, both as `sql()` expressions (https://atlasgo.io/guides/clickhouse/wasm).

Rows are declared next to the table in a `data` block, and applied only when the env enables data sync (https://atlasgo.io/guides/clickhouse/seed-data):

(https://atlasgo.io/guides/clickhouse/seed-data):

Input variables work as in any Atlas HCL schema (https://atlasgo.io/atlas-schema/input-variables), and

The ClickHouse checks report changes whose cost grows with the size of the table, not with the size of the change (https://atlasgo.io/lint/analyzers). They are reported under

the change (https://atlasgo.io/lint/analyzers). They are reported under

A statement can opt out of named checks with a directive, with the user's approval (https://atlasgo.io/versioned/lint#nolint-directive):

(https://atlasgo.io/versioned/lint#nolint-directive):

The env's `diff` block shapes every plan (https://atlasgo.io/versioned/diff):

ones unchanged, and run `atlas migrate hash`. - To undo a partially applied file instead, run `atlas migrate down` before editing it, which reverts   the applied statements one at a time (https://atlasgo.io/versioned/down). Once the file is

- To undo a partially applied file instead, run `atlas migrate down` before editing it, which reverts   the applied statements one at a time (https://atlasgo.io/versioned/down). Once the file is edited   and rehashed, `down` refuses it with

the applied statements one at a time (https://atlasgo.io/versioned/down). Once the file is edited

Add `mode=cluster` to the URL and the dev URL (https://atlasgo.io/guides/clickhouse/cluster-mode):

A setting a statement needs, such as `allow_suspicious_low_cardinality_types`, can come from four places (https://atlasgo.io/guides/clickhouse/session-settings):

(https://atlasgo.io/guides/clickhouse/session-settings):

A database that has tables but no revisions table is refused until it gets a baseline: the first migration, recorded as applied without running (https://atlasgo.io/versioned/apply). Generate it with a

migration, recorded as applied without running (https://atlasgo.io/versioned/apply). Generate it with a

How Atlas models ClickHouse objects, what each one needs, and the cases where its plan differs from what a hand-written migration would do. The full attribute reference is https://atlasgo.io/hcl/clickhouse,

a hand-written migration would do. The full attribute reference is https://atlasgo.io/hcl/clickhouse,

and the overview is https://atlasgo.io/guides/clickhouse/supported-objects. HCL syntax is in

WASM modules and WASM UDFs need ClickHouse 26.3 or later, with WebAssembly enabled in the server configuration, on the target and on the dev database, and `wasm_modules = true` in `mode "clickhouse"` (https://atlasgo.io/guides/clickhouse/wa

(https://atlasgo.io/guides/clickhouse/wasm).

Named collections need `named_collections = true`, server scope, and a user allowed to manage them (`named_collection_control`), on the target and the dev database (https://atlasgo.io/guides/clickhouse/named-collections).

(https://atlasgo.io/guides/clickhouse/named-collections).

Users, roles, grants, row policies, settings profiles, passwords, and the secret settings that engines, dictionaries, and named collections carry. The guides: https://atlasgo.io/guides/clickhouse/security-declarative and

dictionaries, and named collections carry. The guides: https://atlasgo.io/guides/clickhouse/security-declarative and https://atlasgo.io/guides/clickhouse/security-versioned. Everything here needs `atlas login`, as the

https://atlasgo.io/guides/clickhouse/security-declarative and

https://atlasgo.io/guides/clickhouse/security-versioned. Everything here needs `atlas login`, as the

Declare every other account, and review the first plan for drops. To keep drops out of every plan, set `drop_user = true` and `drop_role = true` in the env's `diff { skip { ... } }` policy (https://atlasgo.io/versioned/diff).

(https://atlasgo.io/versioned/diff).

- `member_of` grants roles. A `membership` block, with `role = role.app_writer` and `admin = true`,   grants one `WITH ADMIN OPTION` (https://atlasgo.io/hcl/clickhouse#user).

grants one `WITH ADMIN OPTION` (https://atlasgo.io/hcl/clickhouse#user).

password change with `changing password for user "<name>" should be handled manually`; without the   mode, the change is invisible. Set passwords in a hand-written file   that reads them from a template directory (https://atlasgo.io/atlas-s

mode, the change is invisible. Set passwords in a hand-written file   that reads them from a template directory (https://atlasgo.io/atlas-schema/projects) and starts with   `-- atlas:sensitive`, so they are never logged.

that reads them from a template directory (https://atlasgo.io/atlas-schema/projects) and starts with

dictionary, a function, a named collection, or a single column. `to` takes a role or user reference or a name. `privileges` takes ClickHouse privileges, such as `SELECT`, `INSERT`, `ALTER`, `CREATE`, `DROP`, `dictGet`, or `ALL` (https://atl

`dictGet`, or `ALL` (https://atlasgo.io/hcl/clickhouse#permission):

Kafka, RabbitMQ, NATS, S3Queue, and FileLog tables are recreated for any change, a comment included. - Named collections are created and changed with their keys, and empty values. Value changes are not   planned (https://atlasgo.io/guides/c

planned (https://atlasgo.io/guides/clickhouse/named-collections).

Each case starts from an empty database. Migrate to the version before the change, seed rows, migrate to the version under test, and check the data (https://atlasgo.io/testing/migrate):

the version under test, and check the data (https://atlasgo.io/testing/migrate):

This skill is `SKILL.md` plus seven reference files under `references/`, each served at `https://atlasgo.io/skills/atlas-databricks/references/<name>`. Read a reference when the task needs it:

`https://atlasgo.io/skills/atlas-databricks/references/<name>`. Read a reference when the task needs it:

The `atlas` skill, installed next to this one (`../atlas/SKILL.md`). If it is missing, download https://atlasgo.io/skills/atlas/SKILL.md to `../atlas/SKILL.md` and each reference file listed in its

https://atlasgo.io/skills/atlas/SKILL.md to `../atlas/SKILL.md` and each reference file listed in its

- Databricks HCL reference: https://atlasgo.io/hcl/databricks

- Dev database: https://atlasgo.io/concepts/dev-database

- Connection URLs and scope: https://atlasgo.io/concepts/url

- Databricks guide: https://atlasgo.io/guides/databricks/automatic-migrations

- Lint checks: https://atlasgo.io/lint/analyzers

- Guides for each database: https://atlasgo.io/databases

When no analyzer covers a check, or the user states a convention, write a custom rule in Atlas's HCL rule language. `atlas schema lint` and `atlas migrate lint` enforce it on every change (https://atlasgo.io/lint/rules). Lint needs `atlas l

rule language. `atlas schema lint` and `atlas migrate lint` enforce it on every change (https://atlasgo.io/lint/rules). Lint needs `atlas login`. If `atlas whoami` shows no login, ask the user to run `atlas login`; a user without an account

(https://atlasgo.io/lint/rules). Lint needs `atlas login`. If `atlas whoami` shows no login, ask the user

Rules live in `.rule.hcl` files. The language reference is https://atlasgo.io/hcl/rule.

Databricks uses the base rule language, with no Databricks-specific attributes. The attributes each object exposes, and the child objects a rule can walk into (https://atlasgo.io/hcl/rule#predicate):

object exposes, and the child objects a rule can walk into (https://atlasgo.io/hcl/rule#predicate):

Adapt the closest one before writing a rule from scratch (https://atlasgo.io/lint/rules#examples).

Add the rule files to `atlas.hcl`, globally or inside an env (https://atlasgo.io/lint/rules):

The dev database is a temporary database Atlas uses to load the desired state, replay migrations, and compute plans (https://atlasgo.io/concepts/dev-database). Databricks does not run in Docker, so the dev

compute plans (https://atlasgo.io/concepts/dev-database). Databricks does not run in Docker, so the dev

The Databricks driver ships only in the extended Atlas binary (https://atlasgo.io/guides/databricks/automatic-migrations):

(https://atlasgo.io/guides/databricks/automatic-migrations):

curl -sSf https://atlasgo.sh | ATLAS_FLAVOR="databricks" sh

[Credential-related source omitted]

The `schema` parameter decides what Atlas covers (https://atlasgo.io/concepts/url#scope):

The rules of the HCL schema language that matter on Databricks, and the places where HCL behaves differently from SQL. The language: https://atlasgo.io/atlas-schema/hcl. Column types:

differently from SQL. The language: https://atlasgo.io/atlas-schema/hcl. Column types:

https://atlasgo.io/atlas-schema/hcl-types. Every Databricks block and attribute:

https://atlasgo.io/hcl/databricks. The behavior behind each block is in `references/objects.md`.

- Name Databricks schema files `*.dbx.hcl` and test files `*.test.hcl`, so editors apply the right   schema (https://atlasgo.io/atlas-schema/hcl#file-naming-for-editor-support).

schema (https://atlasgo.io/atlas-schema/hcl#file-naming-for-editor-support).

The examples in this file build one schema, `retail_analytics`, taken from the tested examples of the Databricks changelog (https://atlasgo.io/changelog/databricks-object-attribute-coverage).

Databricks changelog (https://atlasgo.io/changelog/databricks-object-attribute-coverage).

A schema file declares the values it expects, and `atlas.hcl` passes them through `data "hcl_schema"` (https://atlasgo.io/atlas-schema/projects):

(https://atlasgo.io/atlas-schema/projects):

Databricks has no driver-specific analyzers. Lint runs these (https://atlasgo.io/lint/analyzers):

Statement rules fill gaps for Databricks-specific risks, such as a rewrite of a materialized view, which refreshes it in full (https://atlasgo.io/lint/analyzers#statement-rules):

which refreshes it in full (https://atlasgo.io/lint/analyzers#statement-rules):

Each check is tuned in the `lint` block (https://atlasgo.io/lint/analyzers#destructive-changes):

Databricks runs no statement in a transaction, and its SQL driver cannot open one. Atlas plans every Databricks change as non-transactional, and each statement commits on its own (https://atlasgo.io/versioned/apply#transaction-configuration

(https://atlasgo.io/versioned/apply#transaction-configuration):

- A file or a plan that fails halfway stays half applied. The statements before the failure remain,   and Atlas records how many statements of the file ran, so `atlas migrate status` shows the file as   partially applied (https://atlasgo.io

and Atlas records how many statements of the file ran, so `atlas migrate status` shows the file as   partially applied (https://atlasgo.io/versioned/troubleshoot). - The next `atlas migrate apply` continues from the statement that failed. F

partially applied (https://atlasgo.io/versioned/troubleshoot).

- If the connection drops between a statement and its entry in the revisions table, Atlas resumes one   statement early. Revert that statement by hand before the next run   (https://atlasgo.io/versioned/troubleshoot#connection-loss-failures

statement early. Revert that statement by hand before the next run   (https://atlasgo.io/versioned/troubleshoot#connection-loss-failures). - `atlas migrate down` reverts statement by statement on Databricks, without a transaction, and

(https://atlasgo.io/versioned/troubleshoot#connection-loss-failures).

- `atlas migrate down` reverts statement by statement on Databricks, without a transaction, and   updates the revisions table after each, so a run that fails midway is re-run to continue   (https://atlasgo.io/versioned/down). Reverting a dr

updates the revisions table after each, so a run that fails midway is re-run to continue   (https://atlasgo.io/versioned/down). Reverting a dropped table or column recreates it empty. A file   that drops a generated or identity column has n

(https://atlasgo.io/versioned/down). Reverting a dropped table or column recreates it empty. A file

A target that has objects but no revisions table is refused until it gets a baseline: the first migration, recorded as applied without running (https://atlasgo.io/versioned/apply#existing-databases).

migration, recorded as applied without running (https://atlasgo.io/versioned/apply#existing-databases).

How Atlas models Databricks objects, the cases where its plan differs from what a hand-written migration would do, and the changes it refuses to plan. The full attribute reference is https://atlasgo.io/hcl/databricks, and the HCL for each o

https://atlasgo.io/hcl/databricks, and the HCL for each object is in `references/hcl.md`.

Grants on schemas, tables, views, materialized views, functions, and procedures, the Unity Catalog principals they name, and the column masks and row filters that limit what a principal reads. The HCL blocks: https://atlasgo.io/hcl/databric

blocks: https://atlasgo.io/hcl/databricks#permission.

`ref()` takes a schema, a table, a view, or a materialized view. In a `composite_schema`, one part can declare the objects and another the grants on them; both load on the dev catalog, so the grants plan as ordinary ones (https://atlasgo.io

as ordinary ones (https://atlasgo.io/atlas-schema/projects#data-source-composite_schema).

Each case starts from an empty dev catalog. Migrate to a version, seed rows, migrate further, and check the data (https://atlasgo.io/guides/testing/data-migrations). The same shape covers the logic in the

the data (https://atlasgo.io/guides/testing/data-migrations). The same shape covers the logic in the

is described for SQL Server 2022; where a compatibility level changes it, the text says so. Azure SQL Database follows the same rules, and Fabric Data Warehouse has a guide of its own (https://atlasgo.io/guides/azure-fabric).

(https://atlasgo.io/guides/azure-fabric).

This skill is `SKILL.md` plus seven reference files under `references/`, each served at `https://atlasgo.io/skills/atlas-mssql/references/<name>`. Read a reference when the task needs it:

`https://atlasgo.io/skills/atlas-mssql/references/<name>`. Read a reference when the task needs it:

The `atlas` skill, installed next to this one (`../atlas/SKILL.md`). If it is missing, download https://atlasgo.io/skills/atlas/SKILL.md to `../atlas/SKILL.md` and each reference file listed in its

https://atlasgo.io/skills/atlas/SKILL.md to `../atlas/SKILL.md` and each reference file listed in its

- SQL Server HCL reference: https://atlasgo.io/hcl/mssql

- SQL Server guide: https://atlasgo.io/guides/mssql

- Security: https://atlasgo.io/guides/mssql/security-declarative,

https://atlasgo.io/guides/mssql/security-versioned

- Seed data: https://atlasgo.io/guides/mssql/seed-data

- Dev database: https://atlasgo.io/concepts/dev-database

- Lint checks: https://atlasgo.io/lint/analyzers

- Guides for each database: https://atlasgo.io/databases

own. When no analyzer covers a check, or the user states a convention, write a custom rule in Atlas's HCL rule language. A rule can check any attribute of any object Atlas inspects, and `atlas schema lint` and `atlas migrate lint` enforce i

HCL rule language. A rule can check any attribute of any object Atlas inspects, and `atlas schema lint` and `atlas migrate lint` enforce it on every change (https://atlasgo.io/lint/rules). Lint needs `atlas login`, which SQL Server needs an

and `atlas migrate lint` enforce it on every change (https://atlasgo.io/lint/rules). Lint needs

Rules live in `.rule.hcl` files. The language reference is https://atlasgo.io/hcl/rule.

Add the rule files to `atlas.hcl`, globally or inside an env (https://atlasgo.io/lint/rules):

The dev database is a temporary database Atlas uses to load the desired state, replay migrations, and compute plans (https://atlasgo.io/concepts/dev-database). For SQL Server it must match the target's

compute plans (https://atlasgo.io/concepts/dev-database). For SQL Server it must match the target's

`fedauth` method (Azure SQL and Fabric below). - Percent-encode special characters in passwords, or build the URL with `urlescape`:   `urlescape(getenv("DB_PASSWORD"))` (https://atlasgo.io/faq/url-special-chars).

- Percent-encode special characters in passwords, or build the URL with `urlescape`:   `urlescape(getenv("DB_PASSWORD"))` (https://atlasgo.io/faq/url-special-chars). - The user Atlas connects as must be able to read every object Atlas manag

`urlescape(getenv("DB_PASSWORD"))` (https://atlasgo.io/faq/url-special-chars).

`mode` decides what Atlas covers (https://atlasgo.io/concepts/url):

The `docker://` driver starts a fresh container for each run (https://atlasgo.io/concepts/dev-database).

- `docker://` needs a Docker client and a reachable daemon. Inside the `arigaio/atlas` image, or on a CI   runner without Docker, point `dev` at a separate SQL Server container instead   (https://atlasgo.io/faq/docker-in-docker):

(https://atlasgo.io/faq/docker-in-docker):

`atlas tool docker` creates a named container from a `docker://` URL and prints its connection URL. It cleans the database if it is not empty, so never run it against a container that holds data to keep (https://atlasgo.io/cli-reference#atl

(https://atlasgo.io/cli-reference#atlas-tool-docker). The container runs until `atlas tool docker kill`:

Without Docker, a `dev` block connects to an existing empty database, applies the `baseline`, and restores the database to its original state on exit (https://atlasgo.io/concepts/dev-database#providing-your-own-dev-database):

(https://atlasgo.io/concepts/dev-database#providing-your-own-dev-database):

- Azure SQL Database and Managed Instance with Microsoft Entra ID use the `azuresql://` scheme. As with   `sqlserver://`, `mode` sets the scope (https://atlasgo.io/concepts/url):

`sqlserver://`, `mode` sets the scope (https://atlasgo.io/concepts/url):

- Fabric Data Warehouse cannot run in Docker: the dev URL is a separate, empty warehouse on   `azuresql://`. Atlas adds `-- atlas:txmode none` to every migration file and `NOT ENFORCED` to keys,   and a primary key sets `nonclustered = true

and a primary key sets `nonclustered = true` (https://atlasgo.io/guides/azure-fabric).

The rules of the HCL schema language that matter on SQL Server, and the places where HCL behaves differently from T-SQL. The language: https://atlasgo.io/atlas-schema/hcl. Column types:

differently from T-SQL. The language: https://atlasgo.io/atlas-schema/hcl. Column types:

https://atlasgo.io/atlas-schema/hcl-types. Every SQL Server block and attribute:

https://atlasgo.io/hcl/mssql.

- Name SQL Server schema files `*.ms.hcl` and test files `*.test.hcl`, so editors apply the right   schema (https://atlasgo.io/atlas-schema/hcl#file-naming-for-editor-support).

schema (https://atlasgo.io/atlas-schema/hcl#file-naming-for-editor-support).

from the database's default. - `renamed_from` plans `sp_rename` instead of dropping the old column and adding a new one   (https://atlasgo.io/guides/destructive-change-policy):

(https://atlasgo.io/guides/destructive-change-policy):

Write parameters inline: `decimal(10,2)`, `nvarchar(255)`, `datetime2(7)` (https://atlasgo.io/atlas-schema/hcl-types):

(https://atlasgo.io/atlas-schema/hcl-types):

Rows are declared next to the table in a `data` block, and applied only when the env enables data sync (https://atlasgo.io/guides/mssql/seed-data):

(https://atlasgo.io/guides/mssql/seed-data):

A schema file declares the values it expects, and `atlas.hcl` passes them through `data "hcl_schema"` (https://atlasgo.io/atlas-schema/input-variables):

(https://atlasgo.io/atlas-schema/input-variables):

SQL Server has no analyzers of its own (no `MS*` codes). The generic ones apply (https://atlasgo.io/lint/analyzers):

(https://atlasgo.io/lint/analyzers):

Each check is tuned in the `lint` block (https://atlasgo.io/lint/analyzers#checks):

- `atlas migrate apply` runs each file in its own transaction by default (`--tx-mode file`); `all` runs   every pending file in one, and `none` runs statements without one. `atlas schema apply` supports   `file` and `none` (https://atlasgo.

every pending file in one, and `none` runs statements without one. `atlas schema apply` supports   `file` and `none` (https://atlasgo.io/versioned/apply#transaction-configuration). - DDL is transactional on SQL Server: a file that fails is 

`file` and `none` (https://atlasgo.io/versioned/apply#transaction-configuration).

- Migration files are T-SQL sent to the server, not `sqlcmd` scripts. `:setvar`, `:r`, and `$(var)`   fail with `mssql: Incorrect syntax near ':'.` Use input variables in `atlas.hcl`, or a template   directory (https://atlasgo.io/guides/mig

fail with `mssql: Incorrect syntax near ':'.` Use input variables in `atlas.hcl`, or a template   directory (https://atlasgo.io/guides/migration-dirs/template-directory). - `executing statement "..." from version "X": mssql: ...` names the 

directory (https://atlasgo.io/guides/migration-dirs/template-directory).

build with `RESUMABLE = ON` needs `-- atlas:txmode none`. - `NULL` to `NOT NULL` scans the table. The `not_null` diff policy writes the migration as a txtar file   with a pre-migration check that no row is `NULL`, which clears `MF104` (http

with a pre-migration check that no row is `NULL`, which clears `MF104` (https://atlasgo.io/hcl/config):

server do not wait for it. - `hook` blocks run SQL inside the migration transaction, such as `SET LOCK_TIMEOUT 5000` in   `after_begin` (https://atlasgo.io/versioned/apply#migration-hooks). They do not run for

- `hook` blocks run SQL inside the migration transaction, such as `SET LOCK_TIMEOUT 5000` in   `after_begin` (https://atlasgo.io/versioned/apply#migration-hooks). They do not run for   `txmode none` files.

`after_begin` (https://atlasgo.io/versioned/apply#migration-hooks). They do not run for

A database that has objects but no revisions table is refused until it gets a baseline: the first migration recorded as applied without running (https://atlasgo.io/versioned/apply#existing-databases).

migration recorded as applied without running (https://atlasgo.io/versioned/apply#existing-databases).

Lookup tables can be declared with the schema and kept in sync on every apply (https://atlasgo.io/guides/mssql/seed-data). `INSERT` adds missing rows, `UPSERT` also updates them, and

(https://atlasgo.io/guides/mssql/seed-data). `INSERT` adds missing rows, `UPSERT` also updates them, and

How Atlas models SQL Server objects, and the cases where its plan differs from what a hand-written migration would do. The full attribute reference is https://atlasgo.io/hcl/mssql.

migration would do. The full attribute reference is https://atlasgo.io/hcl/mssql.

- An HCL `data` block cannot set an identity column: a row that gives one fails with   `cannot set value for generated column "id"`, and `preserve_ids` has no effect on SQL Server. Give a   lookup table a plain key, as the seed-data guide d

`cannot set value for generated column "id"`, and `preserve_ids` has no effect on SQL Server. Give a   lookup table a plain key, as the seed-data guide does (https://atlasgo.io/guides/mssql/seed-data), or   seed an identity table with `SET 

lookup table a plain key, as the seed-data guide does (https://atlasgo.io/guides/mssql/seed-data), or

A system-versioned table declares its period columns, the period, and the history table (https://atlasgo.io/atlas-schema/hcl#system-versioned-tables). The period columns are `datetime2`,

(https://atlasgo.io/atlas-schema/hcl#system-versioned-tables). The period columns are `datetime2`,

- `fulltext_catalog` and a table's `fulltext` block manage full-text search. They need a dev image with   full-text search installed, and SQL Server cannot create them inside a transaction   (https://atlasgo.io/atlas-schema/hcl#full-text-in

(https://atlasgo.io/atlas-schema/hcl#full-text-index).

Database roles, database users, GRANT and REVOKE, and what Atlas leaves to hand-written migrations on SQL Server. The guides: https://atlasgo.io/guides/mssql/security-declarative and

SQL Server. The guides: https://atlasgo.io/guides/mssql/security-declarative and

https://atlasgo.io/guides/mssql/security-versioned.

Roles, users, and permissions are left out of inspection and planning by default. Enable them in the env's `schema` block (https://atlasgo.io/atlas-schema/hcl#enabling-roles-and-permissions):

env's `schema` block (https://atlasgo.io/atlas-schema/hcl#enabling-roles-and-permissions):

undeclared one is planned for `DROP USER` or `DROP ROLE`. Review the first plan. The `skip` diff   policy takes `drop_role = true` and `drop_user = true` to keep those drops out of plans   (https://atlasgo.io/versioned/diff#diff-policy).

policy takes `drop_role = true` and `drop_user = true` to keep those drops out of plans   (https://atlasgo.io/versioned/diff#diff-policy). - SQL Server roles and users have no `external` attribute (it fails with

(https://atlasgo.io/versioned/diff#diff-policy).

- A `user` takes `default_schema`, `login_name`, `default_language`,   `allow_encrypted_value_modifications`, `comment`, and `member_of`; a `role` takes `member_of`, which   builds role hierarchies (https://atlasgo.io/atlas-schema/hcl#enabl

`allow_encrypted_value_modifications`, `comment`, and `member_of`; a `role` takes `member_of`, which   builds role hierarchies (https://atlasgo.io/atlas-schema/hcl#enabling-roles-and-permissions). Roles   and users share one namespace: a ro

builds role hierarchies (https://atlasgo.io/atlas-schema/hcl#enabling-roles-and-permissions). Roles

The `permission` block grants on a schema, table, view, function, procedure, `type_alias`, `type_table`, or a column of a table or view, to a role or user reference or a name as a string (https://atlasgo.io/hcl/mssql):

(https://atlasgo.io/hcl/mssql):

The env lists the test files (https://atlasgo.io/testing/schema):

- Functions and procedures: normal inputs, edge cases, and error paths with `catch`. Call a procedure   with `EXEC dbo.proc_name @arg = 1` (https://atlasgo.io/guides/testing/procedures).

with `EXEC dbo.proc_name @arg = 1` (https://atlasgo.io/guides/testing/procedures).

- Triggers: seed rows, change them, and check the side effects. A trigger runs once per statement, so   test a multi-row `UPDATE`: a trigger written for one row (`SELECT @id = id FROM inserted`) passes a   single-row test and loses rows on 

test a multi-row `UPDATE`: a trigger written for one row (`SELECT @id = id FROM inserted`) passes a   single-row test and loses rows on a bulk one (https://atlasgo.io/guides/testing/triggers). - Views and computed columns: seed rows and com

single-row test and loses rows on a bulk one (https://atlasgo.io/guides/testing/triggers).

- Views and computed columns: seed rows and compare the output (https://atlasgo.io/guides/testing/views).

`template attribute is supported only for postgres dev-databases`. Each test case restores the dev database when it ends. Set `parallel = true` only on stateless cases, without `INSERT` or `CREATE` (https://atlasgo.io/testing/schema): paral

(https://atlasgo.io/testing/schema): parallel cases share the dev database and see each other's rows.

Each case starts from an empty database. Migrate to the version before the change, seed rows, migrate to the version under test, and check the data (https://atlasgo.io/guides/testing/data-migrations):

to the version under test, and check the data (https://atlasgo.io/guides/testing/data-migrations):

This skill is `SKILL.md` plus seven reference files under `references/`, each served at `https://atlasgo.io/skills/atlas-mysql/references/<name>`. Read a reference when the task needs it:

This skill is `SKILL.md` plus seven reference files under `references/`, each served at `https://atlasgo.io/skills/atlas-mysql/references/<name>`. Read a reference when the task needs it:

This skill is `SKILL.md` plus seven reference files under `references/`, each served at `https://atlasgo.io/skills/atlas-mysql/references/<name>`. Read a reference when the task needs it:

`https://atlasgo.io/skills/atlas-mysql/references/<name>`. Read a reference when the task needs it:

`https://atlasgo.io/skills/atlas-mysql/references/<name>`. Read a reference when the task needs it:

`https://atlasgo.io/skills/atlas-mysql/references/<name>`. Read a reference when the task needs it:

The `atlas` skill, installed next to this one (`../atlas/SKILL.md`). If it is missing, download https://atlasgo.io/skills/atlas/SKILL.md to `../atlas/SKILL.md` and each reference file listed in its

The `atlas` skill, installed next to this one (`../atlas/SKILL.md`). If it is missing, download https://atlasgo.io/skills/atlas/SKILL.md to `../atlas/SKILL.md` and each reference file listed in its

The `atlas` skill, installed next to this one (`../atlas/SKILL.md`). If it is missing, download https://atlasgo.io/skills/atlas/SKILL.md to `../atlas/SKILL.md` and each reference file listed in its

https://atlasgo.io/skills/atlas/SKILL.md to `../atlas/SKILL.md` and each reference file listed in its

https://atlasgo.io/skills/atlas/SKILL.md to `../atlas/SKILL.md` and each reference file listed in its

https://atlasgo.io/skills/atlas/SKILL.md to `../atlas/SKILL.md` and each reference file listed in its

[Credential-related source omitted]

[Credential-related source omitted]

[Credential-related source omitted]

- MySQL HCL reference: https://atlasgo.io/hcl/mysql, and for MariaDB: https://atlasgo.io/hcl/mariadb

- MySQL HCL reference: https://atlasgo.io/hcl/mysql, and for MariaDB: https://atlasgo.io/hcl/mariadb

- MySQL HCL reference: https://atlasgo.io/hcl/mysql, and for MariaDB: https://atlasgo.io/hcl/mariadb

- Dev database: https://atlasgo.io/concepts/dev-database

- Dev database: https://atlasgo.io/concepts/dev-database

- Dev database: https://atlasgo.io/concepts/dev-database

- Security: https://atlasgo.io/guides/mysql/security-declarative,

- Security: https://atlasgo.io/guides/mysql/security-declarative,

- Security: https://atlasgo.io/guides/mysql/security-declarative,

https://atlasgo.io/guides/mysql/security-versioned

https://atlasgo.io/guides/mysql/security-versioned

https://atlasgo.io/guides/mysql/security-versioned

- Lint checks: https://atlasgo.io/lint/analyzers

- Lint checks: https://atlasgo.io/lint/analyzers

- Lint checks: https://atlasgo.io/lint/analyzers

- Guides for each database: https://atlasgo.io/databases

- Guides for each database: https://atlasgo.io/databases

- Guides for each database: https://atlasgo.io/databases

the user states a convention, write a custom rule in Atlas's HCL rule language. A rule can check any attribute of any object Atlas inspects, and `atlas schema lint` and `atlas migrate lint` enforce it on every change (https://atlasgo.io/lin

attribute of any object Atlas inspects, and `atlas schema lint` and `atlas migrate lint` enforce it on every change (https://atlasgo.io/lint/rules). Lint needs `atlas login`. If `atlas whoami` shows no login, ask the user to run `atlas logi

every change (https://atlasgo.io/lint/rules). Lint needs `atlas login`. If `atlas whoami` shows no

Rules live in `.rule.hcl` files. The language reference is https://atlasgo.io/hcl/rule.

The attributes MySQL objects expose to predicates, and the child objects a predicate or rule can walk into (https://atlasgo.io/hcl/rule#predicate):

into (https://atlasgo.io/hcl/rule#predicate):

From the docs (https://atlasgo.io/lint/rules#examples). Adapt the closest one before writing a rule

Add the rule files to `atlas.hcl`, globally or inside an env (https://atlasgo.io/lint/rules):

The dev database is a temporary database Atlas uses to load the desired state, replay migrations, and compute plans (https://atlasgo.io/concepts/dev-database). For MySQL it must match the target's version,

compute plans (https://atlasgo.io/concepts/dev-database). For MySQL it must match the target's version,

In MySQL, a schema is a database. The URL's path names it, and decides what Atlas covers (https://atlasgo.io/concepts/url#scope):

(https://atlasgo.io/concepts/url#scope):

- The dev URL takes the target's scope: `docker://mysql/8/dev` for a schema-scoped target, and   `docker://mysql/8` for a server-scoped one (https://atlasgo.io/concepts/dev-database). Mixing them

`docker://mysql/8` for a server-scoped one (https://atlasgo.io/concepts/dev-database). Mixing them

- At schema scope, Atlas cannot change the database's own character set, collation, or comment: see   Character Sets and Collations below. - `--include` patterns follow the scope (https://atlasgo.io/faq/manage-single-table). At schema scope

Character Sets and Collations below. - `--include` patterns follow the scope (https://atlasgo.io/faq/manage-single-table). At schema scope a   pattern names the table, and at server scope it starts with the database:

- `--include` patterns follow the scope (https://atlasgo.io/faq/manage-single-table). At schema scope a

The `docker://` driver starts a fresh container for each run (https://atlasgo.io/concepts/dev-database):

- `docker://` needs a Docker client and a reachable daemon. Without one, such as in CI, run a MySQL   service container and give its URL as the dev database, for example   `mysql://root:pass@localhost:3306/dev` (https://atlasgo.io/faq/docke

`mysql://root:pass@localhost:3306/dev` (https://atlasgo.io/faq/docker-in-docker).

`atlas tool docker` creates a named container from a `docker://` URL and prints its connection URL. It also applies the baseline, and cleans the database if it is not empty, so never run it against a container that holds data to keep (https

also applies the baseline, and cleans the database if it is not empty, so never run it against a container that holds data to keep (https://atlasgo.io/cli-reference#atlas-tool-docker). The container runs until `atlas tool docker kill --name

container that holds data to keep (https://atlasgo.io/cli-reference#atlas-tool-docker). The container

(https://atlasgo.io/getting-started#step-4-set-up-your-database):

A `docker "mysql"` or `docker "mariadb"` block configures the dev container: `image` (required), `schema`, `baseline`, `init`, `command`, `platform`, `build`, and more (https://atlasgo.io/hcl/config#docker.mysql). The `docker` and `dev` blo

`schema`, `baseline`, `init`, `command`, `platform`, `build`, and more (https://atlasgo.io/hcl/config#docker.mysql). The `docker` and `dev` blocks need `atlas login`. If `atlas whoami` shows no login, ask the user to run `atlas login`; a us

(https://atlasgo.io/hcl/config#docker.mysql). The `docker` and `dev` blocks need `atlas login`. If

`init` runs SQL once the server is up, such as global settings (https://atlasgo.io/concepts/dev-database#docker-init-script):

(https://atlasgo.io/concepts/dev-database#docker-init-script):

A `dev "mysql"` block connects to an existing database instead of a container (https://atlasgo.io/concepts/dev-database#providing-your-own-dev-database). The database must be empty

(https://atlasgo.io/concepts/dev-database#providing-your-own-dev-database). The database must be empty

- Declare them on the schema, so the desired state does not depend on the dev server   (https://atlasgo.io/atlas-schema/hcl#schema):

(https://atlasgo.io/atlas-schema/hcl#schema):

`modify schema "<name>" is not allowed when migration plan is scoped to one schema`. Give the dev   database the target's settings, or use server scope for both URLs, which lets Atlas change the   database's character set and collation (htt

database the target's settings, or use server scope for both URLs, which lets Atlas change the   database's character set and collation (https://atlasgo.io/faq/modify-schema-error). - A different server character set also causes drift that 

database's character set and collation (https://atlasgo.io/faq/modify-schema-error).

expression defaults, functional indexes, checks, and views differ only by an introducer, such as   `_latin1'-'` against `_utf8mb4'-'`. Start the dev server with the target's settings, through   `command` (https://atlasgo.io/faq/mysql-charse

`command` (https://atlasgo.io/faq/mysql-charset-collation-drift):

- RDS and Aurora MySQL with IAM authentication: the URL takes a token from the `aws_rds_token` data   source, with `allowCleartextPasswords`   (https://atlasgo.io/atlas-schema/projects#data-source-aws_rds_token):

(https://atlasgo.io/atlas-schema/projects#data-source-aws_rds_token):

IAM users on the dev database are covered below. - Cloud SQL for MySQL: the `gcp_cloudsql_token` data source signs in with IAM   (https://atlasgo.io/atlas-schema/projects#data-source-gcp_cloudsql_token):

(https://atlasgo.io/atlas-schema/projects#data-source-gcp_cloudsql_token):

- Azure Database for MySQL with Entra ID: the user name contains `@`, so build the URL with   `urluserinfo` (https://atlasgo.io/atlas-schema/projects#data-source-azure_db_token):

`urluserinfo` (https://atlasgo.io/atlas-schema/projects#data-source-azure_db_token):

RDS creates IAM users with a plugin that exists only on RDS. A migration directory or a SQL schema with such a statement, `CREATE USER 'app_iam' IDENTIFIED WITH AWSAuthenticationPlugin AS 'RDS';`, fails on a stock MySQL image (https://atlas

stock MySQL image (https://atlasgo.io/faq/mock-mysql-rds-aws-auth-plugin):

- To replay the migrations on a local database, start it from the same image:   `atlas tool docker --name my-db --env <env>` reads the env's dev URL and prints the URL of a named   container to apply to (https://atlasgo.io/cli-reference#atl

[Credential-related source omitted]

[Credential-related source omitted]

container to apply to (https://atlasgo.io/cli-reference#atlas-tool-docker).

- MySQL does not require TLS by default. `?tls=true` requires it; `?ssl-ca` sets a custom CA, and   `?ssl-cert` with `?ssl-key` a client certificate (https://atlasgo.io/concepts/url#mysql).

`?ssl-cert` with `?ssl-key` a client certificate (https://atlasgo.io/concepts/url#mysql).

- Percent-encode special characters in passwords, or build the URL with `urlescape`   (https://atlasgo.io/faq/url-special-chars). An unescaped password fails with an error such as   `Error: mysql: query system variables: dial tcp: lookup ro

(https://atlasgo.io/faq/url-special-chars). An unescaped password fails with an error such as

`Error 1064 (42000): You have an error in your SQL syntax` near `''`. Set   `$PSDefaultParameterValues['Out-File:Encoding'] = 'utf8'` first   (https://atlasgo.io/faq/schema-encoding).

(https://atlasgo.io/faq/schema-encoding).

| `server does not allow insecure connections, client must use SSL/TLS` | The server requires TLS | Add `?tls=true` to the URL | | `invalid port ":..." after host`, or `net/url: invalid userinfo` | A special character in the password breaks

| `invalid port ":..." after host`, or `net/url: invalid userinfo` | A special character in the password breaks the URL | Percent-encode the password, or build the URL with `urlescape` | | `Error 1049 (42000): Unknown database '<database_na

| `Error 1049 (42000): Unknown database '<database_name>'` | The database in the URL does not exist, or its name is not escaped | Check that it exists, and quote or percent-encode the name (https://atlasgo.io/faq/mysql-error-1049-database-n

The rules of the HCL schema language that matter on MySQL and MariaDB, and the places where HCL behaves differently from SQL. The language: https://atlasgo.io/atlas-schema/hcl. Column types:

differently from SQL. The language: https://atlasgo.io/atlas-schema/hcl. Column types:

https://atlasgo.io/atlas-schema/hcl-types. Every MySQL block and attribute: https://atlasgo.io/hcl/mysql,

and for MariaDB: https://atlasgo.io/hcl/mariadb.

- Name MySQL schema files `*.my.hcl`, MariaDB files `*.ma.hcl`, and test files `*.test.hcl`, so editors   apply the right schema (https://atlasgo.io/atlas-schema/hcl#file-naming-for-editor-support).

apply the right schema (https://atlasgo.io/atlas-schema/hcl#file-naming-for-editor-support).

- A renamed column or table is planned as a drop and an add, which loses its data, unless the rename is   confirmed. In a non-interactive run, such as an agent or CI, declare it with `renamed_from`   (https://atlasgo.io/guides/destructive-c

(https://atlasgo.io/guides/destructive-change-policy):

`-- atlas:renamed_from legacy_email`. - `auto_increment = true` on a column makes it `AUTO_INCREMENT`. On the table, `auto_increment` sets the   start value (https://atlasgo.io/atlas-schema/hcl#auto-increment):

start value (https://atlasgo.io/atlas-schema/hcl#auto-increment):

- `invisible = true` makes a column invisible to `SELECT *` (MySQL 8.0.23 and later). - Generated columns take an expression in `as`, or an `as` block with the storage type. On MySQL, they   are `VIRTUAL` by default (https://atlasgo.io/atla

are `VIRTUAL` by default (https://atlasgo.io/atlas-schema/hcl#generated-columns):

A generated column that is part of a primary key or foreign key must be `STORED`   (https://atlasgo.io/guides/mysql/generated-columns). Adding a `STORED` one copies the table

(https://atlasgo.io/guides/mysql/generated-columns). Adding a `STORED` one copies the table

Write parameters inline: `varchar(255)`, `decimal(5,2)`, `datetime(6)` (https://atlasgo.io/atlas-schema/hcl-types).

(https://atlasgo.io/atlas-schema/hcl-types).

- A `check` takes its SQL in `expr`. MySQL enforces checks from 8.0.16; earlier versions parse and   ignore them (https://atlasgo.io/guides/mysql/check-constraint):

ignore them (https://atlasgo.io/guides/mysql/check-constraint):

`SPATIAL`, and a full-text index takes `parser`. MySQL indexes have no `where`, `include`, or `ops`. - Functional indexes (MySQL 8.0.13 and later) use `on` blocks with `expr`   (https://atlasgo.io/guides/mysql/functional-indexes; more examp

- Functional indexes (MySQL 8.0.13 and later) use `on` blocks with `expr`   (https://atlasgo.io/guides/mysql/functional-indexes; more examples, such as JSON values:   https://atlasgo.io/faq/mysql-functional-indexes):

(https://atlasgo.io/guides/mysql/functional-indexes; more examples, such as JSON values:

https://atlasgo.io/faq/mysql-functional-indexes):

- An index on a `BLOB` or `TEXT` column needs a prefix length, or MySQL fails with   `ERROR 1170 (42000): BLOB/TEXT column 'message' used in key specification without a key length`   (https://atlasgo.io/guides/mysql/prefix-indexes):

(https://atlasgo.io/guides/mysql/prefix-indexes):

- `desc = true` in an `on` block builds a descending index part (MySQL 8.0 and later, InnoDB)   (https://atlasgo.io/guides/mysql/descending-indexes).

(https://atlasgo.io/guides/mysql/descending-indexes).

- `engine` sets the storage engine, and takes `InnoDB`, `MyISAM`, other engine names, or a string   (https://atlasgo.io/atlas-schema/hcl#table). MyISAM ignores foreign keys (`references/objects.md`).

(https://atlasgo.io/atlas-schema/hcl#table). MyISAM ignores foreign keys (`references/objects.md`).

`LIST`, `LIST_COLUMNS`, `HASH`, `LINEAR_HASH`, `KEY`, or `LINEAR_KEY`), the key in `by` blocks or   `columns`, and each named partition inside it. Bounds are strings, including `"MAXVALUE"`   (https://atlasgo.io/atlas-schema/hcl#partitions)

(https://atlasgo.io/atlas-schema/hcl#partitions):

- A view takes `as`, `depends_on`, `check_option` (`LOCAL` or `CASCADED`), and `security`   (https://atlasgo.io/atlas-schema/hcl#view):

(https://atlasgo.io/atlas-schema/hcl#view):

- A function's arguments are named `arg` blocks, and it sets `deterministic`, `data_access`, and   `security`; there is no `lang`. Without `deterministic = true`, the function is `NOT DETERMINISTIC`   (https://atlasgo.io/atlas-schema/hcl#fu

(https://atlasgo.io/atlas-schema/hcl#function):

- A procedure's `arg` takes `mode` (`IN`, `OUT`, or `INOUT`), and `charset` or `collate`. - A trigger has its body in `as`, one timing block (`before` or `after`) with one event, and `follows`   or `precedes` to order triggers on the same e

or `precedes` to order triggers on the same event (https://atlasgo.io/atlas-schema/hcl#trigger):

Rows are declared next to the table in a `data` block, and applied only when the env enables data sync (needs `atlas login`, https://atlasgo.io/guides/mysql/seed-data):

(needs `atlas login`, https://atlasgo.io/guides/mysql/seed-data):

- `AUTO_INCREMENT` primary-key values are left out of the generated `INSERT` statements unless the   env's `data` block sets `preserve_ids = true`   (https://atlasgo.io/atlas-schema/hcl#preserving-explicit-ids). Preserving a literal `0` als

env's `data` block sets `preserve_ids = true`   (https://atlasgo.io/atlas-schema/hcl#preserving-explicit-ids). Preserving a literal `0` also needs   `NO_AUTO_VALUE_ON_ZERO` in the session's `sql_mode`.

(https://atlasgo.io/atlas-schema/hcl#preserving-explicit-ids). Preserving a literal `0` also needs

Input variables work as in any Atlas HCL schema (https://atlasgo.io/atlas-schema/input-variables). A

Most MySQL checks report a change that makes MySQL copy or rebuild the table, or block writes while it runs (https://atlasgo.io/lint/analyzers):

runs (https://atlasgo.io/lint/analyzers):

- `MY146`: archive the history first, with `FOR SYSTEM_TIME ALL`. - `MF104`: backfill the `NULL` rows first, and guard the migration with a check   (https://atlasgo.io/lint/analyzers#MF104):

(https://atlasgo.io/lint/analyzers#MF104):

A statement can opt out of named checks with a directive (https://atlasgo.io/versioned/lint#nolint-directive):

(https://atlasgo.io/versioned/lint#nolint-directive):

back a migration file, or a declarative plan, that fails halfway. The statements before the failure stay applied, and the schema and the revisions table can end up out of step (https://atlasgo.io/versioned/troubleshoot#a-word-on-transaction

(https://atlasgo.io/versioned/troubleshoot#a-word-on-transactions).

- `--tx-mode` does not change this: `all` cannot make several files atomic, because every DDL statement   commits the open transaction. Data statements that run before a DDL statement in the same file are   committed with it (https://atlasg

commits the open transaction. Data statements that run before a DDL statement in the same file are   committed with it (https://atlasgo.io/versioned/apply#transaction-configuration). - Atlas records each statement it applies, so a failed fi

committed with it (https://atlasgo.io/versioned/apply#transaction-configuration).

- Atlas records each statement it applies, so a failed file shows as partially applied in   `atlas migrate status`   (https://atlasgo.io/versioned/troubleshoot):

(https://atlasgo.io/versioned/troubleshoot):

- To undo a partially applied file instead, run `atlas migrate down`. On MySQL it reverts the applied   statements one at a time and updates the revisions table after each, so a run that fails midway is   re-run to continue (https://atlasgo

statements one at a time and updates the revisions table after each, so a run that fails midway is   re-run to continue (https://atlasgo.io/versioned/down). - If the connection drops between a statement and its entry in the revisions table,

re-run to continue (https://atlasgo.io/versioned/down).

- If the connection drops between a statement and its entry in the revisions table, Atlas resumes one   statement early. Revert that statement by hand before the next run   (https://atlasgo.io/versioned/troubleshoot#connection-loss-failures

statement early. Revert that statement by hand before the next run   (https://atlasgo.io/versioned/troubleshoot#connection-loss-failures). - When the schema and the revisions table disagree, `atlas migrate set <version>` updates the revisio

(https://atlasgo.io/versioned/troubleshoot#connection-loss-failures).

- When the schema and the revisions table disagree, `atlas migrate set <version>` updates the revisions   table only; it runs and reverts no SQL (https://atlasgo.io/faq/revisions-table-delete-latest). - `schema apply` has the same limit: a 

table only; it runs and reverts no SQL (https://atlasgo.io/faq/revisions-table-delete-latest).

- A stored program contains semicolons, so a file that creates one redefines the statement delimiter,   with the MySQL client's `DELIMITER` command or the `-- atlas:delimiter` directive   (https://atlasgo.io/versioned/new#custom-statements-

(https://atlasgo.io/versioned/new#custom-statements-delimiter):

- `migrate apply` and `schema apply` take `GET_LOCK` on MySQL and MariaDB, so two deployments cannot   apply at the same time. `--lock-timeout` waits 10 seconds by default; `--skip-lock` skips the lock   (https://atlasgo.io/versioned/apply#

apply at the same time. `--lock-timeout` waits 10 seconds by default; `--skip-lock` skips the lock   (https://atlasgo.io/versioned/apply#controlling-advisory-locks). - The lock is per server, and its name defaults to `atlas_migrate_execute`

(https://atlasgo.io/versioned/apply#controlling-advisory-locks).

A database that has tables but no revisions table is refused until it gets a baseline: the first migration, recorded as applied without running (https://atlasgo.io/versioned/apply#existing-databases):

migration, recorded as applied without running (https://atlasgo.io/versioned/apply#existing-databases):

Then pass its version once: `atlas migrate apply --baseline "20220811074144"`, or set `baseline` in the env's `migration` block. The GitHub action `migrate/apply` has no baseline input; use the env attribute (https://atlasgo.io/faq/migrate-

env's `migration` block. The GitHub action `migrate/apply` has no baseline input; use the env attribute (https://atlasgo.io/faq/migrate-baseline-github-action). When `--dev-url` points at a database that already has the revisions table, `mi

(https://atlasgo.io/faq/migrate-baseline-github-action). When `--dev-url` points at a database that

already has the revisions table, `migrate diff` fails with an error that starts with `connected database is not clean` and ends with `baseline version or allow-dirty is required`: point `--dev-url` at a dev database instead (https://atlasgo

`--dev-url` at a dev database instead (https://atlasgo.io/faq/migrate-diff-clean).

How Atlas models MySQL and MariaDB objects, and the cases where its plan differs from what a hand-written migration would do. The full attribute reference is https://atlasgo.io/hcl/mysql, with

hand-written migration would do. The full attribute reference is https://atlasgo.io/hcl/mysql, with

examples in https://atlasgo.io/atlas-schema/hcl. HCL syntax is in `references/hcl.md`, and the lint

Tables and columns, indexes, foreign keys, check and unique constraints, and comments work without a login. Partitions, views, full-text indexes, triggers, stored procedures, and functions need `atlas login`, and so do users, roles, and gra

login. Partitions, views, full-text indexes, triggers, stored procedures, and functions need `atlas login`, and so do users, roles, and grants (https://atlasgo.io/features). On MariaDB, temporal (system-versioned) tables need it too.

`atlas login`, and so do users, roles, and grants (https://atlasgo.io/features). On MariaDB, temporal

`orders_ibfk_1`. The dev database can pick a different name than the target, and the plan then   renames the constraint. Skip those renames with the `diff` policy   (https://atlasgo.io/faq/skip-constraint-rename):

(https://atlasgo.io/faq/skip-constraint-rename):

indexes, checks, and views. A functional index on `upper(concat('c', c))` inspects as ``upper(concat(_utf8mb4'c',`c`))``, so a plan made without a dev database drops and re-adds the index on every run (https://atlasgo.io/concepts/dev-databa

``upper(concat(_utf8mb4'c',`c`))``, so a plan made without a dev database drops and re-adds the index on every run (https://atlasgo.io/concepts/dev-database). Plan with a dev URL, on a server with the target's character set (`references/dev

on every run (https://atlasgo.io/concepts/dev-database). Plan with a dev URL, on a server with the

MariaDB has its own driver, with `maria://` URLs, `docker://maria/...` dev URLs, `docker "mariadb"` blocks, and `.ma.hcl` files (https://atlasgo.io/hcl/mariadb). Run a MariaDB dev database for a MariaDB

blocks, and `.ma.hcl` files (https://atlasgo.io/hcl/mariadb). Run a MariaDB dev database for a MariaDB

Users, roles, GRANT and REVOKE, and passwords. The guides: https://atlasgo.io/guides/mysql/security-declarative and

https://atlasgo.io/guides/mysql/security-declarative and

https://atlasgo.io/guides/mysql/security-versioned.

login. If `atlas whoami` shows no login, ask the user to run `atlas login`; a user without an account can start a free trial with it. Enable them in the env's `schema` block (https://atlasgo.io/guides/mysql/security-declarative):

(https://atlasgo.io/guides/mysql/security-declarative):

without a database in the path, such as `docker://mysql/8` for the dev database. - With `roles = true`, the desired state is authoritative over every user and role Atlas inspects on   the server (https://atlasgo.io/atlas-schema/hcl#external

- With `roles = true`, the desired state is authoritative over every user and role Atlas inspects on   the server (https://atlasgo.io/atlas-schema/hcl#external-roles-and-users). MySQL has no `external`   attribute, which PostgreSQL uses to 

the server (https://atlasgo.io/atlas-schema/hcl#external-roles-and-users). MySQL has no `external`

the first plan for other accounts. To keep drops out of every plan, set `drop_user = true` and   `drop_role = true` in the env's `diff { skip { ... } }` policy   (https://atlasgo.io/versioned/diff#diff-policy).

`drop_role = true` in the env's `diff { skip { ... } }` policy   (https://atlasgo.io/versioned/diff#diff-policy). - Passwords come from input variables, never from literals in the file. The declarative workflow needs

(https://atlasgo.io/versioned/diff#diff-policy).

`IDENTIFIED WITH caching_sha2_password`. Set the passwords from a template directory, with the   `-- atlas:sensitive` directive so they are never logged   (https://atlasgo.io/guides/mysql/security-versioned):

(https://atlasgo.io/guides/mysql/security-versioned):

- Account limits: `max_user_connections` (simultaneous), `max_connections`, `max_questions`, and   `max_updates` (per hour), plus `password_lifetime`, `password_expired`, and `comment`   (https://atlasgo.io/hcl/mysql).

`max_updates` (per hour), plus `password_lifetime`, `password_expired`, and `comment`   (https://atlasgo.io/hcl/mysql). - An RDS IAM user sets `auth_plugin` and no password. It is the HCL form of

(https://atlasgo.io/hcl/mysql).

- An RDS IAM user sets `auth_plugin` and no password. It is the HCL form of   `CREATE USER 'app_iam' IDENTIFIED WITH AWSAuthenticationPlugin AS 'RDS';`   (https://atlasgo.io/atlas-schema/hcl#external-roles-and-users):

(https://atlasgo.io/atlas-schema/hcl#external-roles-and-users):

single column. `to` takes a role name as a string, a role reference, or a user reference such as `user["api_user@%"]`. Routines take `EXECUTE`. `for_each` expands one block into a grant per object (https://atlasgo.io/guides/mysql/security-d

(https://atlasgo.io/guides/mysql/security-declarative):

Migration tests are listed the same way, under `test { migrate { src = [...] } }`. Without a project file, pass the dev URL and the directory (https://atlasgo.io/cli-reference#atlas-migrate-test):

file, pass the dev URL and the directory (https://atlasgo.io/cli-reference#atlas-migrate-test):

- Functions and procedures: normal inputs, edge cases, and error paths with `catch`   (https://atlasgo.io/guides/testing/functions, https://atlasgo.io/guides/testing/procedures).

(https://atlasgo.io/guides/testing/functions, https://atlasgo.io/guides/testing/procedures).

- Triggers: seed rows, change them, and check the side effects   (https://atlasgo.io/guides/testing/triggers). - Check constraints: `catch` a row that breaks the check. MySQL 8.0.15 and earlier ignore checks, so the

(https://atlasgo.io/guides/testing/triggers).

test also shows whether the dev database enforces them. - Generated columns: insert rows and compare the computed values. - Views: seed rows and compare the view's output (https://atlasgo.io/guides/testing/views).

- Views: seed rows and compare the view's output (https://atlasgo.io/guides/testing/views).

Each case starts from an empty database. Migrate to the version before the change, seed rows, migrate to the version under test, and check the data (https://atlasgo.io/guides/testing/data-migrations).

to the version under test, and check the data (https://atlasgo.io/guides/testing/data-migrations).

In GitHub Actions, the `migrate/test` action runs the tests against a MySQL service container (https://atlasgo.io/integrations/github-actions):

(https://atlasgo.io/integrations/github-actions):

Takes a repository from no Atlas setup to production in six stages, the same path as the Evaluating Atlas guide (https://atlasgo.io/guides/evaluation/intro). Each stage ends on a check the agent runs and

Atlas guide (https://atlasgo.io/guides/evaluation/intro). Each stage ends on a check the agent runs and

This skill is `SKILL.md` plus seven files, each served at `https://atlasgo.io/skills/atlas-onboard/<path>`:

The `atlas` skill, installed next to this one (`../atlas/SKILL.md`). If it is missing, download https://atlasgo.io/skills/atlas/SKILL.md to `../atlas/SKILL.md` and each reference file listed in its

https://atlasgo.io/skills/atlas/SKILL.md to `../atlas/SKILL.md` and each reference file listed in its

the user install it: `claude plugin update atlas@ariga` in Claude Code, or the `npx skills add ariga/atlas -a <agent> -y` command again in other agents. Until then, read it from https://atlasgo.io/skills/atlas-postgres/SKILL.md or https://a

https://atlasgo.io/skills/atlas-postgres/SKILL.md or https://atlasgo.io/skills/atlas-mysql/SKILL.md.

When stage 4 deploys with the Atlas Kubernetes Operator (4.6, 4.7), also read the `atlas-operator` skill (`../atlas-operator/SKILL.md`). Install and read it the same way, from https://atlasgo.io/skills/atlas-operator/SKILL.md when it is mis

skill (`../atlas-operator/SKILL.md`). Install and read it the same way, from https://atlasgo.io/skills/atlas-operator/SKILL.md when it is missing. It covers the operator's install, tokens, resource policies, and troubleshooting.

https://atlasgo.io/skills/atlas-operator/SKILL.md when it is missing. It covers the operator's install,

For stage 3 and the CI deploy job of stage 4, also read the `atlas-action` skill (`../atlas-action/SKILL.md`). Install and read it the same way, from https://atlasgo.io/skills/atlas-action/SKILL.md when it is missing. It covers the Atlas CI

(`../atlas-action/SKILL.md`). Install and read it the same way, from https://atlasgo.io/skills/atlas-action/SKILL.md when it is missing. It covers the Atlas CI steps on each platform, their tokens and permissions, and the fix for each faile

https://atlasgo.io/skills/atlas-action/SKILL.md when it is missing. It covers the Atlas CI steps on each

`atlas schema apply` plan each change against the target database, and the plan is reviewed. - Dev database: a temporary, isolated database Atlas uses as a sandbox to plan and check changes, usually   an ephemeral Docker container (https://

- Dev database: a temporary, isolated database Atlas uses as a sandbox to plan and check changes, usually   an ephemeral Docker container (https://atlasgo.io/concepts/dev-database#introduction). It   never holds data and is not the applicat

an ephemeral Docker container (https://atlasgo.io/concepts/dev-database#introduction). It

`skills-lock.json`. If the install already put them there, commit them unchanged. 3. Next steps: offer the practices from the guides that fit what the scan found, one at a time. The    full list is https://atlasgo.io/guides/evaluation/advan

full list is https://atlasgo.io/guides/evaluation/advanced-topics.

| Practice | Guide |    |----------|-------|    | Production applies only reviewed and approved migrations | https://atlasgo.io/guides/reviewed-approved-migrations |

|----------|-------|    | Production applies only reviewed and approved migrations | https://atlasgo.io/guides/reviewed-approved-migrations |    | Block accidental drops in CI, with a deprecation workflow | https://atlasgo.io/guides/destruc

| Production applies only reviewed and approved migrations | https://atlasgo.io/guides/reviewed-approved-migrations |

| Block accidental drops in CI, with a deprecation workflow | https://atlasgo.io/guides/destructive-change-policy |

| Detect drift at deploy time and between deployments | https://atlasgo.io/guides/drift-detection |

| Test functions, views, triggers, and data migrations | https://atlasgo.io/testing/schema |

| Lock-safe `NOT NULL` changes on PostgreSQL | https://atlasgo.io/guides/lock-safe-not-null |

| Teams change only the objects they own | https://atlasgo.io/guides/schema-ownership |

| Roles, permissions, and row-level security as code | https://atlasgo.io/guides/security-as-code |

| Staged rollouts for database-per-tenant | https://atlasgo.io/guides/database-per-tenant/rollout |

| Stage | Read | |-------|------| | 0 | [Connect](https://atlasgo.io/guides/evaluation/connect), [Choose a workflow](https://atlasgo.io/guides/evaluation/project-structure#choose-a-workflow), [Declarative vs versioned](https://atlasgo.io/co

|-------|------| | 0 | [Connect](https://atlasgo.io/guides/evaluation/connect), [Choose a workflow](https://atlasgo.io/guides/evaluation/project-structure#choose-a-workflow), [Declarative vs versioned](https://atlasgo.io/concepts/declarativ

| 0 | [Connect](https://atlasgo.io/guides/evaluation/connect), [Choose a workflow](https://atlasgo.io/guides/evaluation/project-structure#choose-a-workflow), [Declarative vs versioned](https://atlasgo.io/concepts/declarative-vs-versioned) |

| 1 | [Verify Atlas and export your schema](https://atlasgo.io/guides/evaluation/verify-atlas), [Schema as code](https://atlasgo.io/guides/evaluation/schema-as-code), [Dev database](https://atlasgo.io/concepts/dev-database), [ORM guides](ht

| 2 | [Set up your migration workflow](https://atlasgo.io/guides/evaluation/setup-migrations), [Schema change workflow](https://atlasgo.io/guides/evaluation/developer-workflow), [Migration linting](https://atlasgo.io/versioned/lint) |

| 3 | [Database CI/CD](https://atlasgo.io/guides/evaluation/ci-cd), [Versioned CI/CD](https://atlasgo.io/versioned/setup-cicd), [Declarative CI/CD](https://atlasgo.io/declarative/setup-cicd) |

| 4 | [Deployments in Atlas Cloud](https://atlasgo.io/cloud/deployment), [Deployment guides](https://atlasgo.io/guides/deploying/intro), [Existing databases](https://atlasgo.io/versioned/apply#existing-databases) |

| 5 | [Environment promotion](https://atlasgo.io/guides/environment-promotion), [Declarative environment promotion](https://atlasgo.io/guides/environment-promotion-declarative) |

first segment names the schema: `public.audit_*`, `public.*[type=function]`, or `internal` to skip a   whole schema. - The dev database must match the target's engine version and scope (https://atlasgo.io/concepts/dev-database).

whole schema. - The dev database must match the target's engine version and scope (https://atlasgo.io/concepts/dev-database).   The wrong scope fails with `modify schema "<name>" is not allowed when migration plan is scoped to one schema`, 

- The dev database must match the target's engine version and scope (https://atlasgo.io/concepts/dev-database).

If the command is not found, ask before installing the CLI: `curl -sSf https://atlasgo.sh | sh` on macOS

If the command is not found, ask before installing the CLI: `curl -sSf https://atlasgo.sh | sh` on macOS

and Linux, or `brew install ariga/tap/atlas`. Other methods are at https://atlasgo.io/getting-started.

The URL's scope decides what Atlas sees (https://atlasgo.io/concepts/url#scope):

The table count is often enough. When the database also has views, functions, triggers, or other objects, count them by type: export the database to one file per object in a temporary directory, the same export stage 1 uses (https://atlasgo

same export stage 1 uses (https://atlasgo.io/inspect/database-to-code), and count the files.

rm -rf "$inv"

| Services share one schema | One per service, split by table | `exclude` on the envs: `["audit_*"]` with a schema-scoped URL, `["billing.audit_*"]` with a database-scoped one | | Many databases share one schema (tenants) | One for all of t

| Teams share a unit but must not change each other's tables | One, plus a lint rule | `lint { ownership "github" { ... } }` (https://atlasgo.io/guides/schema-ownership) |

Schema-scoped units can use objects in a schema no unit owns, such as extensions in `public`. Keep those objects out of every unit, and create them in each unit's dev database with a `docker` block `baseline` (stage 1, and https://atlasgo.i

objects out of every unit, and create them in each unit's dev database with a `docker` block `baseline` (stage 1, and https://atlasgo.io/concepts/dev-database#baseline-schema). New databases need them before the first unit deploys. Never pu

(stage 1, and https://atlasgo.io/concepts/dev-database#baseline-schema). New databases need them before

In both workflows, developers define the desired state of the schema as code. The difference is how changes reach a database (https://atlasgo.io/guides/evaluation/project-structure#choose-a-workflow):

changes reach a database (https://atlasgo.io/guides/evaluation/project-structure#choose-a-workflow):

Propose declarative when the project already applies a desired state without migration files, or when the user asks for it. Ask in one question that says what changes for developers, and link https://atlasgo.io/concepts/declarative-vs-versi

https://atlasgo.io/concepts/declarative-vs-versioned. Record `workflow` as `versioned` or `declarative`.

Goal: the unit's desired state lives in code and matches the database. This stage is the same for both workflows. It writes `atlas.hcl` and the desired state, and changes nothing in a database. The steps follow https://atlasgo.io/guides/eva

workflows. It writes `atlas.hcl` and the desired state, and changes nothing in a database. The steps follow https://atlasgo.io/guides/evaluation/verify-atlas and https://atlasgo.io/guides/evaluation/schema-as-code.

follow https://atlasgo.io/guides/evaluation/verify-atlas and

https://atlasgo.io/guides/evaluation/schema-as-code.

The dev database is a temporary, isolated database that Atlas uses as a sandbox: it loads the desired state and the migrations there, because every expression, default, and statement must be accepted by a real database of the same type and 

state and the migrations there, because every expression, default, and statement must be accepted by a real database of the same type and version (https://atlasgo.io/concepts/dev-database#introduction). The `docker://` driver starts it as a

real database of the same type and version (https://atlasgo.io/concepts/dev-database#introduction). The

Docker dev URLs from https://atlasgo.io/concepts/dev-database#introduction. The dev database must use the

schema there until they exist. Create them in the `baseline` of a `docker` block, which runs when the container starts, and point the envs' `dev` at it (https://atlasgo.io/concepts/dev-database#baseline-schema):

(https://atlasgo.io/concepts/dev-database#baseline-schema):

pgvector, use an image that ships them (`postgis/postgis`, `pgvector/pgvector`). Without Docker, a `dev` block points at an empty database of your own and takes the same `baseline` (https://atlasgo.io/concepts/dev-database#providing-your-ow

(https://atlasgo.io/concepts/dev-database#providing-your-own-dev-database).

[Credential-related source omitted]

token and builds the URL in `atlas.hcl`, so no password is stored (https://atlasgo.io/atlas-schema/projects#data-sources). Each method needs the database user mapped to the identity first; the linked sections list the steps.

(https://atlasgo.io/atlas-schema/projects#data-sources). Each method needs the database user mapped to

AWS RDS with IAM authentication (https://atlasgo.io/atlas-schema/projects#data-source-aws_rds_token):

(https://atlasgo.io/atlas-schema/projects#data-source-aws_rds_token):

Azure Database for PostgreSQL or MySQL with Microsoft Entra ID, using the credentials from `az login`, a managed identity, or a workload identity (https://atlasgo.io/atlas-schema/projects#data-source-azure_db_token):

(https://atlasgo.io/atlas-schema/projects#data-source-azure_db_token):

Azure SQL (SQL Server) with Microsoft Entra ID: the `fedauth` parameter of the URL picks the sign-in method (https://atlasgo.io/concepts/url, SQL Server tab):

method (https://atlasgo.io/concepts/url, SQL Server tab):

GCP Cloud SQL with IAM authentication. MySQL needs `allowCleartextPasswords` and `tls` as shown; PostgreSQL uses `sslmode=require` (https://atlasgo.io/atlas-schema/projects#data-source-gcp_cloudsql_token):

PostgreSQL uses `sslmode=require` (https://atlasgo.io/atlas-schema/projects#data-source-gcp_cloudsql_token):

A password kept in a secret store, such as AWS Secrets Manager or GCP Secret Manager (https://atlasgo.io/atlas-schema/projects#data-source-runtimevar):

(https://atlasgo.io/atlas-schema/projects#data-source-runtimevar):

For units without an ORM, the desired state is the database exported to code. Ask which language the team will edit (decision point): SQL, which most teams already know, or HCL, which has editor support and no ordering constraints (https://

team will edit (decision point): SQL, which most teams already know, or HCL, which has editor support and no ordering constraints (https://atlasgo.io/guides/evaluation/schema-as-code#what-should-you-choose). Default to SQL.

no ordering constraints (https://atlasgo.io/guides/evaluation/schema-as-code#what-should-you-choose).

Full reference: https://atlasgo.io/inspect/database-to-code.

For units with an ORM, the desired state is the models. Add the `data "external_schema"` loader from the ORM's guide (https://atlasgo.io/orms, `atlas/references/schema-sources.md`), and set `local.src` to

the ORM's guide (https://atlasgo.io/orms, `atlas/references/schema-sources.md`), and set `local.src` to

Objects the ORM cannot express (views, triggers, functions, row-level security) go in a SQL or HCL file next to the models, combined with them through `composite_schema` (https://atlasgo.io/guides/evaluation/schema-as-code#must-you-choose-o

(https://atlasgo.io/guides/evaluation/schema-as-code#must-you-choose-only-one).

Tell the user that the desired state now lives in the repository, and that both workflows start from it. Link https://atlasgo.io/guides/evaluation/schema-as-code.

Link https://atlasgo.io/guides/evaluation/schema-as-code.

Goal: the unit's workflow is set up, the user has seen a change go through it, and the project PR is open. Continue on the stage 1 branch. The steps follow https://atlasgo.io/guides/evaluation/setup-migrations and

open. Continue on the stage 1 branch. The steps follow https://atlasgo.io/guides/evaluation/setup-migrations and https://atlasgo.io/guides/evaluation/developer-workflow.

https://atlasgo.io/guides/evaluation/setup-migrations and

https://atlasgo.io/guides/evaluation/developer-workflow.

default. If the team wants to manage them as code, enable them with a `mode` block in the env's `schema` block before the baseline, and repeat the stage 1 export so the desired state includes them (https://atlasgo.io/atlas-schema/hcl#enabli

block before the baseline, and repeat the stage 1 export so the desired state includes them (https://atlasgo.io/atlas-schema/hcl#enabling-roles-and-permissions, https://atlasgo.io/guides/security-as-code).

(https://atlasgo.io/atlas-schema/hcl#enabling-roles-and-permissions,

https://atlasgo.io/guides/security-as-code).

The exported schema also refers to roles that exist on the target but not in a new dev database, such as the provider roles of a managed database. Create them in the dev database's `baseline`, so Atlas can load the schema there (https://atl

as the provider roles of a managed database. Create them in the dev database's `baseline`, so Atlas can load the schema there (https://atlasgo.io/concepts/dev-database#baseline-schema, and for managed PostgreSQL, https://atlasgo.io/guides/p

load the schema there (https://atlasgo.io/concepts/dev-database#baseline-schema, and for managed

PostgreSQL, https://atlasgo.io/guides/postgres/security-declarative#dev-database-for-cloud-environments):

instance, its roles would collide with the live ones. - Declarative units that manage passwords also set `sensitive = ALLOW`   (https://atlasgo.io/guides/postgres/security-declarative).

- Declarative units that manage passwords also set `sensitive = ALLOW`   (https://atlasgo.io/guides/postgres/security-declarative). - Use the same `mode` block and dev database in every env of the unit, so local development, CI, and

(https://atlasgo.io/guides/postgres/security-declarative).

Generate the baseline, the first migration: it captures the schema as it exists today, and every later migration is a diff on top of it (https://atlasgo.io/versioned/import#generate-a-baseline-migration).

migration is a diff on top of it (https://atlasgo.io/versioned/import#generate-a-baseline-migration).

How a database starts depends on whether it already has the schema (https://atlasgo.io/versioned/import#apply-the-baseline-migration):

(https://atlasgo.io/versioned/import#apply-the-baseline-migration):

[Credential-related source omitted]

rm -rf "$tmp"

Lint exits 1 with `DS103` (dropping a column) and `BC104` (clients using it will fail), plus a suggested fix. Explain each finding in one sentence with its code (https://atlasgo.io/lint/analyzers): CI stops a

fix. Explain each finding in one sentence with its code (https://atlasgo.io/lint/analyzers): CI stops a

The baseline is the default. Import a golang-migrate, goose, Flyway, Liquibase, or dbmate history instead only when the user asks to keep it, and only when it covers exactly this unit's schemas (https://atlasgo.io/versioned/import):

(https://atlasgo.io/versioned/import):

Every schema change from now on is: edit the desired state, then `atlas schema apply --env local` against the local database. Atlas prints the planned statements, runs the lint analyzers on them, and asks for approval (https://atlasgo.io/gu

against the local database. Atlas prints the planned statements, runs the lint analyzers on them, and asks for approval (https://atlasgo.io/guides/evaluation/developer-workflow). `--dry-run` shows the plan without applying it. On shared dat

asks for approval (https://atlasgo.io/guides/evaluation/developer-workflow). `--dry-run` shows the plan

Tell the user how a schema change works from now on, in their workflow's terms. Link https://atlasgo.io/guides/evaluation/developer-workflow.

https://atlasgo.io/guides/evaluation/developer-workflow.

| CI system | Versioned | Declarative | |-----------|-----------|-------------| | GitHub Actions | https://atlasgo.io/guides/ci-platforms/github-versioned | https://atlasgo.io/guides/ci-platforms/github-declarative |

|-----------|-----------|-------------| | GitHub Actions | https://atlasgo.io/guides/ci-platforms/github-versioned | https://atlasgo.io/guides/ci-platforms/github-declarative | | GitLab CI | https://atlasgo.io/guides/ci-platforms/gitlab-ver

| GitHub Actions | https://atlasgo.io/guides/ci-platforms/github-versioned | https://atlasgo.io/guides/ci-platforms/github-declarative |

| GitLab CI | https://atlasgo.io/guides/ci-platforms/gitlab-versioned | https://atlasgo.io/guides/ci-platforms/gitlab-declarative |

| Bitbucket Pipelines | https://atlasgo.io/guides/ci-platforms/bitbucket-versioned | https://atlasgo.io/guides/ci-platforms/bitbucket-declarative |

| CircleCI | https://atlasgo.io/guides/ci-platforms/circleci-versioned | https://atlasgo.io/guides/ci-platforms/circleci-declarative |

| Azure DevOps, code on GitHub | https://atlasgo.io/guides/ci-platforms/azure-devops-github#versioned-migrations-workflow | https://atlasgo.io/guides/ci-platforms/azure-devops-github#declarative-workflow |

| Azure DevOps, code in Azure Repos | https://atlasgo.io/guides/ci-platforms/azure-devops-repos#versioned-migrations-workflow | https://atlasgo.io/guides/ci-platforms/azure-devops-repos#declarative-workflow |

All the CI guides are listed at https://atlasgo.io/guides.

- CI system: from the scan, with its guide from the table above. Anything else, such as Jenkins or   TeamCity, installs the CLI (`curl -sSf https://atlasgo.sh | sh`), runs

TeamCity, installs the CLI (`curl -sSf https://atlasgo.sh | sh`), runs

TeamCity, installs the CLI (`curl -sSf https://atlasgo.sh | sh`), runs

[Credential-related source omitted]

If the repository already has an Atlas token secret under another name, reuse it and write that name into the workflows. When the registry repo has protected flows enabled, the bot needs the Writer role on it (https://atlasgo.io/cloud/roles

on it (https://atlasgo.io/cloud/roles-and-permissions).

[Credential-related source omitted]

generation job) installs the ORM's runtime and its Atlas provider before Atlas runs, as the ORM's    guide shows. For Django: `actions/setup-python`, then `pip install django atlas-provider-django`    (https://atlasgo.io/guides/orms/django/

guide shows. For Django: `actions/setup-python`, then `pip install django atlas-provider-django`    (https://atlasgo.io/guides/orms/django/linting). 4. Keep test steps only for tests that exist: `schema/test` when the unit has schema tests,

(https://atlasgo.io/guides/orms/django/linting).

container attached to the Atlas jobs only, with the target's version and scope, or at an empty database the runner can reach (`dev = getenv("DEV_URL")` from a CI secret, https://atlasgo.io/concepts/dev-database#providing-your-own-dev-databa

the runner can reach (`dev = getenv("DEV_URL")` from a CI secret, https://atlasgo.io/concepts/dev-database#providing-your-own-dev-database). Never add services, images, or variables at the top level of a pipeline that other jobs share.

https://atlasgo.io/concepts/dev-database#providing-your-own-dev-database). Never add services, images, or

Tell the user what CI now does on every PR and every merge. Link https://atlasgo.io/versioned/setup-cicd

(or https://atlasgo.io/declarative/setup-cicd).

phase, Fly.io's `release_command`, an ECS task before the service update), run `atlas migrate apply --env staging` there instead of the old tool, not in the container entrypoint (https://atlasgo.io/guides/deploying/fly-io). The image needs 

`atlas migrate apply --env staging` there instead of the old tool, not in the container entrypoint (https://atlasgo.io/guides/deploying/fly-io). The image needs the `atlas` binary and the unit's `atlas.hcl`. The user sets `ATLAS_TOKEN` and 

(https://atlasgo.io/guides/deploying/fly-io). The image needs the `atlas` binary and the unit's

Read the `atlas-operator` skill first (Requires): it covers the operator's install, the bot token Secret, the resource policies, and the errors a first rollout hits. The Operator must be installed in the cluster (https://atlasgo.io/integrat

bot token Secret, the resource policies, and the errors a first rollout hits. The Operator must be installed in the cluster (https://atlasgo.io/integrations/kubernetes/install). That is usually the platform team's change; ask before adding 

installed in the cluster (https://atlasgo.io/integrations/kubernetes/install).

- Health: Argo CD 2.10 and later ship health checks for `AtlasMigration` and `AtlasSchema`. Add the   custom check from https://atlasgo.io/guides/deploying/k8s-argo only on older versions. A failed

custom check from https://atlasgo.io/guides/deploying/k8s-argo only on older versions. A failed

- Declarative units use `AtlasSchema` with `schema.url: atlas://<repo>?tag=<tag>` and a review policy   (`policy.lint.review: ERROR`, `WARNING`, or `ALWAYS`). A plan that needs review waits for a human to   approve it in Atlas Cloud (https:

(`policy.lint.review: ERROR`, `WARNING`, or `ALWAYS`). A plan that needs review waits for a human to   approve it in Atlas Cloud (https://atlasgo.io/integrations/kubernetes/declarative). - Optional drift monitoring: an `AtlasDriftCheck` nex

approve it in Atlas Cloud (https://atlasgo.io/integrations/kubernetes/declarative).

- Optional drift monitoring: an `AtlasDriftCheck` next to the `AtlasMigration`, with `onDrift: Report`   first. Registry versions pushed with a tag need a dev database on the `AtlasMigration` (`devURLFrom`)   for the check to work (https://

for the check to work (https://atlasgo.io/integrations/kubernetes/versioned).

The same Atlas resources as 4.6, ordered through Kustomizations instead of sync waves: the Kustomization that holds the Atlas resource lists it under `healthChecks`, and the application's Kustomization lists that one under `dependsOn` (http

Kustomization lists that one under `dependsOn` (https://atlasgo.io/guides/deploying/k8s-flux).

Terraform plans. Use a provider `cloud` block plus `data "atlas_migration"` and `resource "atlas_migration"` reading `atlas://<repo>` (https://atlasgo.io/guides/terraform/opentaco), in the staging root module or workspace only. The

`resource "atlas_migration"` reading `atlas://<repo>` (https://atlasgo.io/guides/terraform/opentaco), in the staging root module or workspace only. The Terraform runner then needs network access to the database and the bot token. Pin the `a

(https://atlasgo.io/guides/terraform/opentaco), in the staging root module or workspace only. The

Tell the user what runs on each merge now, and where to see it (https://atlasgo.io/cloud/deployment).

Goal: production applies only the version already deployed to staging. This is environment promotion, and it builds on the earlier stages (https://atlasgo.io/guides/environment-promotion):

and it builds on the earlier stages (https://atlasgo.io/guides/environment-promotion):

To gate instead, keep `dir` unpinned and add the guide's `check "migrate_apply"` with a `deny` rule on `self.planned_migration.target_version > local.staging_version` (https://atlasgo.io/guides/environment-promotion#example-pre-execution-ch

(https://atlasgo.io/guides/environment-promotion#example-pre-execution-check-for-promotion).

Declarative units pin the desired state to staging's version (https://atlasgo.io/guides/environment-promotion-declarative):

(https://atlasgo.io/guides/environment-promotion-declarative):

Tell the user how a schema change reaches production now: pull request, CI, merge, staging, promotion. Link https://atlasgo.io/guides/environment-promotion (or the declarative guide).

Link https://atlasgo.io/guides/environment-promotion (or the declarative guide).

The Atlas Kubernetes Operator applies schema changes from Kubernetes resources (https://atlasgo.io/integrations/kubernetes). This skill covers installing it, writing its resources,

The Atlas Kubernetes Operator applies schema changes from Kubernetes resources (https://atlasgo.io/integrations/kubernetes). This skill covers installing it, writing its resources,

(https://atlasgo.io/integrations/kubernetes). This skill covers installing it, writing its resources,

(https://atlasgo.io/integrations/kubernetes). This skill covers installing it, writing its resources,

This skill is `SKILL.md` plus eleven reference files under `references/`, each served at `https://atlasgo.io/skills/atlas-operator/references/<name>`. Read a reference when the task needs it:

This skill is `SKILL.md` plus eleven reference files under `references/`, each served at `https://atlasgo.io/skills/atlas-operator/references/<name>`. Read a reference when the task needs it:

`https://atlasgo.io/skills/atlas-operator/references/<name>`. Read a reference when the task needs it:

`https://atlasgo.io/skills/atlas-operator/references/<name>`. Read a reference when the task needs it:

The `atlas` skill, installed next to this one (`../atlas/SKILL.md`). If it is missing, download https://atlasgo.io/skills/atlas/SKILL.md to `../atlas/SKILL.md` and each reference file listed in its

The `atlas` skill, installed next to this one (`../atlas/SKILL.md`). If it is missing, download https://atlasgo.io/skills/atlas/SKILL.md to `../atlas/SKILL.md` and each reference file listed in its

https://atlasgo.io/skills/atlas/SKILL.md to `../atlas/SKILL.md` and each reference file listed in its

https://atlasgo.io/skills/atlas/SKILL.md to `../atlas/SKILL.md` and each reference file listed in its

- Operator overview: https://atlasgo.io/integrations/kubernetes

- Operator overview: https://atlasgo.io/integrations/kubernetes

- Quickstarts: https://atlasgo.io/integrations/kubernetes/quickstart,

- Quickstarts: https://atlasgo.io/integrations/kubernetes/quickstart,

https://atlasgo.io/integrations/kubernetes/versioned-quickstart

https://atlasgo.io/integrations/kubernetes/versioned-quickstart

- Installation: https://atlasgo.io/integrations/kubernetes/install

- Installation: https://atlasgo.io/integrations/kubernetes/install

- Resource references: https://atlasgo.io/integrations/kubernetes/declarative,

- Resource references: https://atlasgo.io/integrations/kubernetes/declarative,

https://atlasgo.io/integrations/kubernetes/versioned

https://atlasgo.io/integrations/kubernetes/versioned

- Approvals: https://atlasgo.io/integrations/kubernetes/pre-approval,

- Approvals: https://atlasgo.io/integrations/kubernetes/pre-approval,

https://atlasgo.io/integrations/kubernetes/ad-hoc-approval

https://atlasgo.io/integrations/kubernetes/ad-hoc-approval

- Custom configuration: https://atlasgo.io/integrations/kubernetes/project-configuration

- Custom configuration: https://atlasgo.io/integrations/kubernetes/project-configuration

- GitOps: https://atlasgo.io/guides/deploying/k8s-argo, https://atlasgo.io/guides/deploying/k8s-flux

- GitOps: https://atlasgo.io/guides/deploying/k8s-argo, https://atlasgo.io/guides/deploying/k8s-flux

- Security scans: https://atlasgo.io/guides/security-scan/kubernetes

- Security scans: https://atlasgo.io/guides/security-scan/kubernetes

configuration to it: data sources such as `composite_schema`, `external_schema`, `aws_rds_token`, and `gcp_cloudsql_token`, variables, and env settings (https://atlasgo.io/integrations/kubernetes/project-configuration).

(https://atlasgo.io/integrations/kubernetes/project-configuration).

Every resource needs the URL of its target database, and Atlas Pro features need an Atlas Cloud bot token (https://atlasgo.io/integrations/kubernetes/declarative#credentials). Both live in Kubernetes Secrets.

(https://atlasgo.io/integrations/kubernetes/declarative#credentials). Both live in Kubernetes Secrets.

name, such as `postgres.default` or `mysql.app`: a short name resolves in the operator's namespace, and   `localhost` is the operator itself. - Special characters in the password must be URL-encoded (https://atlasgo.io/faq/url-special-chars

`localhost` is the operator itself. - Special characters in the password must be URL-encoded (https://atlasgo.io/faq/url-special-chars). - A Secret key that does not exist reads as an empty URL. The error then names an empty driver, such as

- Special characters in the password must be URL-encoded (https://atlasgo.io/faq/url-special-chars).

The URL decides what Atlas manages (https://atlasgo.io/concepts/url#scope):

The operator runs in the cluster and authenticates with a bot token, not with a user's `atlas login` session (https://atlasgo.io/cloud/bots). A user without an Atlas account starts a free trial with

session (https://atlasgo.io/cloud/bots). A user without an Atlas account starts a free trial with

- The operator pod opens the connections, not the dev database pod. A cloud identity, such as an IAM   role or a workload identity, belongs to the operator's service account, which the chart's values   configure (https://github.com/ariga/at

role or a workload identity, belongs to the operator's service account, which the chart's values   configure (https://github.com/ariga/atlas-operator/blob/master/charts/atlas-operator/values.yaml). - For Azure SQL, Atlas reads the identity 

configure (https://github.com/ariga/atlas-operator/blob/master/charts/atlas-operator/values.yaml).

- For Azure SQL, Atlas reads the identity through the `fedauth` parameter, for example   `azuresql://<instance>.database.windows.net?fedauth=ActiveDirectoryDefault&database=master`   (https://atlasgo.io/concepts/url).

(https://atlasgo.io/concepts/url).

An `AtlasSchema` holds the desired state of a database. The operator compares it with the database, plans the `CREATE`, `ALTER`, and `DROP` statements between them, and applies them (https://atlasgo.io/integrations/kubernetes/declarative). 

the `CREATE`, `ALTER`, and `DROP` statements between them, and applies them (https://atlasgo.io/integrations/kubernetes/declarative). It acts when the resource changes, not when the database does.

(https://atlasgo.io/integrations/kubernetes/declarative). It acts when the resource changes, not when the

`cloud.repo` for an inline or ConfigMap schema. A plan matches a transition from one state to another, not a database, so one approved plan serves every database in the same state (https://atlasgo.io/faq/multi-db-plan-approve).

(https://atlasgo.io/faq/multi-db-plan-approve).

`ariga/atlas-action/schema/plan@v1` on the pull request, and `schema/plan/approve@v1` and `schema/push@v1` on merge. The push tags the schema with the merge commit's SHA, the tag to put in `schema.url` (https://atlasgo.io/integrations/kuber

`schema.url` (https://atlasgo.io/integrations/kubernetes/pre-approval).

`atlas schema plan rm --url <url>`.

For an inline schema, create a repository in Atlas Cloud (a declarative workflow repository) and name it in `cloud.repo` (https://atlasgo.io/integrations/kubernetes/ad-hoc-approval):

in `cloud.repo` (https://atlasgo.io/integrations/kubernetes/ad-hoc-approval):

Atlas computes every plan on a dev database, an empty database it can change freely (https://atlasgo.io/concepts/dev-database). The operator creates one for each resource, unless the

(https://atlasgo.io/concepts/dev-database). The operator creates one for each resource, unless the

- The dev database must be empty and used by nothing else: Atlas changes and cleans it on every run. A   database with tables fails with `connected database is not clean`   (https://atlasgo.io/faq/migrate-diff-clean).

database with tables fails with `connected database is not clean`   (https://atlasgo.io/faq/migrate-diff-clean). - Its scope matches the target's: a schema-scoped target needs a schema-scoped dev URL, and a

(https://atlasgo.io/faq/migrate-diff-clean).

`cannot diff a database connection with a schema "<name>"`, or plans the wrong changes. - It runs the target's engine version, with the extensions and settings the target has. For extension   version errors, see https://atlasgo.io/faq/exten

version errors, see https://atlasgo.io/faq/extension-version-mismatch.

Since v0.7.52, `devDB.metadata` adds labels and annotations to the dev database pod, without a custom pod spec or a `devURL` (https://atlasgo.io/changelog/operator-dev-db-pod-metadata):

(https://atlasgo.io/changelog/operator-dev-db-pod-metadata):

change. The operator does not re-check a database between deployments on its own. Two features detect drift for an `AtlasMigration`, both with Atlas Pro (https://atlasgo.io/integrations/kubernetes/versioned#drift-detection):

(https://atlasgo.io/integrations/kubernetes/versioned#drift-detection):

The operator applies what the manifest names. A deployment is a change to the manifest, which a GitOps tool syncs to the cluster: Argo CD (https://atlasgo.io/guides/deploying/k8s-argo), Flux

tool syncs to the cluster: Argo CD (https://atlasgo.io/guides/deploying/k8s-argo), Flux

(https://atlasgo.io/guides/deploying/k8s-flux), or a plain `kubectl apply`. This reference also covers

For an `AtlasMigration` on GitHub Actions, `ariga/atlas-action/migrate/push@v1` tags the push with the commit SHA by default, and also moves `latest`. It needs a dev database: a service container in the job, as in https://atlasgo.io/integra

commit SHA by default, and also moves `latest`. It needs a dev database: a service container in the job, as in https://atlasgo.io/integrations/github-actions#arigaatlas-actionmigratepush. Then two steps write the tag into the manifest and c

as in https://atlasgo.io/integrations/github-actions#arigaatlas-actionmigratepush. Then two steps write

and drop or rename only after no running version uses the object (expand and contract).   `atlas migrate lint` reports backward-incompatible changes in CI   (https://atlasgo.io/lint/analyzers#backward-incompatible-changes); move such a chan

`atlas migrate lint` reports backward-incompatible changes in CI   (https://atlasgo.io/lint/analyzers#backward-incompatible-changes); move such a change to a later   release.

(https://atlasgo.io/lint/analyzers#backward-incompatible-changes); move such a change to a later

Octopus deploys to Argo CD by committing to the Git repository that an Argo CD application syncs (https://octopus.com/docs/argo-cd/steps):

(https://octopus.com/docs/argo-cd/steps):

Crossplane installs the chart with provider-helm, and wraps the Atlas resources in provider-kubernetes `Object`s, whose service account needs RBAC on the Atlas kinds (https://atlasgo.io/guides/deploying/crossplane):

(https://atlasgo.io/guides/deploying/crossplane):

Running `atlas migrate apply` in a Helm hook Job or an init container is deprecated (https://atlasgo.io/guides/deploying/helm). Neither can tell an upgrade from a rollback, and an older

(https://atlasgo.io/guides/deploying/helm). Neither can tell an upgrade from a rollback, and an older

The operator installs with Helm from an OCI registry (https://atlasgo.io/integrations/kubernetes/install). It adds the Atlas resource kinds to the cluster,

(https://atlasgo.io/integrations/kubernetes/install). It adds the Atlas resource kinds to the cluster,

[Credential-related source omitted]

`.atlas` on disk. The cached grant keeps Atlas Pro features working for some time when Atlas Cloud is unreachable, so deployments in the cluster do not depend on Atlas Cloud being up (https://atlasgo.io/cloud/bots#offline-access). Without a

unreachable, so deployments in the cluster do not depend on Atlas Cloud being up (https://atlasgo.io/cloud/bots#offline-access). Without a volume, the cache is lost when the operator pod is replaced, and a pod that starts while Atlas Cloud 

(https://atlasgo.io/cloud/bots#offline-access). Without a volume, the cache is lost when the operator pod

production (https://atlasgo.io/integrations/kubernetes/install#persisting-the-atlas-grant-cache):

To connect with client certificates (https://atlasgo.io/guides/deploying/k8s-operator-certs), store

Since v0.8.0, an `AtlasSecurityScan` runs `atlas security scan` against a database on a schedule, and after an `AtlasSchema` or `AtlasMigration` listed in its `triggers` applies a new version (https://atlasgo.io/guides/security-scan/kuberne

after an `AtlasSchema` or `AtlasMigration` listed in its `triggers` applies a new version (https://atlasgo.io/guides/security-scan/kubernetes). It grades the findings, known vulnerabilities in the database's extensions, against a policy, an

(https://atlasgo.io/guides/security-scan/kubernetes). It grades the findings, known vulnerabilities in

1. Validate the desired state: `atlas schema validate --env local`. 2. Test the logic it holds: `atlas schema test --env local` runs `test "schema"` cases for functions,    views, triggers, and checks (https://atlasgo.io/testing/schema).

2. Test the logic it holds: `atlas schema test --env local` runs `test "schema"` cases for functions,    views, triggers, and checks (https://atlasgo.io/testing/schema). 3. Review the plan from the deployed version, as the operator will com

views, triggers, and checks (https://atlasgo.io/testing/schema).

2. Lint the new files: `atlas migrate lint --env local --latest 1`, in CI on every pull request. 3. Test data migrations with seeded rows: `atlas migrate test --env local`    (https://atlasgo.io/testing/migrate).

3. Test data migrations with seeded rows: `atlas migrate test --env local`    (https://atlasgo.io/testing/migrate). 4. Preview what a database will run: `atlas migrate apply --dry-run` against a staging database, or a

(https://atlasgo.io/testing/migrate).

Try a new operator version, chart values, or policies in a throwaway cluster first, as the quickstarts do (https://atlasgo.io/integrations/kubernetes/quickstart): a local cluster, a database in a Deployment, and

(https://atlasgo.io/integrations/kubernetes/quickstart): a local cluster, a database in a Deployment, and

| `multiple schema plans found: <urls>` | Several plans match the same change | Remove the extras with `atlas schema plan rm --url <url>` |

An `AtlasMigration` applies the pending files of a migration directory, in order (https://atlasgo.io/integrations/kubernetes/versioned). A history table records what ran, so each

(https://atlasgo.io/integrations/kubernetes/versioned). A history table records what ran, so each

A database that already has a schema needs a baseline, a migration file that describes the existing schema and is marked applied instead of run (https://atlasgo.io/versioned/apply#existing-databases):

schema and is marked applied instead of run (https://atlasgo.io/versioned/apply#existing-databases):

- `execOrder` sets how files apply when the history and the directory disagree on order: `linear` (the   default), `linear-skip`, or `non-linear` (https://atlasgo.io/faq/out-of-order-migrations).

default), `linear-skip`, or `non-linear` (https://atlasgo.io/faq/out-of-order-migrations).

- Registry directory: the directory's approval policy in Atlas Cloud decides who signs off. Turn on   Protected Flows in the directory's settings and require approval for `atlas migrate down`   (https://atlasgo.io/versioned/down). The opera

Protected Flows in the directory's settings and require approval for `atlas migrate down`   (https://atlasgo.io/versioned/down). The operator plans the revert and waits, with   `ApprovalPending: plan approval pending, review here: <link>`; 

(https://atlasgo.io/versioned/down). The operator plans the revert and waits, with

This skill is `SKILL.md` plus seven reference files under `references/`, each served at `https://atlasgo.io/skills/atlas-oracle/references/<name>`. Read a reference when the task needs it:

`https://atlasgo.io/skills/atlas-oracle/references/<name>`. Read a reference when the task needs it:

The `atlas` skill, installed next to this one (`../atlas/SKILL.md`). If it is missing, download https://atlasgo.io/skills/atlas/SKILL.md to `../atlas/SKILL.md` and each reference file listed in its

https://atlasgo.io/skills/atlas/SKILL.md to `../atlas/SKILL.md` and each reference file listed in its

1. The Oracle driver ships in the Oracle build of Atlas and needs a login. If a command fails with    `The oracle driver is available only as custom build`, install that build:    `curl -sSf https://atlasgo.sh | ATLAS_FLAVOR="oracle" sh`, o

`The oracle driver is available only as custom build`, install that build:    `curl -sSf https://atlasgo.sh | ATLAS_FLAVOR="oracle" sh`, or use the `arigaio/atlas:latest-extended`    image. Check the login with `atlas whoami`. If it shows n

`curl -sSf https://atlasgo.sh | ATLAS_FLAVOR="oracle" sh`, or use the `arigaio/atlas:latest-extended`

|----------|--------| | A local Oracle database to apply migrations to | `atlas tool docker --url "docker://oracle/free:latest-lite" --name my-ora` prints its URL; `atlas tool docker kill --name my-ora` stops it (`references/dev-database.md

| A local Oracle database to apply migrations to | `atlas tool docker --url "docker://oracle/free:latest-lite" --name my-ora` prints its URL; `atlas tool docker kill --name my-ora` stops it (`references/dev-database.md`) | | `The oracle dri

| `The oracle driver is available only as custom build`, or `Error: timeout:` with that text | Install the Oracle build: `curl -sSf https://atlasgo.sh \| ATLAS_FLAVOR="oracle" sh` (Rule 1) |

- Oracle HCL reference: https://atlasgo.io/hcl/oracle

- Oracle guides: https://atlasgo.io/guides/oracle/automatic-migrations,

https://atlasgo.io/guides/oracle/vector

- Security: https://atlasgo.io/guides/oracle/security-declarative,

https://atlasgo.io/guides/oracle/security-versioned

- Dev database: https://atlasgo.io/concepts/dev-database

- Lint checks: https://atlasgo.io/lint/analyzers

- Oracle SQL Language Reference: https://docs.oracle.com/en/database/oracle/oracle-database/26/sqlrf/

- Guides for each database: https://atlasgo.io/databases

no analyzer covers a check, or the user states a convention, write a custom rule in Atlas's HCL rule language. A rule can check any attribute of any object Atlas inspects, and `atlas schema lint` and `atlas migrate lint` enforce it on every

language. A rule can check any attribute of any object Atlas inspects, and `atlas schema lint` and `atlas migrate lint` enforce it on every change (https://atlasgo.io/lint/rules). Lint needs `atlas login`. If `atlas whoami` shows no login, 

`atlas migrate lint` enforce it on every change (https://atlasgo.io/lint/rules). Lint needs

Rules live in `.rule.hcl` files. The language reference is https://atlasgo.io/hcl/rule.

Oracle objects expose the attributes common to every driver (https://atlasgo.io/hcl/rule#predicate). Driver-specific ones from other databases are rejected, such as

(https://atlasgo.io/hcl/rule#predicate). Driver-specific ones from other databases are rejected, such as

Foreign-key columns that lead an index. Without one, updating a parent key or deleting a parent row locks the whole child table, and Oracle's guidance is to index foreign keys (https://docs.oracle.com/en/database/oracle/oracle-database/26/c

locks the whole child table, and Oracle's guidance is to index foreign keys (https://docs.oracle.com/en/database/oracle/oracle-database/26/cncpt/data-concurrency-and-consistency.html). An index, a unique constraint, or the primary key cover

(https://docs.oracle.com/en/database/oracle/oracle-database/26/cncpt/data-concurrency-and-consistency.html).

The docs have more, such as comments on PII columns, foreign keys that reference primary keys with `ON DELETE CASCADE`, naming conventions, and audit tables (https://atlasgo.io/lint/rules#examples).

`ON DELETE CASCADE`, naming conventions, and audit tables (https://atlasgo.io/lint/rules#examples).

Add the rule files to `atlas.hcl`, globally or inside an env (https://atlasgo.io/lint/rules):

The dev database is a temporary database Atlas uses to load the desired state, replay migrations, and compute plans (https://atlasgo.io/concepts/dev-database). For Oracle it must match the target's scope,

compute plans (https://atlasgo.io/concepts/dev-database). For Oracle it must match the target's scope,

In Oracle, a schema is a user: the objects that one user owns. The URL's `mode` parameter decides what Atlas covers (https://atlasgo.io/concepts/url#scope):

Atlas covers (https://atlasgo.io/concepts/url#scope):

- The path is the service name of a pluggable database (PDB), such as `FREEPDB1`. Connect to the PDB's   service, not to the root container   (https://docs.oracle.com/en/database/oracle/oracle-database/26/multi/administering-pdbs-with-sql-p

service, not to the root container   (https://docs.oracle.com/en/database/oracle/oracle-database/26/multi/administering-pdbs-with-sql-plus.html). - At schema scope, Atlas manages the schema of the user it connects as, so connect as the sche

(https://docs.oracle.com/en/database/oracle/oracle-database/26/multi/administering-pdbs-with-sql-plus.html).

The `docker://` driver starts a fresh container for each run (https://atlasgo.io/concepts/dev-database):

holds 19c and 21c. Pulling an enterprise image needs an Oracle account, accepting the license in the   registry, and `docker login container-registry.oracle.com`   (https://container-registry.oracle.com/ords/ocr/ba/database/free).

registry, and `docker login container-registry.oracle.com`   (https://container-registry.oracle.com/ords/ocr/ba/database/free). - Atlas connects to the `FREEPDB1` database as `PDBADMIN`.

(https://container-registry.oracle.com/ords/ocr/ba/database/free).

The lite image removes features to stay small, such as XML DB, so it has no `XMLTYPE`, and Oracle Text lexers other than `BASIC_LEXER` (https://container-registry.oracle.com/ords/ocr/ba/database/free). It

lexers other than `BASIC_LEXER` (https://container-registry.oracle.com/ords/ocr/ba/database/free). It

`atlas tool docker` creates a named container from a `docker://` URL and prints its connection URL. It cleans the database if it is not empty, so never run it against a container that holds data to keep (https://atlasgo.io/cli-reference#atl

(https://atlasgo.io/cli-reference#atlas-tool-docker). Use it for a local database to apply migrations to:

[Credential-related source omitted]

A `docker "oracle"` block configures the dev container (https://atlasgo.io/hcl/config#docker.oracle).

- Release. The Free image is Oracle AI Database 26ai, release 23.26, which replaced 23ai through a release   update (https://docs.oracle.com/en/database/oracle/oracle-database/26/nfcoa/). Features by release:

update (https://docs.oracle.com/en/database/oracle/oracle-database/26/nfcoa/). Features by release:

- `MAX_STRING_SIZE`. `STANDARD`, the default and the Free image's setting, limits `VARCHAR2` to 4000   bytes; `EXTENDED` allows 32767   (https://docs.oracle.com/en/database/oracle/oracle-database/26/refrn/MAX_STRING_SIZE.html). A

bytes; `EXTENDED` allows 32767   (https://docs.oracle.com/en/database/oracle/oracle-database/26/refrn/MAX_STRING_SIZE.html). A   `VARCHAR2(8000)` column that an `EXTENDED` target accepts fails on a `STANDARD` dev database with

(https://docs.oracle.com/en/database/oracle/oracle-database/26/refrn/MAX_STRING_SIZE.html). A

for multibyte text. Write `VARCHAR2(100 CHAR)` for a character length (`references/hcl.md`). - Free limits each instance to 2 CPUs, 2 GB of memory, and 12 GB of user data   (https://docs.oracle.com/en/database/oracle/oracle-database/26/xein

- Free limits each instance to 2 CPUs, 2 GB of memory, and 12 GB of user data   (https://docs.oracle.com/en/database/oracle/oracle-database/26/xeinl/licensing-restrictions.html),   enough for a dev database.

(https://docs.oracle.com/en/database/oracle/oracle-database/26/xeinl/licensing-restrictions.html),

Connect Atlas as a dedicated user that owns the application schema, not as an administrator (https://atlasgo.io/guides/oracle/security-declarative). It needs these, granted once by an

(https://atlasgo.io/guides/oracle/security-declarative). It needs these, granted once by an

- Each `CREATE` privilege covers one object type in the user's own schema; `CREATE PROCEDURE` covers   functions and packages too. Add `CREATE MATERIALIZED VIEW`, `CREATE DATABASE LINK`, or `CREATE ROLE` if   the schema has them (https://do

functions and packages too. Add `CREATE MATERIALIZED VIEW`, `CREATE DATABASE LINK`, or `CREATE ROLE` if   the schema has them (https://docs.oracle.com/en/database/oracle/oracle-database/26/sqlrf/GRANT.html). - `RESOURCE` does not include `U

the schema has them (https://docs.oracle.com/en/database/oracle/oracle-database/26/sqlrf/GRANT.html).

- `RESOURCE` does not include `UNLIMITED TABLESPACE` since 12c, so give the user a quota. On 19c,   `RESOURCE` also lacks `CREATE VIEW` and `CREATE SYNONYM`   (https://docs.oracle.com/en/database/oracle/oracle-database/19/dbseg/predefined-r

`RESOURCE` also lacks `CREATE VIEW` and `CREATE SYNONYM`   (https://docs.oracle.com/en/database/oracle/oracle-database/19/dbseg/predefined-roles-oracle-database-installation.html). - A missing grant fails with one of these:

(https://docs.oracle.com/en/database/oracle/oracle-database/19/dbseg/predefined-roles-oracle-database-installation.html).

first row then fails with `ORA-01950`. - Database scope needs privileges on other users' objects, listed in the Oracle tab of   https://atlasgo.io/concepts/url.

https://atlasgo.io/concepts/url.

- Amazon RDS for Oracle: the master user is not `SYSDBA`, and grants on `SYS` objects go through an RDS   procedure, which grants only privileges the master user holds   (https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/Appendix.Oracl

procedure, which grants only privileges the master user holds   (https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/Appendix.Oracle.CommonDBATasks.TransferPrivileges.html).   Run it once from a SQL client, not from a migration file (`re

(https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/Appendix.Oracle.CommonDBATasks.TransferPrivileges.html).

- Oracle Autonomous Database: connect as `ADMIN`, which is not `SYSDBA`, or as a user it creates, through   a predefined service such as `<db>_low` or `<db>_tp`   (https://docs.oracle.com/en/cloud/paas/autonomous-database/serverless/adbsb/p

a predefined service such as `<db>_low` or `<db>_tp`   (https://docs.oracle.com/en/cloud/paas/autonomous-database/serverless/adbsb/predefined-database-services-names.html).   Mutual TLS, the default on port 1522, needs the wallet: `?ssl=tru

(https://docs.oracle.com/en/cloud/paas/autonomous-database/serverless/adbsb/predefined-database-services-names.html).

Mutual TLS, the default on port 1522, needs the wallet: `?ssl=true&wallet=/path/to/wallet`. TLS without   a wallet needs an access control list or a private endpoint   (https://docs.oracle.com/en/cloud/paas/autonomous-database/serverless/ad

a wallet needs an access control list or a private endpoint   (https://docs.oracle.com/en/cloud/paas/autonomous-database/serverless/adbsb/connect-introduction.html). - Autonomous Database ignores tablespace and storage clauses in `CREATE TA

(https://docs.oracle.com/en/cloud/paas/autonomous-database/serverless/adbsb/connect-introduction.html).

- Autonomous Database ignores tablespace and storage clauses in `CREATE TABLE`, and refuses tablespace   changes (https://docs.oracle.com/en/cloud/paas/autonomous-database/serverless/adbsb/autonomous-sql-commands.html).   It uses `MAX_STRIN

changes (https://docs.oracle.com/en/cloud/paas/autonomous-database/serverless/adbsb/autonomous-sql-commands.html).

- Write the URL as `oracle://user:pass@host:1521/service_name`. The service names a PDB. - Percent-encode special characters in passwords, or build the URL with `urlescape`   (https://atlasgo.io/faq/url-special-chars).

- Percent-encode special characters in passwords, or build the URL with `urlescape`   (https://atlasgo.io/faq/url-special-chars). - TLS options go in the query: `?ssl=true` turns TLS on, and `wallet` points at a wallet directory for

(https://atlasgo.io/faq/url-special-chars).

| Error | Cause | Fix | |-------|-------|-----| | `The oracle driver is available only as custom build`, or `Error: timeout: ...` with that text on a `docker://` dev URL | The installed Atlas has no Oracle driver | Install the Oracle build:

|-------|-------|-----| | `The oracle driver is available only as custom build`, or `Error: timeout: ...` with that text on a `docker://` dev URL | The installed Atlas has no Oracle driver | Install the Oracle build: `curl -sSf https://atla

| `The oracle driver is available only as custom build`, or `Error: timeout: ...` with that text on a `docker://` dev URL | The installed Atlas has no Oracle driver | Install the Oracle build: `curl -sSf https://atlasgo.sh \| ATLAS_FLAVOR="

The rules of the HCL schema language that matter on Oracle, and the places where HCL behaves differently from SQL. The language: https://atlasgo.io/atlas-schema/hcl. Every Oracle block and attribute:

from SQL. The language: https://atlasgo.io/atlas-schema/hcl. Every Oracle block and attribute:

https://atlasgo.io/hcl/oracle. The Oracle driver needs `atlas login`. If `atlas whoami` shows no login,

- Name Oracle schema files `*.oc.hcl`, test files `*.test.hcl`, and rule files `*.rule.hcl`. The Atlas   editor plugins recognize `.oc.hcl` for Oracle   (https://atlasgo.io/atlas-schema/hcl#file-naming-for-editor-support).

editor plugins recognize `.oc.hcl` for Oracle   (https://atlasgo.io/atlas-schema/hcl#file-naming-for-editor-support). - A `schema` block is an Oracle user. At schema scope, its name must be the user in the URL, in

(https://atlasgo.io/atlas-schema/hcl#file-naming-for-editor-support).

several `schema` blocks needs database scope (`references/dev-database.md`). - When environments use different owners, such as `APP_DEV` and `APP_PROD`, set the name from an input   variable (https://atlasgo.io/atlas-schema/input-variables)

variable (https://atlasgo.io/atlas-schema/input-variables):

Rows are declared next to the table in a `data` block, and applied only when the env enables data sync (https://atlasgo.io/atlas-schema/hcl#preserving-explicit-ids):

(https://atlasgo.io/atlas-schema/hcl#preserving-explicit-ids):

Input variables work as in any Atlas HCL schema (https://atlasgo.io/atlas-schema/input-variables). A

Oracle has no analyzers of its own, like the `MY` and `PG` checks of MySQL and PostgreSQL. The generic ones run (https://atlasgo.io/lint/analyzers):

ones run (https://atlasgo.io/lint/analyzers):

- A `statement` rule that flags indexes built without `ONLINE`   (https://atlasgo.io/lint/analyzers#statement-rules). Rules run in order, and the first match wins:

(https://atlasgo.io/lint/analyzers#statement-rules). Rules run in order, and the first match wins:

A statement opts out of named checks with a directive on the line before it (https://atlasgo.io/versioned/lint#nolint-directive):

(https://atlasgo.io/versioned/lint#nolint-directive):

Oracle commits the open transaction before and after every DDL statement (https://docs.oracle.com/en/database/oracle/oracle-database/26/sqlrf/COMMIT.html). A migration file or a

(https://docs.oracle.com/en/database/oracle/oracle-database/26/sqlrf/COMMIT.html). A migration file or a

file. Keep data changes in files of their own, apart from DDL. - `atlas migrate down` reverts applied files on Oracle. It computes the revert on the dev database and   checks that a column it drops holds no data (https://atlasgo.io/versione

- `atlas migrate down` reverts applied files on Oracle. It computes the revert on the dev database and   checks that a column it drops holds no data (https://atlasgo.io/versioned/down). - `atlas migrate set <version>` updates the revisions 

checks that a column it drops holds no data (https://atlasgo.io/versioned/down).

- In a hand-written file, end each `CREATE [OR REPLACE]` of a function, procedure, trigger, type, package,   or package body with `END;;`, or with a `/` on a line of its own, as in SQL*Plus   (https://docs.oracle.com/en/database/oracle/orac

(https://docs.oracle.com/en/database/oracle/oracle-database/26/sqpug/SQL-Plus-basics.html):

- After a deployment that changes tables, views, or PL/SQL that other code depends on, recompile the   schema: `CALL DBMS_UTILITY.COMPILE_SCHEMA(schema => 'APP', compile_all => FALSE);`   (https://docs.oracle.com/en/database/oracle/oracle-d

(https://docs.oracle.com/en/database/oracle/oracle-database/26/admin/managing-schema-objects.html).

- `migrate apply` and `schema apply` hold a `DBMS_LOCK` lock for the run, which needs   `EXECUTE ON SYS.DBMS_LOCK`. `--lock-timeout` waits 10 seconds by default; `--skip-lock` skips the lock   (https://atlasgo.io/versioned/apply#controlling

`EXECUTE ON SYS.DBMS_LOCK`. `--lock-timeout` waits 10 seconds by default; `--skip-lock` skips the lock   (https://atlasgo.io/versioned/apply#controlling-advisory-locks). `migrate diff` and `migrate lint` take   the lock on the dev database.

(https://atlasgo.io/versioned/apply#controlling-advisory-locks). `migrate diff` and `migrate lint` take

the lock on the dev database. - `DDL_LOCK_TIMEOUT` is 0 by default, so DDL on a table with an open transaction fails at once   (https://docs.oracle.com/en/database/oracle/oracle-database/26/refrn/DDL_LOCK_TIMEOUT.html):

(https://docs.oracle.com/en/database/oracle/oracle-database/26/refrn/DDL_LOCK_TIMEOUT.html):

or for every file, with a hook in `atlas.hcl` (https://atlasgo.io/versioned/apply#migration-hooks):

- Atlas plans `CREATE INDEX` without `ONLINE`, which blocks writes for the whole build. On a populated   table, write the index by hand with `ONLINE`, which lets DML continue   (https://docs.oracle.com/en/database/oracle/oracle-database/26/

(https://docs.oracle.com/en/database/oracle/oracle-database/26/sqlrf/CREATE-INDEX.html):

- `ONLINE` operations are included in Enterprise Edition and Free, not in Standard Edition 2     (https://docs.oracle.com/en/database/oracle/oracle-database/26/dblic/Licensing-Information.html).

(https://docs.oracle.com/en/database/oracle/oracle-database/26/dblic/Licensing-Information.html).

- Add foreign keys and checks to populated tables without validating them, then validate in a later   file. Validating an `ENABLE NOVALIDATE` constraint blocks neither reads nor writes   (https://docs.oracle.com/en/database/oracle/oracle-da

(https://docs.oracle.com/en/database/oracle/oracle-database/26/sqlrf/constraint.html):

- With supplemental logging on, as GoldenGate and logical standby require, Oracle runs `ADD COLUMN`,   `ENABLE NOVALIDATE`, and `VALIDATE` as blocking DDL   (https://docs.oracle.com/en/database/oracle/oracle-database/26/sqlrf/Automatic-and-

`ENABLE NOVALIDATE`, and `VALIDATE` as blocking DDL   (https://docs.oracle.com/en/database/oracle/oracle-database/26/sqlrf/Automatic-and-Manual-Locking-Mechanisms-During-SQL-Operations.html). - Adding a column with a `DEFAULT` stores the de

(https://docs.oracle.com/en/database/oracle/oracle-database/26/sqlrf/Automatic-and-Manual-Locking-Mechanisms-During-SQL-Operations.html).

- Adding a column with a `DEFAULT` stores the default as metadata, without rewriting rows, for nullable   and `NOT NULL` columns alike, except on index-organized, temporary, and some other tables   (https://docs.oracle.com/en/database/oracl

and `NOT NULL` columns alike, except on index-organized, temporary, and some other tables   (https://docs.oracle.com/en/database/oracle/oracle-database/26/sqlrf/ALTER-TABLE.html). - A column's size or precision can always grow. Changing its

(https://docs.oracle.com/en/database/oracle/oracle-database/26/sqlrf/ALTER-TABLE.html).

data, and drop the old one in a later file. - Changes that rebuild a large table online use `DBMS_REDEFINITION`   (https://docs.oracle.com/en/database/oracle/oracle-database/26/admin/managing-tables.html), and

- Changes that rebuild a large table online use `DBMS_REDEFINITION`   (https://docs.oracle.com/en/database/oracle/oracle-database/26/admin/managing-tables.html), and   upgrades of PL/SQL in use without downtime use edition-based redefinitio

(https://docs.oracle.com/en/database/oracle/oracle-database/26/admin/managing-tables.html), and

upgrades of PL/SQL in use without downtime use edition-based redefinition   (https://docs.oracle.com/en/database/oracle/oracle-database/26/adfns/editions.html). Run both outside   Atlas, then record the file with `atlas migrate set <version

(https://docs.oracle.com/en/database/oracle/oracle-database/26/adfns/editions.html). Run both outside

A schema that has objects but no revisions table is refused until it gets a baseline, the first migration recorded as applied without running (https://atlasgo.io/versioned/apply#existing-databases).

migration recorded as applied without running (https://atlasgo.io/versioned/apply#existing-databases).

How Atlas models Oracle objects, and the cases where its plan differs from what a hand-written migration would do. The full attribute reference is https://atlasgo.io/hcl/oracle. HCL syntax is in

would do. The full attribute reference is https://atlasgo.io/hcl/oracle. HCL syntax is in

indexes, comments, views, sequences, functions, procedures, triggers, object types, varrays, nested tables, synonyms, database links, operators, index types, roles, and object grants (https://atlasgo.io/hcl/oracle).

(https://atlasgo.io/hcl/oracle).

- Oracle folds unquoted names to uppercase and keeps quoted names as written   (https://docs.oracle.com/en/database/oracle/oracle-database/26/sqlrf/Database-Object-Names-and-Qualifiers.html).

(https://docs.oracle.com/en/database/oracle/oracle-database/26/sqlrf/Database-Object-Names-and-Qualifiers.html).

`NUMBER`, which accepts decimals, and later plans do not report the difference. Write integers with a   precision: `NUMBER(10)`, `NUMBER(19)`, or `NUMBER(38)`. - Oracle treats `''` as `NULL` (https://docs.oracle.com/en/database/oracle/oracl

precision: `NUMBER(10)`, `NUMBER(19)`, or `NUMBER(38)`. - Oracle treats `''` as `NULL` (https://docs.oracle.com/en/database/oracle/oracle-database/26/sqlrf/Nulls.html):   - A `NOT NULL` `VARCHAR2` column rejects `''` with `ORA-01400`.

- Oracle treats `''` as `NULL` (https://docs.oracle.com/en/database/oracle/oracle-database/26/sqlrf/Nulls.html):

- `BOOLEAN` (23ai), `JSON` (21c), and `VECTOR` (23.4) exist only on those releases: on an older target,   see `references/dev-database.md`, Versions and Settings. `VECTOR` columns are covered in   https://atlasgo.io/guides/oracle/vector.

see `references/dev-database.md`, Versions and Settings. `VECTOR` columns are covered in   https://atlasgo.io/guides/oracle/vector. - `LONG` columns are deprecated and limited to one per table. Convert them to `CLOB`.

https://atlasgo.io/guides/oracle/vector.

- Declarative: declare the sequence without a start, apply it, then move it once by hand:     `ALTER SEQUENCE "INVOICE_SEQ" RESTART START WITH 50000;`     (https://docs.oracle.com/en/database/oracle/oracle-database/26/sqlrf/ALTER-SEQUENCE.h

`ALTER SEQUENCE "INVOICE_SEQ" RESTART START WITH 50000;`     (https://docs.oracle.com/en/database/oracle/oracle-database/26/sqlrf/ALTER-SEQUENCE.html). Later     plans leave it alone.

(https://docs.oracle.com/en/database/oracle/oracle-database/26/sqlrf/ALTER-SEQUENCE.html). Later

- An identity column's `start` is planned, and plans leave the identity alone once rows use it. - Identity columns take `GENERATED ALWAYS`, the default, `BY DEFAULT`, or `BY DEFAULT ON NULL`   (https://docs.oracle.com/en/database/oracle/ora

- Identity columns take `GENERATED ALWAYS`, the default, `BY DEFAULT`, or `BY DEFAULT ON NULL`   (https://docs.oracle.com/en/database/oracle/oracle-database/26/sqlrf/CREATE-TABLE.html):   - A table has at most one, and it is implicitly `NOT

(https://docs.oracle.com/en/database/oracle/oracle-database/26/sqlrf/CREATE-TABLE.html):

- Seed rows in a `data` block skip `GENERATED ALWAYS` identity values even with `preserve_ids = true`;   `BY DEFAULT` values are kept with it   (https://atlasgo.io/atlas-schema/hcl#preserving-explicit-ids).

(https://atlasgo.io/atlas-schema/hcl#preserving-explicit-ids).

row locks the whole child table, and Oracle's guidance is that "foreign keys should almost always be   indexed"   (https://docs.oracle.com/en/database/oracle/oracle-database/26/cncpt/data-concurrency-and-consistency.html).

indexed"   (https://docs.oracle.com/en/database/oracle/oracle-database/26/cncpt/data-concurrency-and-consistency.html).   Atlas creates no index on its own; enforce it with the rule in `references/custom-rules.md`.

(https://docs.oracle.com/en/database/oracle/oracle-database/26/cncpt/data-concurrency-and-consistency.html).

statement as applied. An invalid trigger fails every statement that fires it, with   `ORA-04098: trigger '...' is invalid and failed re-validation`, until it is fixed   (https://docs.oracle.com/en/database/oracle/oracle-database/26/lnpls/tr

`ORA-04098: trigger '...' is invalid and failed re-validation`, until it is fixed   (https://docs.oracle.com/en/database/oracle/oracle-database/26/lnpls/trigger-compilation-invalidation-and-recompilation.html).   A migration test that check

(https://docs.oracle.com/en/database/oracle/oracle-database/26/lnpls/trigger-compilation-invalidation-and-recompilation.html).

optional `referencing`, `when`, `follows` or `precedes`, and its body in `as`. The body reads   `:NEW` and `:OLD`, but a `when` condition writes `NEW` and `OLD` without the colon   (https://docs.oracle.com/en/database/oracle/oracle-database

`:NEW` and `:OLD`, but a `when` condition writes `NEW` and `OLD` without the colon   (https://docs.oracle.com/en/database/oracle/oracle-database/26/lnpls/CREATE-TRIGGER-statement.html). - Definer's-rights code and views run without the owne

(https://docs.oracle.com/en/database/oracle/oracle-database/26/lnpls/CREATE-TRIGGER-statement.html).

sessions running that code can fail with `ORA-04068`. After a deployment, recompile with   `UTL_RECOMP` or `DBMS_UTILITY.COMPILE_SCHEMA`   (https://docs.oracle.com/en/database/oracle/oracle-database/26/admin/managing-schema-objects.html).

(https://docs.oracle.com/en/database/oracle/oracle-database/26/admin/managing-schema-objects.html).

- `synonym` points at a table, view, sequence, function, or procedure, or a name through a   `database_link`. A `database_link` takes a `host` and its credentials; keep passwords in input   variables (https://atlasgo.io/atlas-schema/input-v

`database_link`. A `database_link` takes a `host` and its credentials; keep passwords in input   variables (https://atlasgo.io/atlas-schema/input-variables). - `operator` and `index_type` model Data Cartridge objects for domain indexes.

variables (https://atlasgo.io/atlas-schema/input-variables).

Roles, role hierarchies, and object and column grants. The guides: https://atlasgo.io/guides/oracle/security-declarative and

https://atlasgo.io/guides/oracle/security-declarative and

https://atlasgo.io/guides/oracle/security-versioned.

global authorization, or a package (a secure application role). Only `NOT IDENTIFIED` roles are   enabled at login as default roles; the others need `SET ROLE` or the package   (https://docs.oracle.com/en/database/oracle/oracle-database/26/

enabled at login as default roles; the others need `SET ROLE` or the package   (https://docs.oracle.com/en/database/oracle/oracle-database/26/sqlrf/ALTER-USER.html). - The `role` block has no `external` attribute. Every role that Oracle doe

(https://docs.oracle.com/en/database/oracle/oracle-database/26/sqlrf/ALTER-USER.html).

- The `role` block has no `external` attribute. Every role that Oracle does not maintain is in scope,   including other teams' roles, and a role the schema does not declare is planned for `DROP ROLE`. Keep   `drop_role = true` in the env's 

including other teams' roles, and a role the schema does not declare is planned for `DROP ROLE`. Keep   `drop_role = true` in the env's `skip` policy (https://atlasgo.io/versioned/diff#diff-policy). - The user Atlas connects as can grant or

`drop_role = true` in the env's `skip` policy (https://atlasgo.io/versioned/diff#diff-policy).

- Prefer `READ` to `SELECT` for read-only access: `SELECT` also allows `SELECT ... FOR UPDATE` and   `LOCK TABLE`, so a reader can lock rows (12.1.0.2 and later,   https://docs.oracle.com/en/database/oracle/oracle-database/26/sqlrf/GRANT.ht

`LOCK TABLE`, so a reader can lock rows (12.1.0.2 and later,   https://docs.oracle.com/en/database/oracle/oracle-database/26/sqlrf/GRANT.html). Changing one to the   other plans a `GRANT` and a `REVOKE`.

https://docs.oracle.com/en/database/oracle/oracle-database/26/sqlrf/GRANT.html). Changing one to the

Write schema privileges (23ai and later), such as `GRANT SELECT ANY TABLE ON SCHEMA APP TO APP_READONLY`,   and system privileges in hand-written migration files   (https://docs.oracle.com/en/database/oracle/oracle-database/26/dbseg/managin

(https://docs.oracle.com/en/database/oracle/oracle-database/26/dbseg/managing-system-privileges.html).

Oracle disables roles inside definer's-rights PL/SQL, the default for functions, procedures, packages, and triggers, and when it compiles a view (https://docs.oracle.com/en/database/oracle/oracle-database/26/dbseg/user-roles.html):

(https://docs.oracle.com/en/database/oracle/oracle-database/26/dbseg/user-roles.html):

database, and the call fails with `ORA-00904: "NO_SUCH_FN": invalid identifier`. - Triggers: seed rows, make the change that fires the trigger, and check the side effect, as above   (https://atlasgo.io/guides/testing/triggers). A row trigge

- Triggers: seed rows, make the change that fires the trigger, and check the side effect, as above   (https://atlasgo.io/guides/testing/triggers). A row trigger that reads `:NEW` needs `for = ROW`. - Views and virtual columns: seed rows and

(https://atlasgo.io/guides/testing/triggers). A row trigger that reads `:NEW` needs `for = ROW`.

- Views and virtual columns: seed rows and compare the output   (https://atlasgo.io/guides/testing/views). - Functions and procedures: normal inputs, edge cases, and error paths with `catch`

(https://atlasgo.io/guides/testing/views).

(https://atlasgo.io/guides/testing/functions, https://atlasgo.io/guides/testing/procedures).

Each case starts from an empty database. Migrate to the version before the change, seed rows, migrate to the version under test, and check the data (https://atlasgo.io/guides/testing/data-migrations):

to the version under test, and check the data (https://atlasgo.io/guides/testing/data-migrations):

commands; this skill covers the rules, edge cases, and answers that differ on PostgreSQL. PostgreSQL-compatible engines, such as CockroachDB, YugabyteDB, and Aurora DSQL, behave differently in places: follow their guides (https://atlasgo.io

commands; this skill covers the rules, edge cases, and answers that differ on PostgreSQL. PostgreSQL-compatible engines, such as CockroachDB, YugabyteDB, and Aurora DSQL, behave differently in places: follow their guides (https://atlasgo.io

commands; this skill covers the rules, edge cases, and answers that differ on PostgreSQL. PostgreSQL-compatible engines, such as CockroachDB, YugabyteDB, and Aurora DSQL, behave differently in places: follow their guides (https://atlasgo.io

places: follow their guides (https://atlasgo.io/databases).

places: follow their guides (https://atlasgo.io/databases).

places: follow their guides (https://atlasgo.io/databases).

This skill is `SKILL.md` plus seven reference files under `references/`, each served at `https://atlasgo.io/skills/atlas-postgres/references/<name>`. Read a reference when the task needs it:

This skill is `SKILL.md` plus seven reference files under `references/`, each served at `https://atlasgo.io/skills/atlas-postgres/references/<name>`. Read a reference when the task needs it:

This skill is `SKILL.md` plus seven reference files under `references/`, each served at `https://atlasgo.io/skills/atlas-postgres/references/<name>`. Read a reference when the task needs it:

`https://atlasgo.io/skills/atlas-postgres/references/<name>`. Read a reference when the task needs it:

`https://atlasgo.io/skills/atlas-postgres/references/<name>`. Read a reference when the task needs it: