Skip to main content

Connect to your database

info

In this section, we perform read-only operations and make no changes to your database.

With the Atlas CLI installed and logged-in to your account, let's now make sure we can connect to your database with the CLI.

Step 1: Determine the database's URL​

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]

Select your database below for the connection URL format. For the full reference, see the URL Docs.

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

Step 2: Choose connection scope​

Using the connection URL, specify the scope with which you would like Atlas to connect:

Schema scope​

  • Targets a single schema.
  • Atlas only sees objects in that schema, and generated DDL omits schema qualifiers (e.g. CREATE TABLE users instead of CREATE TABLE public.users).
# PostgreSQL: search_path selects the schema
postgres://localhost:5432/database?search_path=public

# MySQL: the path segment is the schema
mysql://localhost:3306/app_schema

Database scope​

  • Targets the entire database or specific schemas within it.
  • Atlas includes schema qualifiers in generated DDL (e.g. CREATE TABLE public.users):
# PostgreSQL: no search_path = all schemas
postgres://localhost:5432/database

# MySQL: trailing slash = all schemas
mysql://localhost:3306/

Which scope should you use?​

Use caseScope
All tables live in one schemaSchema
Multiple schemas (e.g. auth, billing)Database
Qualified identifiers (e.g. auth.users)Database
Database-level objects: extensions, roles, event triggers, composite typesDatabase

The URL examples in Step 1 above show both scope formats per database. For a detailed explanation, see Schema vs. Database scope.

Test your connection​

Once you have determined your full connection URL, including its scope, you can test that Atlas is able to connect to the database using the following command:

atlas schema inspect --url "<url>" --format "OK"

Be sure to replace <url> with your database's URL.

If Atlas is able to connect to the given URL you should see the following output:

OK

Troubleshooting​

Password contains special characters​

Atlas uses standard RFC 3986 URLs. Characters like @, $, +, % in the password must be percent-encoded. For example, Pa$$w@rd becomes Pa%24%24w%40rd.

Without encoding, you will see errors like:

Error: mysql: query system variables: dial tcp: lookup root:BnB+PjA:3309: no such host

Encode the password before putting it in the URL:

import urllib.parse
print(urllib.parse.quote("BnB+PjA"))  # BnB%2BPjA

You can also use the urlescape function in atlas.hcl to handle this automatically:

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

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

Connection times out​

Error: postgres: scanning system variables: dial tcp 10.0.5.243:5432: connect: operation timed out

Atlas cannot reach the database over the network. Verify:

  • You are connected to the correct VPN
  • Firewall rules allow connections from your machine
  • The host and port in the URL are correct
  • If the database is behind a bastion/jump server, set up an SSH tunnel first

SSL/TLS errors​

For local or dev databases where SSL is not configured, disable it in the URL:

# PostgreSQL
postgres://localhost:5432/database?sslmode=disable

# MySQL
mysql://localhost:3306/schema?tls=skip-verify

For production databases, see the SSL/TLS configuration docs.

Authentication failed​

Double-check that the username and password are correct and that the user has the necessary permissions. For database-specific requirements:

  • PostgreSQL: The user needs CONNECT privilege on the database and USAGE on the target schema.
  • MySQL: The user needs SELECT privilege on information_schema and the target schema.
  • SQL Server: The user needs db_owner role for database-scope connections.
  • Oracle: See the required grants in the Oracle URL tab.
Need more help?

If you are evaluating Atlas for commercial use, reach out via your shared Slack Connect channel. Otherwise, use the Community Support channels and provide a minimal example to reproduce the issue.