Atlas Registry

Atlas Registry allows you to store, version, and maintain a single source of truth for your database schemas, database migrations, and additional assets related to schema changes. It is like Docker Hub for Atlas schemas and migrations.

Getting Started

Pushing a Schema

The atlas schema push command allows you to push your schema definition to the Atlas Registry. If no repository exists in the registry for the schema, a new one is created. Otherwise, a new version is generated.

atlas schema push myapp \
  --env local

https://example.atlasgo.cloud/schemas/141733920769

Once pushed, the schema is available to others in your organization and can be referenced in your deployment pipelines.

Schema created with atlas schema push

Registry Config for Schemas

The example below demonstrates how to configure the registry for your schema within an env block. All commands executed in this environment will automatically use the configured repository:

atlas.hcl

env "local" {
  # URL to the underlying database.
  url = getenv("DATABASE_URL")
  # URL to the dev-database.
  dev = "sqlite://dev?mode=memory"
  schema {
    # Desired schema state.
    src = "file://schema.sql"
    # Atlas Registry config.
    repo {
      name = "myapp"
    }
  }
}

Pushing a Migration Directory

The atlas migrate push command allows you to push your migration directory to the Atlas Registry. If no repository exists in the registry for the pushed directory, a new one is created. Otherwise, the directory state will be updated.

atlas migrate push myapp \
  --env local

https://example.atlasgo.cloud/dirs/4294967370

Once pushed, the migration directory is available to others in your organization and can be referenced in your deployment pipelines.

Note that Atlas Registry is schema-aware. In addition to storing and versioning your migrations, it provides ER diagrams, SQL diffing, schema docs, and other capabilities that make working with your schema easier.

Migration Directory created with atlas migrate push

Registry Config for Migration Directories

The example below demonstrates how to configure the registry for your migration directory within an env block. All commands executed in this environment will automatically use the configured repository:

atlas.hcl

env "local" {
  # URL to the underlying database.
  url = getenv("DATABASE_URL")
  # URL to the dev-database.
  dev = "sqlite://dev?mode=memory"
  # URL to the desired schema state.
  src = "file://schema.sql"
  migration {
    # Atlas Registry config.
    repo {
      name = "myapp"
    }
  }
}

Simplifying Deployments

When you push a migration directory to the Schema Registry, you can give it a tag in the same way that you would tag a Docker image. This makes any version of your schema effectively addressable which dramatically simplifies deployments.

References to a schema version can then be used in your deployment pipelines with an expression similar to:

# Reference by version
atlas migrate apply \
    --dir "atlas://myapp?version=20231201182011" \
    --url "postgres://postgres:pass@:5432/example?search_path=public&sslmode=disable"

# Reference by tag
atlas migrate apply \
  --dir "atlas://app?tag=39e7e4e35fce7409bd26d25d8140061695d4ffd5" \
  --url "postgres://postgres:pass@:5432/example?search_path=public&sslmode=disable"

Using the Schema Registry completely eliminates the need to create custom Docker images for migrations or grant your runtime environments access to your source code repository.

Example: Kubernetes Deployment

Let's see how we can use tagged schema versions in a Kubernetes deployment:

apiVersion: db.atlasgo.io/v1alpha1
kind: AtlasMigration
metadata:
  name: migration
spec:
  urlFrom:
    secretKeyRef:
      key: url
      name: postgres-credentials
  cloud:
    project: "atlasdemo" # Atlas Cloud project name
    tokenFrom:
      secretKeyRef:
        name: atlas-credentials
        key: token
  dir:
    remote:
      name: "myapp" # Migration directory name in your atlas cloud project
      tag: "39e7e4e35fce7409bd26d25d8140061695d4ffd5" # See below on how to obtain this value for your project.

Example: Terraform

You can also use references to the Schema Registry in your Terraform modules:

resource "atlas_migration" "myapp" {
  url = "postgres://postgres:pass@:5432/example?search_path=public&sslmode=disable"
  remote_dir {
    name = "myapp"
    tag  = "39e7e4e35fce7409bd26d25d8140061695d4ffd5"
  }
}

Additional Benefits

• Schema Docs - Get automatically generated documentation for your schemas when you push them to the Schema Registry.