Question​

When using Atlas on my macOS, I can run atlas migrate apply without any issues, and it applies the migrations successfully. But when running in CI on linux, I get the following error: Error: checksum mismatch

Answer​

This issue is likely due to differences in line endings between operating systems. macOS uses LF (Line Feed) for line endings, while Windows uses CRLF (Carriage Return + Line Feed). When you run Atlas commands in a Docker container, it may be using a different line ending format than what your migrations were created with.

To resolve this issue, you can try the following steps:

1. Add a .gitattributes file to your repository with the following content:

# Ensure all text files use LF line endings
* text=auto eol=lf

2. Commit the .gitattributes file to your repository.
3. If you have existing migration files that were created with different line endings, you may need to normalize them. You can do this by running the following command in your repository:

# Remove all files from the index (but keep them on disk)
git rm --cached -r .
# Re-checkout the files from the repository
git reset --hard

How to detect schema drift in CI and ensure the migration directory is up to date with the desired schema state - ORM, HCL, SQL, or any other schema definition?

With Atlas, we advocate for treating migration directories as deployment artifacts resulting from a structured build process. The preferred approach is to push migration directories to the Atlas Schema Registry. In addition to its role as a migration directory storage, the Schema Registry provides a tight integration with the Atlas CLI and the Atlas Cloud UI, allowing you to deploy migrations, visualize schemas over time, review deployment logs and errors, and more.

However, some users prefer to store their migration directories in S3, typically due to internal policies or requirements.

A .env file is a simple text file used to store environment variables for applications. It helps developers manage configuration settings, such as database credentials, API keys, and other sensitive information, without hardcoding them into the source code. By using a .env file, developers can keep their codebase clean, secure, and easily configurable across different environments.

For developers who want to use .env files with Atlas, there are two ways users can do so through the standard Atlas HCL configuration file:

Question​

Why does atlas schema apply / atlas schema plan fail with an error like this when working with PostgreSQL extensions?

PostGIS is a spatial database extension for PostgreSQL. It adds support for geometric objects, enabling the processing of spatial data like points, lines, and polygons. After installing PostGIS, the GEOMETRY data type can be used to define tables that capture geo-spatial data, for example:

How can I install Atlas, and why is go install no longer supported?

Developers who use Atlas to run migrations using a golang-migrate directory format, may run into an errors like:

-- migrating version 20250324061649.down.sql
-> DROP TABLE `users`;
   Error 1051 (42S02): Unknown table 'public.users'

With features such as composite schemas, custom rules, schema linting, and more, the atlas.hcl file can get complex. To validate or debug the file, you can use print statements as you commonly would with other languages.

PostgreSQL extensions are additional modules that extend the functionality of the PostgreSQL database. Examples of popular extensions include PostGIS for geographic data handling, PGVector for vector similarity search, and pgcrypto for cryptographic functions.

Once installed, these extensions provide additional data types and objects that users' schemas can leverage. However, because extensions are managed at the database level (and can only be installed once per database rather than per schema), users may prefer handling these extensions separately from their primary application schema migrations.

For example, if you maintain multiple applications – each with its own schema(s) but several relying on the same PostgreSQL extension – determining which application should handle installation, upgrades, or removal can be challenging. To address this complexity, managing extensions through a dedicated migration process is beneficial. This separation ensures extension-related changes remain isolated.

This guide demonstrates how to use the --include flag (or env.include argument) provided by Atlas to limit migrations specifically to PostgreSQL extensions.