Managing Distributed Schemas with Confidence: Atlas Now Supports YugabyteDB

Vicky Harp

Schema changes are among the riskiest operations in a database’s life. A single misplaced ALTER TABLE can lock a hot table, break a deployment, or leave environments quietly drifting apart.

In a distributed SQL database like YugabyteDB, the stakes are even higher. Your schema describes more than just columns and constraints; it also determines how data is sharded, distributed across nodes and regions, and how it performs at scale.

Most schema-as-code tools were built for single-node PostgreSQL and don’t model any of this. The settings never show up in a diff, or a generated migration quietly leaves them out. That’s why we’re excited to share that Atlas, the open-source schema-as-code product, now supports YugabyteDB’s extensions to the PostgreSQL schema through its ysql:// driver as part of Atlas Pro.

Atlas has long been a popular choice for managing Postgres schemas. It can now understand and manage the distributed constructs that make YugabyteDB unique, including hash and range sharding, tablet splitting and colocation, and tablespaces for geo-placement. Teams can describe their full distributed schema in code, and Atlas will safely plan, validate, and apply changes.

For application developers, this means that schema changes follow the same workflow as application code. You declare the schema you want, review an automatically generated migration plan in a pull request, and let CI/CD apply it consistently across dev, staging, and production.

For DBAs, Atlas adds guardrails. Migration linting catches destructive or locking changes before they reach production, drift detection flags environments that have strayed from the source of truth, and a versioned history shows exactly what changed, when, and why.

This blog walks through how to set up Atlas with YugabyteDB and demonstrates these workflows in action.

Distribution is Part of the Schema

With YugabyteDB, reads and writes are spread across the shards, or tablets, of both tables and indexes. An index is a distributed object with its own tablets, so sharding is not only a table-level concern. How each object is split across the cluster is a schema design decision, on the same level as choosing columns and types.

YugabyteDB exposes three of these decisions in DDL:

DecisionWhat it controlsDDLAtlas attribute
Hash or range shardingWhether rows or index entries are hash-distributed or sorted by keyPRIMARY KEY (id HASH), (month_created ASC)sharding = HASH or sharding = RANGE on a key or index column
Pre-splittingHow many tablets a table starts with, or where their boundaries areSPLIT INTO 100 TABLETS, SPLIT AT VALUES (...)split_into (hash), split_at_values (range)
ColocationWhether a small table shares one tablet with its neighbors or gets its ownWITH (colocation = false)colocation = false

The defaults suit most tables, but every write-intensive schema has its hot table, pre-split table, or range-scanned index, and those are where a missed setting costs the most. A schema manager that models only columns and types either ignores these attributes or plans a migration to drop them.

Managing the Schema with Atlas

Atlas applies the infrastructure-as-code approach to database schemas. It supports YugabyteDB through its ysql:// driver and treats each distribution decision in the table above as a first-class schema attribute.

By executing atlas schema inspect, Atlas inspects live database instances to reverse-engineer distribution options like colocation and sharding layout. It tracks these configurations during diffing and explicitly emits HASH or ASC key strategies in the generated DDL, even when relying on system defaults. Certain parameters remain immutable once provisioned: Atlas blocks in-place modifications to table colocation properties. Furthermore, directives like split_into and split_at_values are applied only during the initial CREATE execution and are skipped in subsequent comparisons, allowing YugabyteDB to handle dynamic tablet splitting automatically as volume increases.

In Atlas’s declarative workflow, the team keeps a schema definition in the application repository, written in Atlas HCL, plain SQL, or loaded from an ORM. Engineers edit the desired state, and Atlas plans the DDL to bring each database to it.

A change follows the same path as any other code change:

  1. An engineer edits the schema definition file and runs atlas schema apply against a local database, which prints the planned SQL for approval.
  2. In the pull request, the Atlas CI integration runs atlas schema plan and posts the same plan for review.
  3. After the merge, the same desired state is applied to each environment in order: staging, then each production cluster.

The examples below follow a retail team through this workflow. Each change starts on a local cluster, the way an engineer tries it before opening a pull request, and then moves through review and rollout.

