Skip to main content

URLs

Atlas uses a standard URL format to connect to databases and load schemas and migrations from various sources. The format below covers the supported parts of a URL, with subsequent sections providing more detailed examples.

driver://[username[:password]@]address/[schema|database][?param1=value1&...&paramN=valueN]

To inspect a database using a URL, refer to one of the examples below:

Connecting to a local PostgreSQL database named database (all schemas):

postgres://localhost:5432/database

Connecting to a specific PostgreSQL schema named public:

postgres://localhost:5432/database?search_path=public

Connecting to a local PostgreSQL with credentials and SSL disabled:

postgres://postgres:pass@localhost:5432/database?search_path=public&sslmode=disable
Schema vs. Database scope

When the database URL targets a specific schema, Atlas limits its scope to that schema for inspection, diffing, planning, and applying changes. DDL statements are formatted without schema qualifiers and can be executed on any schema - for example, table instead of schema.table.

postgres://localhost:5432/db?search_path=public
mysql://localhost:3306/dev

When no schema is specified, Atlas operates on all schemas and includes schema qualifiers in the generated DDL statements - for example, schema.table instead of table.

postgres://localhost:5432/db
mysql://localhost:3306/

For PostgreSQL, use the search_path query parameter to specify the schema scope. For MySQL, specify the schema as the database name in the URL path. For SQL Server, use the mode query parameter. For other drivers, see the examples in the tabs above.

Supported Schemes​

Besides the standard database URLs mentioned above, Atlas supports various schemes for loading schemas and migration states:

file​

The file:// scheme is used to load schema state from a local file or a directory. The supported extensions are .sql and .hcl. For example:

file://path/to/schema.hcl
file://path/to/schema.sql
file://path/to/schemadir

file://path/to/migrations
file://path/to/migrations?version=20231201182011

atlas​

The atlas:// scheme is used to load the state of a remote schema or a migrations directory from the Atlas Cloud, the schema registry, and migrations artifactory of Atlas. For example:

atlas://dir-slug
atlas://dir-slug?version=20231201182011
atlas://dir-slug?tag=39e7e4e35fce7409bd26d25d8140061695d4ffd5

env​

The env:// scheme is useful for referencing the state of a schema after it has been loaded by a data source. For example:

atlas.hcl
data "external_schema" "orm" {
  program = [
    ...
  ]
}

env "dev" {
  orm = data.external_schema.orm
}
atlas schema inspect --env dev -u env://orm

ent​

The ent:// scheme is used to load the state an ent schema. For example:

ent://path/to/ent/schema

SSL/TLS Mode​

PostgreSQL​

The default SSL mode for Postgres is required. Please follow the Postgres documentation for configuring your SSL connection for your database, or set SSL mode to disable with the search parameter ?sslmode=disable. For local databases, disabling SSL is appropriate when inspecting and applying schema changes.

MySQL​

MySQL does not require TLS by default. However, you can require TLS with the ?tls=true search parameter.

Specify the ?ssl-ca search parameter to use a custom CA certificate, or ?ssl-cert and ?ssl-key to use a custom certificate and key. Follow the MySQL documentation for configuring encrypted connections with your database.

Non-alphanumeric characters​

Database URLs often contain passwords and other information which may contain non-alphanumeric characters. These characters must be escaped using standard URL encoding, in order to be parsed correctly. As a convenience, users may use the urlescape function in an atlas.hcl project file to escape these characters automatically.

Suppose your password is h:e!:l:l:o and it is stored as an environment variable named DB_PASSWORD, you can read this value and escape it using the urlescape function:

atlas.hcl
locals {
  db_pass = urlescape(getenv("DB_PASSWORD"))
}

env "local" {
    url = "postgres://user:${local.db_pass}@localhost:5432/database"
}

The urlescape function return the escaped value: h%3Ae%21%3Al%3Al%3Ao.