Using Atlas declarative approach with Drizzle ORM schema definitions and handling multi-developer testing environments

[arthikek]

Atlas Declarative Approach with Drizzle ORM + Multi-Developer Testing Environment

Background

We're currently using Drizzle ORM to define our database schema and want to integrate Atlas for schema migrations. We're trying to understand the best approach for our workflow and how to handle some specific challenges.

Current Setup

• Schema Definition: Drizzle ORM (TypeScript)
• Database: PostgreSQL with pgvector extension
• Deployment: Google Cloud SQL via Cloud SQL Proxy
• CI/CD: GitHub Actions
• Environments: Local development, shared staging, production

Questions

1. Atlas Declarative Approach with Drizzle

We have our schema defined in Drizzle ORM and want to use Atlas's declarative approach. Our current atlas.hcl looks like this:

data "external_schema" "drizzle" {
  program = [
    "npx",
    "drizzle-kit",
    "export",
  ]
}

env "staging" {
  dev = "docker://pgvector/pg17/dev"
  url = local.envfile["STAGING"]
  schema {
    src = data.external_schema.drizzle.url
  }
  migration {
    dir = "file://migrations"
    revisions_schema = "public"
  }
}

Questions:

• Can Atlas generate migration files automatically when we change our Drizzle schema?
• Should we use atlas schema apply (declarative) or atlas migrate apply (versioned) with Drizzle?
• Will Atlas create migration files in the migrations/ folder when using the declarative approach?

2. Multi-Developer Testing Environment Challenge

We have a shared staging database where multiple developers deploy different versions for testing. This creates conflicts:

• Developer A deploys feature branch with new enum type roles
• Developer B deploys different feature branch, Atlas tries to create the same enum → conflict
• Database ends up in inconsistent state with mixed schema versions

Current Error Example:

-> CREATE TYPE "roles" AS ENUM ('Admin', 'Educator', 'Student');
pq: type "roles" already exists

Questions:

• What's the recommended approach for shared testing environments?
• Should each developer use separate staging databases?
• How can we handle "dirty" databases that have partial schema changes?
• Is there a way to make Atlas more resilient to existing objects?

3. Current Workflow Issues

Our GitHub Actions workflow:

1. Sets up Cloud SQL Proxy
2. Runs atlas migrate apply with --allow-dirty
3. Often fails due to existing database objects

We're considering switching to:

1. Calculate diff: atlas schema diff --env staging
2. Apply changes: atlas schema apply --env staging --auto-approve

Is this the right approach for a Drizzle + Atlas setup?

Desired Workflow

Ideally, we want:

1. Define schema changes in Drizzle ORM
2. Atlas automatically detects changes and generates/applies migrations
3. Safe deployment to staging environment regardless of current state
4. Multiple developers can deploy to staging without conflicts
5. Clean migration history for production deployments

Environment Details

• Atlas Version: Latest
• Drizzle Version: Latest
• PostgreSQL: 17 with pgvector extension
• Deployment: Cloud SQL + Cloud SQL Proxy

Any guidance on best practices for this setup would be greatly appreciated! Particularly interested in how other teams handle multi-developer environments with Atlas.

---

Additional Context:
We're open to changing our approach if there's a better way to handle schema management with Drizzle + Atlas for our multi-environment setup.

[MILLERMARRU]

1. Declarative + Drizzle: atlas schema apply with your external_schema block is the right call for what you described. It diffs your live target database against whatever drizzle-kit export produces (that's what data "external_schema" "drizzle" is for) and applies changes in place to reach that state, it does not write files into migrations/. If you want versioned migration files generated from that same source instead, that's atlas migrate diff against the same external_schema data source, the two workflows read from the same schema definition but produce different outputs (schema apply reconciles live state, migrate diff produces a file for migrate apply to replay later). You don't need both, pick one workflow per environment rather than mixing them.

2. This is exactly the case declarative solves. The core mechanical difference: migrate apply replays a linear history of migration files assuming the target is at a known prior version, so two developers deploying different branches to the same shared staging DB will produce the type "roles" already exists conflict you're seeing, because the second deploy's migration file assumes a starting state that no longer matches reality. schema apply instead computes its plan from the database's actual current state every time, so if roles already exists with the right shape, there's nothing to change for it, no conflict. That's the "resilient to existing objects" behavior you're asking about, it's inherent to the declarative model, not a flag to turn on. Given your team already has multiple branches landing on one shared staging DB, I'd switch that environment fully to atlas schema apply --env staging --auto-approve and drop migrate apply --allow-dirty there entirely, keep the versioned migrate apply workflow (if you want one) for production only, where deploys are sequential and drift isn't expected.

One caveat worth planning for: declarative apply can still refuse or misbehave on changes that aren't losslessly invertible from live state alone (renames that look like drop+create, data-affecting column type narrowing). Atlas's dev database (your docker://pgvector/pg17/dev line) exists to catch a lot of that during planning, keep it pointed at a throwaway container, not a shared one, since Atlas spins it up fresh to simulate the plan before touching your real target.