Setting Up a Local Cluster

Start a single-node YugabyteDB cluster in Docker:

docker run --rm -d --name atlas-yb \
  -p 5433:5433 \
  yugabytedb/yugabyte:latest \
  bin/yugabyted start --background=false

Most of the team’s tables take heavy write traffic and need their own tablets, so the team splits them across two databases on the same cluster:

  • shop is a regular database. Each table gets its own tablets.
  • lookup is colocated. It holds small reference tables that share one tablet.

Tables in different databases can’t reference each other through foreign keys, so each database holds a self-contained group of tables.

Once the cluster is running, create both databases:

docker exec atlas-yb bash -lc \
  'bin/ysqlsh -h "$(hostname -i)" -U yugabyte -d yugabyte -c "CREATE DATABASE shop"'
docker exec atlas-yb bash -lc \
  'bin/ysqlsh -h "$(hostname -i)" -U yugabyte -d yugabyte -c "CREATE DATABASE lookup WITH COLOCATION = true"'

YugabyteDB support is part of Atlas Pro. Install Atlas and log in:

atlas login

Next, create the Atlas project file, atlas.hcl, with an environment for each local database:

diff {
  concurrent_index {
    create = true
  }
}

docker "ysql" "colocated" {
  image      = "yugabytedb/yugabyte:latest"
  database   = "dev"
  colocation = true
}

env "shop_local" {
  url = "ysql://yugabyte@localhost:5433/shop?sslmode=disable"
  dev = "docker://ysql/latest/dev"
  schema {
    src = "file://shop.hcl"
  }
}

env "lookup_local" {
  url = "ysql://yugabyte@localhost:5433/lookup?sslmode=disable"
  dev = docker.ysql.colocated.url
  schema {
    src = "file://lookup.hcl"
  }
}

Each environment has an ephemeral dev database, where Atlas normalizes the desired schema before diffing it. The dev database must match its target’s colocation:

  • shop uses a regular dev database, docker://ysql/latest/dev.
  • lookup uses the docker "ysql" block, which creates a colocated one.

Each url points at a database without naming a schema, matching the database scope of its dev database, so Atlas manages every schema in it and plans schema-qualified DDL.

The diff block applies to every environment. YugabyteDB builds an index online, with backfill, only outside a transaction block, and Atlas runs a plan in a transaction by default. With concurrent_index, Atlas plans CREATE INDEX CONCURRENTLY and runs it outside the transaction.

Colocating Small Tables

In a colocated database, every table shares a single tablet by default. That suits small, low-traffic tables: a join between two colocated tables is served from one node, without a network hop. currencies and promotions are both small, so the team puts them in lookup.hcl and leaves them at the database default:

schema "public" {
}

table "currencies" {
  schema = schema.public
  column "code" {
    null = false
    type = character_varying(3)
  }
  column "name" {
    null = false
    type = character_varying
  }
  primary_key {
    columns = [column.code]
  }
}

table "promotions" {
  schema = schema.public
  column "id" {
    null = false
    type = bigint
  }
  column "code" {
    null = false
    type = character_varying(32)
  }
  column "discount_pct" {
    null = false
    type = numeric(5,2)
  }
  primary_key {
    columns = [column.id]
  }
}

Neither table says anything about colocation. Atlas treats it as unspecified, so both follow the database default.

Giving orders Its Own Tablets

orders is the opposite case. The team knows it will take a large share of the write traffic from day one, and that a single shared tablet would create a bottleneck.

It goes in shop.hcl. shop isn’t colocated, so orders gets its own tablets without any colocation setting. Its primary key is hash-sharded, the default outside a colocated tablet, so inserts spread evenly across its tablets:

schema "public" {
}

table "orders" {
  schema = schema.public
  column "id" {
    null = false
    type = bigint
  }
  column "customer_id" {
    null = false
    type = bigint
  }
  column "status" {
    null = false
    type = character_varying(20)
  }
  column "total" {
    null = false
    type = numeric(12,2)
  }
  column "created_at" {
    null = false
    type = timestamptz
  }
  column "month_created" {
    null = false
    type = date
  }
  primary_key {
    columns = [column.id]   // hash-sharded by default
  }
}

