Connection parameters​

Specifying an instance​

There are several ways to uniquely identify an EdgeDB instance.

--host/-H <host>
--port/-P <port>

Let’s dig into each of these a bit more.

Instance name

All local instances (instances created on your local machine using the CLI) are associated with a name. This name is what’s needed to connect; under the hood, the CLI stores the instance credentials (username, password, etc) on your file system in the EdgeDB config directory. The CLI and client libraries look up these credentials to connect.

You can also assign names to remote instances using edgedb instance link. The CLI will save the credentials locally, so you can connect to a remote instance using just its name, just like a local instance.

If you have authenticated with EdgeDB Cloud in the CLI using the edgedb cloud login command, you can address your own EdgeDB Cloud instances using the instance name format <org-name>/<instance-name>. If you are not authenticated,

Secret key

If you want to connect to an EdgeDB Cloud instance in either of these scenarios:

• from a client binding

• from the CLI to an instance not belonging to the currently authenticated EdgeDB Cloud user

you will need to provide a secret key in addition to the instance name. Generate a dedicated secret key for the instance via the CLI with edgedb cloud secretkey create or via the web UI’s “Secret Keys” pane in your instance dashboard.

DSN

DSNs (data source names, also referred to as “connection strings”) are a convenient and flexible way to specify connection information with a simple string. It takes the following form:

edgedb://USERNAME:PASSWORD@HOSTNAME:PORT/BRANCH

# example
edgedb://alice:pa$$w0rd@example.com:1234/my_branch

All components of the DSN are optional; technically edgedb:// is a valid DSN. The unspecified values will fall back to their defaults:

Host: "localhost"
Port: 5656
User: "edgedb"
Password: null
Branch name: "main"

DSNs also accept query parameters to support advanced use cases. Read the DSN Specification reference for details.

Host and port

In general, we recommend using a fully-qualified DSN when connecting to the database. For convenience, it’s possible to individually specify a host and/or a port.

When not otherwise specified, the host defaults to "localhost" and the port defaults to 5656.

Credentials file

e.g. /path/to/credentials.json.

If you wish, you can store your credentials as a JSON file. Checking this file into version control could present a security risk and is not recommended.

Copy

{
  "host": "localhost",
  "port": 10702,
  "user": "testuser",
  "password": "testpassword",
  "branch": "main",
  "tls_cert_data": "-----BEGIN CERTIFICATE-----\nabcdef..."
}

Relative paths are resolved relative to the current working directory.

Project-linked instances

When you run edgedb project init in a given directory, EdgeDB creates an instance and “links” it to that directory. There’s nothing magical about this link; it’s just a bit of metadata that gets stored in the EdgeDB config directory. When you use the client libraries or run a CLI command inside a project-linked directory, the library/CLI can detect this, look up the linked instance’s credentials, and connect automatically.

For more information on how this works, check out the release post for edgedb project.

Priority levels​

The section above describes the various ways of specifying an EdgeDB instance. There are also several ways to provide this configuration information to the client. From highest to lowest priority, you can pass them explicitly as parameters/flags (useful for debugging), use environment variables (recommended for production), or rely on edgedb project (recommended for development).

1. Explicit connection parameters. For security reasons, hard-coding connection information or credentials in your codebase is not recommended, though it may be useful for debugging or testing purposes. As such, explicitly provided parameters are given the highest priority.

   In the context of the client libraries, this means passing an option explicitly into the client creation call. Here’s how this looks using the JavaScript library:

   Copy

   import * as edgedb from "edgedb";
   
   const pool = await edgedb.createClient({
     instance: "my_instance"
   });

   In the context of the CLI, this means using the appropriate command-line flags:

   Copy

   $ 

   edgedb --instance my_instance

   EdgeDB 2.x
   Type \help for help, \quit to quit.
   edgedb>

2. Environment variables.

   This is the recommended mechanism for providing connection information to your EdgeDB client, especially in production or when running EdgeDB inside a container. All clients read the following variables from the environment:

   • EDGEDB_DSN

   • EDGEDB_INSTANCE

   • EDGEDB_CREDENTIALS_FILE

   • EDGEDB_HOST / EDGEDB_PORT

   When one of these environment variables is defined, there’s no need to pass any additional information to the client. The CLI and client libraries will be able to connect without any additional information. You can execute CLI commands without any additional flags, like so:

   Copy

   $ 

   edgedb # no flags needed

   EdgeDB 2.x
   Type \help for help, \quit to quit.
   edgedb>

   Using the JavaScript client library:

   Copy

   import { createClient } from "edgedb";
   
   const client = createClient();
   const result = await client.querySingle("select 2 + 2;");
   console.log(result); // 4

   Ambiguity is not permitted. For instance, specifying both EDGEDB_INSTANCE and EDGEDB_DSN will result in an error. You can use EDGEDB_HOST and EDGEDB_PORT simultaneously.

3. Project-linked credentials

   If you are using edgedb project (which we recommend!) and haven’t otherwise specified any connection parameters, the CLI and client libraries will connect to the instance that’s been linked to your project.

   This makes it easy to get up and running with EdgeDB. Once you’ve run edgedb project init, the CLI and client libraries will be able to connect to your database without any explicit flags or parameters, as long as you’re inside the project directory.

If no connection information can be detected using the above mechanisms, the connection fails.

Granular parameters​

The instance selection section describes several mechanisms for providing a complete set of connection information in a single package. Occasionally—perhaps in development or for testing—it may be useful to override a particular component of this configuration.

The following “granular” parameters will override any value set by the instance-level configuration object.

EDGEDB_BRANCH

Each EdgeDB instance can be branched multiple times. When an instance is created, a default branch named main is created. For CLI-managed instances, connections are made to the currently active branch. In other cases, incoming connections connect to the main branch by default.

EDGEDB_USER/EDGEDB_PASSWORD

These are the credentials of the database user account to connect to the EdgeDB instance.

EDGEDB_TLS_CA_FILE

TLS is required to connect to any EdgeDB instance. To do so, the client needs a reference to the root certificate of your instance’s certificate chain. Typically this will be handled for you when you create a local instance or link a remote one.

If you’re using a globally trusted CA like Let’s Encrypt, the root certificate will almost certainly exist already in your system’s global certificate pool. In this case, you won’t need to specify this path; it will be discovered automatically by the client.

If you’re self-issuing certificates, you must download the root certificate and provide a path to its location on the filesystem. Otherwise TLS will fail to connect.

EDGEDB_TLS_SERVER_NAME (SNI)

If for some reason target instance IP address can’t be resolved from the hostname, you can provide SNI.

EDGEDB_CLIENT_TLS_SECURITY

Sets the TLS security mode. Determines whether certificate and hostname verification is enabled. Possible values:

• "strict" (default) — certificates and hostnames will be verified

• "no_host_verification" — verify certificates but not hostnames

• "insecure" — client libraries will trust self-signed TLS certificates. Useful for self-signed or custom certificates.

This setting defaults to "strict" unless a custom certificate is supplied, in which case it is set to "no_host_verification".

EDGEDB_CLIENT_SECURITY

Provides some simple “security presets”.

Currently there is only one valid value: insecure_dev_mode. Setting EDGEDB_CLIENT_SECURITY=insecure_dev_mode disables all TLS security measures. Currently it is equivalent to setting EDGEDB_CLIENT_TLS_SECURITY=insecure but it may encompass additional configuration settings later. This is most commonly used when developing locally with Docker.

EDGEDB_DSN=edgedb://olduser:oldpass@hostname.com:5656
EDGEDB_USER=newuser
EDGEDB_PASSWORD=newpass