If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/ariga/atlas shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across the board

• Last commit 2w ago
• 9 active contributors
• Distributed ownership (top contributor 44% of recent commits)
• Apache-2.0 licensed
• CI configured
• Tests present

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live ariga/atlas repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/ariga/atlas.

What it runs against: a local clone of ariga/atlas — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in ariga/atlas | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | Last commit ≤ 47 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of ariga/atlas. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/ariga/atlas.git
#   cd atlas
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of ariga/atlas and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "ariga/atlas(\\.git)?\\b" \\
  && ok "origin remote is ariga/atlas" \\
  || miss "origin remote is not ariga/atlas (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Apache-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Apache-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is Apache-2.0" \\
  || miss "license drift — was Apache-2.0 at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 47 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~17d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/ariga/atlas"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Atlas is a schema-as-code CLI tool that manages database migrations declaratively (like Terraform) or through versioned migration workflows. It inspects, diffs, plans, and applies schema changes across 15+ databases (PostgreSQL, MySQL, SQLite, Snowflake, CockroachDB, etc.) by comparing desired state (defined in HCL, SQL, or ORM) to actual database state, then auto-generating and executing migration plans. Monorepo structure: cmd/atlas/ contains the CLI entry point using spf13/cobra, atlasexec/ wraps the atlas package as a Go SDK (exposed in atlasexec/atlas.go, atlas_migrate.go, atlas_schema.go), testdata/ holds migration fixtures and atlas.hcl examples, and .github/workflows/ orchestrates dialect-specific CI. Core logic lives in ariga.io/atlas (parent module via replace directive).

DevOps engineers, backend developers, and database administrators who manage production databases and want infrastructure-as-code workflows for schema changes, automated migration planning, and safe schema linting without writing raw SQL migrations.

Actively maintained and production-ready. The codebase shows ~2.5M lines of Go with comprehensive CI workflows (ci-go_oss.yaml, ci-dialect_oss.yaml, ci-revisions_oss.yaml), organized test suites in atlasexec/, and recent commits visible in the go.mod replace directive pointing to v0.32.1-0.20250325101103. Multiple database dialect implementations and extensive test data across supported databases indicate stability.

Low risk for a mature schema migration tool. Dependencies are well-managed (hashicorp/hcl, spf13/cobra, lib/pq, go-sql-driver/mysql are industry-standard). Primary risk is the complexity of supporting 15+ database dialects—breaking changes to one dialect's DDL parsing could affect users. Single repository (not modular) means dialect-specific bugs can block the main CLI.

Active development on multiple fronts: CI workflows for dialect testing (MySQL, CockroachDB OSS variants), E2E tests in atlasexec/internal/e2e/ for versioned migrations and multi-tenant schemas, and SDK refinement (atlas_internal_test.go, copilot_test.go suggest recent Copilot integration or AI features). Go version recently bumped to 1.25.9.

git clone https://github.com/ariga/atlas.git
cd atlas
go build ./cmd/atlas
./atlas version

Or use the official installer: curl -sSf https://atlasgo.sh | sh or npm install -g @ariga/atlas.

Daily commands:

cd cmd/atlas
go run . version                    # Show version
go run . schema inspect -u "file://schema.sql"  # Inspect schema
go run . schema diff --from "file://current.sql" --to "file://desired.sql"  # Diff
go run . migrate diff --dir "file://migrations" --env dev  # Versioned diff

For local development: go test ./... runs the test suite.

• cmd/atlas: CLI entry point; contains cobra command definitions and main argument parsing
• atlasexec/atlas.go: Primary Go SDK interface; exposes Atlas schema inspection, diffing, and migration planning APIs
• atlasexec/atlas_migrate.go: Versioned migration workflow implementation; handles planning, linting, and applying migrations
• atlasexec/atlas_schema.go: Declarative schema workflow; implements inspect, diff, plan, apply for schema-as-code
• .github/workflows/ci-dialect_oss.yaml: Database dialect testing pipeline; ensures multi-database compatibility
• atlasexec/internal/e2e/: End-to-end test scenarios with real migration fixtures (versioned-basic, multi-tenants, schema-plan)
• go.mod: Module dependencies and version constraints; replace directive shows ariga.io/atlas core module location

