URLs

What is a URL?

Uniform Resource Locators, or URLs are a standardized method for specifying a location of a resource. All the component parts of a URL are shown below:

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

An example might look like:

MySQL

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

MariaDB

Connecting to a local MariaDB server (all schemas/databases):

maria://localhost:3306/

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

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

Connecting using Unix Sockets:

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

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

maria+unix://user@/tmp/mysql.sock?database=dbname

PostgreSQL

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@0.0.0.0:5432/database?search_path=public&sslmode=disable

SQLServer

Connecting to a default schema of current user:

sqlserver://sa:P@ssw0rd0995@localhost:1433?database=master&mode=schema

Connecting to a local SQLServer database named master (all schemas). The user need to have db_owner role:

sqlserver://sa:P@ssw0rd0995@localhost:1433?database=master&mode=database

note

• The mode parameter is Atlas-specific and isn't used for opening the underlying connection.
• The default mode is schema.

SQLite

Connecting to a local SQLite database (file):

sqlite://file.db

Connecting to an in-memory SQLite database (ephemeral). Useful for --dev-url:

sqlite://file?mode=memory&_fk=1

Atlas also supports WebSocket connections to remote libsql databases:

libsql+wss://database-url

Docker

Atlas can spin up an ephemeral local docker container for you by specifying a special URL like below. This can be useful if you need a dev database for schema validation or diffing. However, some images like mysql / mariadb take quite some time to "boot", before they are ready to be used. For a smoother developing experience consider spinning up a longer lived container by yourself.

# PostgreSQL database scope (all schemas).
docker://postgres/15/test

# PostgreSQL specific schema scope.
docker://postgres/15/test?search_path=public

# MySQL server scope (all schemas).
docker://mysql/8

# MySQL specific schema scope.
docker://mysql/8/test

# MySQL server scope (all schemas).
docker://maria/latest

# MySQL specific schema scope.
docker://maria/latest/test

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.