Error: extension has no installation script nor update path for version

Question

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

danger

Error: create extension "postgis_topology": pq: extension "postgis_topology" has no installation script nor update path for version "3.4.3"

Answer

This error occurs when there's a version mismatch between the extension installed in your target database (current state) and the extension available in your local dev-database.

To make sure migration plans are safe, Atlas does the following:

1. It first creates the current state (the database schema) on the dev-database
2. Applies the planned migration to it
3. Inspects the result and checks if it matches the desired target state

This simulation helps Atlas detect potential issues before touching your actual database while ensuring the migration plans actually bring the schema to the desired state.

During stages 1 and 2, Atlas needs to recreate your schema's extensions in the dev-database. If the dev-database doesn't have installation scripts for the exact extension versions (whether from your current schema or desired state), PostgreSQL returns this error.

For example, if your production database has PostGIS 3.4.3 but your dev-database Docker image only includes PostGIS 3.5.x, Atlas cannot create an identical schema in the dev-database for validation.

Solutions

There are several approaches to resolve this issue:

1. Use a dev-database with matching extension versions

The most reliable solution is to ensure your dev-database has the same extension versions as your target database. You can:

Build a custom Docker image with the exact PostgreSQL and extension versions:

atlas.hcl

docker "postgres" "dev" {
  image = "postgres:16-custom"
  build {
    context    = "."
    dockerfile = "Dockerfile"
  }
}

env "dev" {
  url = "postgres://user:pass@host:5432/mydb"
  dev = docker.postgres.dev.url
}

Dockerfile

FROM postgres:16.8
RUN apt-get update && apt-get install -y \
    postgresql-16-postgis-3.4.3 \
    && rm -rf /var/lib/apt/lists/*

2. Use a compatible pre-built image

For PostGIS specifically, you can use the PostGIS Docker images that match your major version:

atlas.hcl

env "dev" {
  url = "postgres://user:pass@host:5432/mydb"
  dev = "docker://postgis/16-3.4/dev"
}

3. Use version 'ANY' for PostGIS extensions

PostGIS supports installing any available version when you specify version = "ANY". This tells PostGIS to install whatever version is available in the system:

schema.hcl

extension "postgis" {
  schema  = schema.public
  version = "ANY"
}

This approach works well when exact version matching isn't critical for your use case. PostGIS will store the version as "ANY" in the database metadata.

4. Exclude extension versions from Atlas management

You can tell Atlas to ignore extension versions entirely using the exclude attribute:

atlas.hcl

env "production" {
  url = "postgres://user:pass@host:5432/mydb"
  dev = "docker://postgres/16/dev"
  exclude = ["*[type=extension].version"]
}

Or use the --exclude flag when running commands:

atlas schema apply --env production --exclude "*[type=extension].version"

This allows Atlas to manage extensions without caring about specific versions, avoiding version mismatch errors while still tracking that extensions exist.

5. Manage extensions separately

As mentioned in our extension management guide, you can also manage extensions outside of Atlas migrations. This approach treats extension upgrades as infrastructure changes rather than schema migrations:

1. Remove extension definitions from your schema files
2. Manage extensions through a separate deployment process
3. Let Atlas handle only tables, indexes, and other schema objects

This avoids version conflicts but requires additional coordination for extension management.