Skip to main content

atlas-provider-sqlalchemy

Use Atlas with SQLAlchemy to manage your database schema as code. By connecting your SQLAlchemy models to Atlas, you can define and edit your schema directly in Python, and Atlas will automatically plan and apply database schema migrations for you, eliminating the need to write migrations manually.

Atlas brings automated CI/CD workflows to your database, along with built-in support for testing, linting, schema drift detection, and schema monitoring. It also allows you to extend SQLAlchemy with advanced database objects such as triggers, row-level security, and custom functions that are not supported natively.

Use-cases

  1. Declarative migrations - Use the Terraform-like atlas schema apply --env sqlalchemy command to apply your SQLAlchemy schema to the database.
  2. Automatic migration planning - Use atlas migrate diff --env sqlalchemy to automatically plan database schema changes and generate a migration from the current database version to the desired version defined by your SQLAlchemy schema.

Installation

Install Atlas from macOS or Linux by running:

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

See atlasgo.io for more installation options.

Install the provider by running:

# The Provider works by importing your SQLAlchemy models and extracting the schema from them.
# Therefore, you will need to run the provider from within your project's Python environment.
pip install atlas-provider-sqlalchemy

Standalone

If all of your SQLAlchemy models exist in a single package, you can use the provider directly to load your SQLAlchemy schema into Atlas.

In your project directory, create a new file named atlas.hcl with the following contents:

data "external_schema" "sqlalchemy" {
  program = [
    "atlas-provider-sqlalchemy",
    "--path", "./path/to/models",
    "--dialect", "mysql" // mariadb | postgresql | sqlite | mssql
  ]
}

env "sqlalchemy" {
  src = data.external_schema.sqlalchemy.url
  dev = "docker://mysql/8/dev"
  migration {
    dir = "file://migrations"
  }
  format {
    migrate {
      diff = "{{ sql . \"  \" }}"
    }
  }
}

As Python Script

If you want to use the provider as a python script, you can use the provider as follows:

Create a new file named load_models.py with the following contents:

# import all models
from models import User, Task
from atlas_provider_sqlalchemy.ddl import print_ddl
print_ddl("mysql", [User, Task])

Next, in your project directory, create a new file named atlas.hcl with the following contents:

data "external_schema" "sqlalchemy" {
    program = [
        "python",
        "load_models.py"
    ]
}

env "sqlalchemy" {
  src = data.external_schema.sqlalchemy.url
  dev = "docker://mysql/8/dev"
  migration {
    dir = "file://migrations"
  }
  format {
    migrate {
      diff = "{{ sql . \"  \" }}"
    }
  }
}

Usage

Once you have the provider installed, you can use it to apply your SQLAlchemy schema to the database:

Apply

You can use the atlas schema apply command to plan and apply a migration of your database to your current SQLAlchemy schema. This works by inspecting the target database and comparing it to the SQLAlchemy schema and creating a migration plan. Atlas will prompt you to confirm the migration plan before applying it to the database.

atlas schema apply --env sqlalchemy -u "mysql://root:password@localhost:3306/mydb"

Where the -u flag accepts the URL to the target database.

Diff

Atlas supports a version migration workflow, where each change to the database is versioned and recorded in a migration file. You can use the atlas migrate diff command to automatically generate a migration file that will migrate the database from its latest revision to the current SQLAlchemy schema.

atlas migrate diff --env sqlalchemy 

Supported Databases

The provider supports the following databases:

  • MySQL
  • MariaDB
  • PostgreSQL
  • SQLite
  • Microsoft SQL Server
  • ClickHouse
  • Snowflake

FAQ

How to include schema creation in the migration?

Sometimes your tables may not reside in the default schema, and you may want to create the schema as part of the migration.

you can utilize composite schemas to add custom DDL in addition to the SQLAlchemy schema.

change your atlas.hcl like this:

data "external_schema" "sqlalchemy" {
  program = [
    "atlas-provider-sqlalchemy",
    "--path", "./path/to/models",
    "--dialect", "postgresql"
  ]
}

data "composite_schema" "app" {
    # Create the test schema first
    schema "public" {
        url = "file://schema.sql"
    }
   # Next, load the sqlalchemy models.
    schema "public" {
        url = data.external_schema.sqlalchemy.url
    }
}

env "sqlalchemy" {
  src = data.composite_schema.app.url
  dev = "docker://postgres/16/dev"
  migration {
    dir = "file://migrations"
  }
  format {
    migrate {
      diff = "{{ sql . \"  \" }}"
    }
  }
}

and create a schema.sql file with the following contents (change the schema name as needed):

CREATE SCHEMA IF NOT EXISTS test;

Credit

The code in this repository is based on noamtamir/atlas-provider-sqlalchemy.

Issues

Please report any issues or feature requests in the ariga/atlas repository.

License

This project is licensed under the Apache License 2.0.

Metadata

Release files for atlas-provider-sqlalchemy 0.6.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for atlas-provider-sqlalchemy 0.6.0
File Size Uploaded Provenance Actions
atlas_provider_sqlalchemy-0.6.0.tar.gz 10.3 kB With provenance Details for atlas_provider_sqlalchemy-0.6.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for atlas-provider-sqlalchemy 0.6.0
File Interpreter ABI Platform Actions
atlas_provider_sqlalchemy-0.6.0-py3-none-any.whl Python 3 none any Details for atlas_provider_sqlalchemy-0.6.0-py3-none-any.whl

Total release size: 22.6 kB

Release files / atlas_provider_sqlalchemy-0.6.0.tar.gz

Download URL atlas_provider_sqlalchemy-0.6.0.tar.gz
Size 10.3 kB
Tags Source
SHA-256 checksum
How to use checksums
28f2e037749507672feee706ab49b5ed6a5b1af76c5aa0ae71a963e72cac15a1
BLAKE2b-256 checksum
How to use checksums
92894780a7d2f0bd0bb6112d9a2e5ddd890cabb1a03a89c3c8281fa1aa0a4752
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 30, 2026.

Transparency log

Release files / atlas_provider_sqlalchemy-0.6.0-py3-none-any.whl

Download URL atlas_provider_sqlalchemy-0.6.0-py3-none-any.whl
Size 12.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
6733fd80cbe58d90c60672ea555e5ae98e4f9aacbe65b4ea547009aca49f92f2
BLAKE2b-256 checksum
How to use checksums
7a21d517890b724abd63d57985328ab75918e263ddb1fc5c6f483ec080a01eaa
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 30, 2026.

Transparency log

Security for atlas-provider-sqlalchemy 0.6.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for atlas_provider_sqlalchemy-0.6.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 30, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page