Applying the Schema

Run atlas schema apply against the local shop database:

atlas schema apply --env shop_local

Atlas diffs shop.hcl against the empty database and prints the plan before running anything:

Planning migration statements (1 in total):

  -- create "orders" table:
    -> CREATE TABLE "public"."orders" (
         "id" bigint NOT NULL,
         "customer_id" bigint NOT NULL,
         "status" character varying(20) NOT NULL,
         "total" numeric(12,2) NOT NULL,
         "created_at" timestamptz NOT NULL,
         "month_created" date NOT NULL,
         PRIMARY KEY ("id" HASH)
       );

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

Analyzing planned statements (1 in total):

  -- no diagnostics found

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

? Approve or abort the plan:
  ▸ Abort
    Approve and apply

Approve it, then apply lookup.hcl to the lookup database:

atlas schema apply --env lookup_local
Planning migration statements (2 in total):

  -- create "currencies" table:
    -> CREATE TABLE "public"."currencies" (
         "code" character varying(3) NOT NULL,
         "name" character varying NOT NULL,
         PRIMARY KEY ("code" ASC)
       );
  -- create "promotions" table:
    -> CREATE TABLE "public"."promotions" (
         "id" bigint NOT NULL,
         "code" character varying(32) NOT NULL,
         "discount_pct" numeric(5,2) NOT NULL,
         PRIMARY KEY ("id" ASC)
       );

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

Analyzing planned statements (2 in total):

  -- no diagnostics found

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

? Approve or abort the plan:
  ▸ Abort
    Approve and apply

These distribution choices are captured directly in the generated DDL: orders uses a hash-distributed key (HASH), whereas the colocated structures default to range order (ASC), where distributing across multiple tablets is unnecessary. Even when omitted from the source file, Atlas explicitly emits YugabyteDB’s key layout strategies to ensure consistent provisioning, ignoring server-level overrides such as yb_use_hash_splitting_by_default.

Adding a Range-Sharded Index

Months later, orders holds millions of rows, and most reporting and support queries are bounded by time: orders from last month, or orders in a given quarter. month_created holds the first day of the month in which the order was placed, so the team needs an index on it.

How that index is sharded decides how those queries perform. A hash-sharded index scatters adjacent values across all of its tablets, so a WHERE month_created BETWEEN … query has to read every one of them. A range-sharded index keeps values in sorted order, so the same query reads only the tablets that hold those months.

The trade-off is on the write path. month_created only grows, so every new order writes its index entry to the tablet that holds the current month. The team accepts that hot index tablet in exchange for fast range scans.

An engineer adds the index to shop.hcl in a feature branch and sets sharding = RANGE on its column:

table "orders" {
  // ...
  // highlight-start
  index "orders_month_created_idx" {
    on {
      column   = column.month_created
      sharding = RANGE
    }
  }
  // highlight-end
}

Then, they apply it to the local shop database:

atlas schema apply --env shop_local

This time, the database already holds the schema, so Atlas only plans the difference:

Planning migration statements (1 in total):

  -- create index "orders_month_created_idx" to table: "orders":
    -> CREATE INDEX CONCURRENTLY "orders_month_created_idx" ON "public"."orders" ("month_created" ASC);

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

Analyzing planned statements (1 in total):

  -- no diagnostics found

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

? Approve or abort the plan:
  ▸ Abort
    Approve and apply

Reviewing the Plan

Once local validation succeeds, the engineer submits a pull request. Atlas’s CI pipeline triggers atlas schema plan automatically, publishing the generated CREATE INDEX CONCURRENTLY DDL directly into the pull request comments for review.

This output provides immediate feedback: teammates can verify that the index uses online creation and range sharding, indicated by ASC instead of HASH on the key column alongside CONCURRENTLY. Equally critical is what remains unchanged: because Atlas inspects the target instance during execution, it detects matching layout parameters and avoids extraneous table rebuilds or attribute removals.