For new SQL dialect: add parser grammar to ANTLR files (references atlas module), implement Inspector interface in parent atlas module. For CLI commands: edit cmd/atlas/main.go and add cobra.Command structs. For SDK/API changes: modify atlasexec/*.go (atlas.go, atlas_migrate.go, atlas_schema.go). For tests: add fixtures to atlasexec/testdata/ or atlasexec/internal/e2e/testdata/, write tests in *_test.go files.

The main atlas logic is in the parent module (ariga.io/atlas) via the replace directive in go.mod—most core diff/plan logic is not in this repo but in the parent ariga.io/atlas package. Database drivers must be explicitly imported by the CLI (lib/pq, go-sql-driver/mysql, mattn/go-sqlite3); missing a driver means that dialect won't work. Atlas requires database connectivity for inspect/diff operations—local development needs a running test database or Docker containers. HCL schema files use hashicorp/hcl syntax, not standard SQL, requiring schema conversion from existing databases first.

• Schema Diffing — Core capability of Atlas—computing DDL changes between desired and actual schemas requires deep SQL parsing and diff algorithms for each database dialect
• Declarative vs Imperative Migrations — Atlas supports both workflows: declarative (Terraform-like desired state) and imperative (versioned SQL files); understanding the trade-offs is essential for using the tool correctly
• Database Dialects / Vendor-Specific DDL — Each database (PostgreSQL, MySQL, SQLite, Snowflake, etc.) has unique constraint syntax, type systems, and DDL—Atlas must parse and generate dialect-specific SQL, visible in the 15+ supported databases
• ANTLR Grammar-Based SQL Parsing — Atlas uses ANTLR v4 to parse SQL dialects declaratively via grammar files; understanding grammar generation is key for adding new dialect support
• Schema-as-Code (HCL) — Using hashicorp/hcl/v2 to express database schemas declaratively, enabling version control, code review, and Terraform-like workflows for infrastructure teams
• Migration State Tracking (atlas.sum) — Atlas uses checksummed migration files (atlas.sum) to track applied migrations and detect changes, similar to Terraform state files; crucial for safe apply operations
• Linting Schema Migrations — Atlas can lint proposed migrations for destructive changes, performance issues, and policy violations before applying; requires static analysis of DDL

• golang-migrate/migrate — Alternative versioned-only migration tool for Go; lacks declarative/diff features but simpler for pure migration execution
• liquibase/liquibase — Multi-language migration tool supporting similar declarative workflows; main competitor for schema versioning across polyglot teams
• ariga/ent — Ariga's own Go ORM; Atlas integrates with Ent schemas for schema-as-code workflows
• hashicorp/terraform — Terraform inspired Atlas's declarative state-comparison architecture and HCL configuration syntax
• sqlc-dev/sqlc — Complementary tool for type-safe SQL generation in Go; works well with Atlas for migration + query safety

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add integration tests for Turso/LibSQL dialect in ci-dialect_oss.yaml

The repo imports github.com/tursodatabase/libsql-client-go but there's no corresponding CI workflow for testing the LibSQL dialect alongside MySQL, PostgreSQL, and CockroachDB. The ci-dialect_oss.yaml workflow only runs specific dialect tests, and LibSQL is missing despite being a production dependency.

• [ ] Review cmd/atlas/internal/cmdapi to identify LibSQL-specific test cases that should run in CI
• [ ] Add a new test job in .github/workflows/ci-dialect_oss.yaml that spins up a Turso/LibSQL test database
• [ ] Create a Dockerfile in .github/ops/libsql/ (similar to .github/ops/mysql/Dockerfile) to containerize the test database
• [ ] Add LibSQL-specific migration and schema test fixtures to cmd/atlas/internal/cmdapi/testdata/
• [ ] Document the new dialect test coverage in the CI workflow comments

Add comprehensive E2E tests for multi-tenant migration workflows in atlasexec

The repo has testdata for multi-tenant scenarios at atlasexec/internal/e2e/testdata/multi-tenants/ but only a sqlite_test.go file testing it. This is a critical real-world use case that needs broader database support and more complex scenarios (e.g., tenant isolation, rollback behavior, concurrent migrations).

• [ ] Expand atlasexec/internal/e2e/sqlite_test.go to include separate test functions for multi-tenant scenarios with isolation verification
• [ ] Add MySQL and PostgreSQL variants of multi-tenant tests in new files (e.g., atlasexec/internal/e2e/mysql_test.go, atlasexec/internal/e2e/postgres_test.go)
• [ ] Create additional testdata scenarios: multi-tenant with schema-per-tenant, multi-tenant with row-level security, and failed tenant migration recovery
• [ ] Add test cases that verify atlasexec/atlas_migrate.go correctly handles multi-tenant contexts and env variables
• [ ] Document multi-tenant migration best practices in atlasexec/README.md with examples

Implement missing unit tests for atlasexec/copilot.go AI generation feature

The copilot.go file (AI-powered migration suggestions) has a copilot_test.go with minimal coverage. Given that this involves external API calls and complex logic, there are likely gaps in error handling, mock API responses, and edge cases that need testing.

• [ ] Review atlasexec/copilot.go and copilot_test.go to identify untested code paths (error handling, retries, timeout scenarios)
• [ ] Add test cases for API failures (timeout, rate-limit, malformed response) in copilot_test.go
• [ ] Mock the copilot API client and add tests for different migration suggestion types (DDL, rollback, conflict resolution)
• [ ] Add benchmarks for copilot API response parsing to ensure performance doesn't regress
• [ ] Document the copilot integration points in atlasexec/README.md with examples and limitations

• Add integration tests for the new Copilot feature (copilot.go, copilot_test.go) covering the full E2E workflow with mock LLM responses
• Write missing documentation and examples for the multi-tenant migration workflow (atlasexec/internal/e2e/testdata/multi-tenants/ exists but has no docs/guide)
• Extend CI dialect testing to include Oracle and Databricks variants (currently only MySQL and CockroachDB OSS in .github/workflows/), following the pattern in ci-dialect_oss.yaml

• High · Outdated Go Version — cmd/atlas/go.mod. The go.mod specifies 'go 1.25.9' which appears to be a future or non-existent version. This could indicate either a configuration error or use of an unreleased/invalid Go version, which may lead to unexpected behavior and missed security patches. Fix: Verify and update to a stable, current Go version (e.g., 1.22.x or 1.23.x). Check official Go releases at golang.org/dl.
• High · Dependency on Pre-release Atlas Version — cmd/atlas/go.mod. The project depends on 'ariga.io/atlas v0.32.1-0.20250325101103-175b25e1c1b9' which is a pre-release/development version (indicated by the timestamp-based pseudo-version). This may contain unpatched vulnerabilities or unstable code. Fix: Use stable, released versions of dependencies. Migrate to the latest stable release of ariga.io/atlas (v0.32.1 or later stable version) once available.
• Medium · Outdated Dependency: lib/pq — cmd/atlas/go.mod (github.com/lib/pq v1.12.0). The PostgreSQL driver 'github.com/lib/pq v1.12.0' is significantly outdated (current stable is 1.10+). Older versions may contain known security vulnerabilities. Fix: Update to the latest stable version of github.com/lib/pq. Run 'go get -u github.com/lib/pq' and verify compatibility with the codebase.
• Medium · Potential SQL Injection Risk — cmd/atlas/internal/cmdapi (migration and schema handling), atlasexec/testdata/migrations. The codebase handles raw SQL queries (visible in testdata files with .sql extensions and SQL migration handling). Without evidence of parameterized query patterns or SQL sanitization, there's risk of SQL injection vulnerabilities. Fix: Ensure all SQL queries use parameterized statements or prepared statements. Implement input validation and sanitization for user-provided SQL. Use ORM or query builders that handle escaping automatically.
• Medium · Missing Security Headers in GitHub Actions — .github/workflows/. GitHub Actions workflows (.github/workflows/) are visible but their content is not provided. These workflows may have security issues such as exposed secrets, insecure checkout configurations, or overly permissive token permissions. Fix: Audit all GitHub Actions workflows for: (1) secrets handling, (2) use of 'persist-credentials: false' in checkout, (3) restricted GITHUB_TOKEN permissions, (4) verification of third-party action versions.
• Medium · Outdated AWS SDK Dependencies — cmd/atlas/go.mod. Dependencies on 'github.com/aws/aws-sdk-go v1.55.7' (v1 SDK) alongside aws-sdk-go-v2 creates maintenance burden. V1 SDK is in maintenance mode and may not receive security updates. Fix: Migrate fully to AWS SDK v2 (github.com/aws/aws-sdk-go-v2). Remove v1 SDK dependency and update all code to use v2 APIs.
• Medium · Cloud Storage Integration Without Visible Security Controls — cmd/atlas/go.mod (gocloud.dev), cmd/atlas/internal/cloudapi/. The dependency on 'gocloud.dev v0.43.0' indicates cloud storage integration (Google Cloud, AWS, etc.). No visible evidence of encryption, access controls, or credential management in file structure. Fix: Implement encryption at rest/transit for cloud storage. Use managed identity/IAM roles instead of hardcoded credentials. Audit cloudapi/client.go for security best practices.
• Low · Weak Randomness: google/uuid Usage — cmd/atlas/go.mod. The 'github.com/google/uuid v1.6.0' dependency is used for UUID generation. While generally secure, ensure UUIDs are not used for security-sensitive purposes like session tokens. Fix: Use cryptographically secure random generation for any security-sensitive identifiers. Document where

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.