Connection parameters

• Instance parameters

• Priority levels

• Granular parameters

The CLI and client libraries (collectively referred to as “clients” below) must connect to an EdgeDB instance to run queries or commands. There are several connection parameters, each of which can be specified in several ways.

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 that’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.

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/DATABASE
# example
edgedb://alice:pa$$w0rd@example.com:1234/my_db

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
Database name: "edgedb"

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.

{
  "host": "localhost",
  "port": 10702,
  "user": "testuser",
  "password": "testpassword",
  "database": "edgedb",
  "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 connect call. Here’s how this looks using the JavaScript library:

```
import * as edgedb from "edgedb";
const pool = await edgedb.connect({
  instance: "my_instance"
});
```
In the context of the CLI, this means using the appropriate command-line flags:
```
$ 
```
```
edgedb --instance my_instance
```
```
EdgeDB 1.x
Type \help for help, \quit to quit.
edgedb>
```

1. 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:

```
$ 
```
```
edgedb # no flags needed
```
```
EdgeDB 1.x
Type \help for help, \quit to quit.
edgedb>
```
Using the JavaScript client library:
```
import * as edgedb from "edgedb";
const pool = edgedb.connect();
pool.query(`select 2 + 2;`).then(result => {
  // do stuff
})
```
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.

1. 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.

Within a given priority level, you cannot specify multiple instances “instance selection parameters” simultaneously. For instance, specifying both EDGEDB_INSTANCE and EDGEDB_DSN environment variables will result in an error.

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_DATABASE

Each EdgeDB instance can contain multiple databases. When in instance is created, a default database named edgedb is created. Unless otherwise specified, all incoming connections connect to the edgedb database.

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_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.

Override behavior

When specified, the connection parameters (user, password, and database) will override the corresponding element of a DSN, credentials file, etc. For instance, consider the following environment variables:

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

In this scenario, newuser will override olduser and newpass will override oldpass. The client library will try to connect using this modified DSN: edgedb://newuser:newpass@hostname.com:5656.

Overriding across priority levels

This override behavior only happens same or lower priority level. For instance:

• EDGEDB_PASSWORD will override the password specified in EDGEDB_DSN

• EDGEDB_PASSWORD will be ignored if a DSN is passed explicitly using the --dsn flag. Explicit parameters take precedence over environment variables. To override the password of an explicit DSN, you need to pass it explicitly as well:

```
$ 
```
```
edgedb --dsn edgedb://username:oldpass@hostname.com --password qwerty
```
```
# connects to edgedb://username:qwerty@hostname.com
```

• EDGEDB_PASSWORD will override the stored password associated with a project-linked instance. (This is unlikely to be desirable.)