This review matters more than it would on a single-node database. YugabyteDB fixes an index’s sharding when the index is created, and can’t change it in place. A wrong setting caught in the pull request costs a comment. Caught in production, it means dropping and rebuilding an index over millions of rows.

Rolling Out to Every Environment

After the pull request merges, the same shop.hcl is applied to every environment. Each one gets its own env block in atlas.hcl, next to shop_local. Production runs on more than one cluster, so the shop_prod block uses the Atlas for_each meta-argument to expand into one environment per cluster:

variable "shop_prod_urls" {
  type    = list(string)
  default = []
}

// docker "ysql" "colocated" and the local environments as above.
env "shop_staging" {
  url = getenv("SHOP_STAGING_URL")
  dev = "docker://ysql/latest/dev"
  schema {
    src = "file://shop.hcl"
  }
  lint {
    review = WARNING
  }
}

env "shop_prod" {
  for_each = toset(var.shop_prod_urls)
  url      = each.value
  dev      = "docker://ysql/latest/dev"
  schema {
    src = "file://shop.hcl"
  }
  lint {
    review = WARNING
  }
}

Each target URL points to the shop database without a schema, the same scope as the dev database. The lookup database gets a matching pair, lookup_staging and lookup_prod, with lookup.hcl as the source, the colocated docker.ysql.colocated.url as the dev database, and the same lint block.

The pipeline runs the same command used locally for each environment in turn:

atlas schema apply --env shop_staging
atlas schema apply --env shop_prod \
  --var shop_prod_urls="$PROD_US_EAST_URL" \
  --var shop_prod_urls="$PROD_EU_WEST_URL"

For shop_prod, the pipeline passes one --var per production cluster, and Atlas applies the schema to every one of them. The empty default keeps the other environments working, since Atlas requires a variable without a default in every environment of the file.

Atlas plans against each database separately. A cluster that is already up to date reports Schema is synced, no changes to be made, and one that is behind gets only the statements it is missing. Here, that is the single CREATE INDEX CONCURRENTLY.

With a review policy of WARNING on every deployed environment, atlas schema apply applies a plan with no diagnostics, like the index above, without a prompt. A plan with a destructive change or a table rewrite is never applied unattended. In a terminal, Atlas asks for approval. In CI, the command fails with Rejected by review policy: errors or warnings were found, and the change ships as a plan reviewed and approved in advance. The policy is WARNING rather than ERROR because, on YugabyteDB, an index built without backfill and a table rewrite that can lose writes are both warnings. For stricter rules, such as blocking any DROP TABLE in production, use pre-execution checks and a destructive change policy.

Tablet counts don’t create false drift: YugabyteDB splits tablets as orders grows, and Atlas doesn’t diff tablet counts or split points. The schema inspection section of the YugabyteDB guide lists which distribution attributes Atlas reads back from a live database.

Wrapping Up

On YugabyteDB, sharding and colocation shape how a workload behaves as it grows, and some of those choices can’t be undone without rebuilding a table or index. Atlas reads them from live databases, keeps them intact in the DDL it plans, and puts every change to them in front of a reviewer alongside the columns and indexes they belong to. Changes that would rebuild a table get flagged and held for a person to approve.

Your team keeps a PostgreSQL-style workflow, and the distribution layout gets the same review, history, and rollout as the rest of the schema.

Get Started

To try it yourself, use the declarative and versioned YugabyteDB distribution guides walk through colocation, pre-splitting, and index sharding on a local cluster. If your database already exists, automatic migrations for YugabyteDB show how to inspect it and generate its schema as code.

From there, add Atlas to your CI/CD pipeline to plan and lint every schema change in pull requests, and set up drift detection to catch changes made to your clusters outside the pipeline.

Running YugabyteDB in production and want to see how Atlas fits your clusters? Schedule a demo with our team.

Vicky Harp

Related Posts

Explore Distributed SQL and YugabyteDB in Depth

Discover the future of data management.
Learn at Yugabyte University
Get Started
Browse Yugabyte Docs
Explore docs
PostgreSQL For Cloud Native World
Read for Free