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 MySQL server (all schemas/databases):

mysql://localhost:3306/

Connecting to a specific MySQL schema (database) with a username and password:

mysql://user:pass@localhost:3306/schema

Connecting using Unix Sockets:

mysql+unix:///tmp/mysql.sock

mysql+unix://user:pass@/tmp/mysql.sock

mysql+unix://user@/tmp/mysql.sock?database=dbname
Schema vs. Database scope

When the database URL is set to a specific schema (e.g., mysql://:3306/dev), the scope of the work done by Atlas (inspection, diffing, planning, applying, etc.) is limited to one schema. As a result, DDL statements printed during diffing or planning will be formatted without schema qualifiers and can be executed on any schema. e.g., table instead of schema.table

However, if the database URL does not specify a schema (e.g., mysql://:3306/), Atlas operates on the selected schemas (defaulting to all), and the generated DDL statements include schema qualifiers. e.g., schema.table instead of table.

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​

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 does not require TLS by default. However, you can require TLS with the ?tls=true search parameter.

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.