Client Libraries

EdgeDB implements libraries for popular languages that make it easier to work with EdgeDB. These libraries provide a common set of functionality.

Instantiating clients. Most libraries implement a Client class that internally manages a pool of physical connections to your EdgeDB instance.
Resolving connections. All client libraries implement a standard protocol for determining how to connect to your database. In most cases, this will involve checking for special environment variables like EDGEDB_DSN or, in the case of EdgeDB Cloud instances, EDGEDB_INSTANCE and EDGEDB_SECRET_KEY. (More on this in the Connection section below.)
Executing queries. A Client will provide some methods for executing queries against your database. Under the hood, this query is executed using EdgeDB’s efficient binary protocol.

For some use cases, you may not need a client library. EdgeDB allows you to execute queries over HTTP. This is slower than the binary protocol and lacks support for transactions and rich data types, but may be suitable if a client library isn’t available for your language of choice.

Available libraries

To execute queries from your application code, use one of EdgeDB’s client libraries for the following languages.

Usage

To follow along with the guide below, first create a new directory and initialize a project.

Copy

mydir myproject

Copy

cd myproject

Copy

edgedb project init

Configure the environment as needed for your preferred language.

Node.js

Deno

Python

Rust

.NET

Maven (Java)

Gradle (Java)

Elixir

Copy

npm init -y

Copy

tsc --init # (TypeScript only)

Copy

touch index.ts

Copy

touch index.ts

Copy

python -m venv venv

Copy

source venv/bin/activate

Copy

touch main.py

Copy

cargo init

Copy

go mod init example/quickstart

Copy

touch hello.go

Copy

dotnet new console -o . -f net6.0

Copy

touch Main.java

Copy

touch Main.java

Copy

mix new edgedb_quickstart

Install the EdgeDB client library.

Node.js

Deno

Python

Rust

.NET

Maven (Java)

Gradle (Java)

Elixir

Copy

npm install edgedb    # npm

Copy

yarn add edgedb       # yarn

Copy

n/a

Copy

pip install edgedb

Copy

# Cargo.toml

[dependencies]
edgedb-tokio = "0.5.0"
# Additional dependency
tokio = { version = "1.28.1", features = ["macros", "rt-multi-thread"] }

Copy

go get github.com/edgedb/edgedb-go

Copy

dotnet add package EdgeDB.Net.Driver

Copy

// pom.xml
<dependency>
    <groupId>com.edgedb</groupId>
    <artifactId>driver</artifactId>
</dependency>

// build.gradle
implementation 'com.edgedb:driver'

Copy

# mix.exs
{:edgedb, "~> 0.6.0"}

Copy and paste the following simple script. This script initializes a Client instance. Clients manage an internal pool of connections to your database and provide a set of methods for executing queries.

Note that we aren’t passing connection information (say, a connection URL) when creating a client. The client libraries can detect that they are inside a project directory and connect to the project-linked instance automatically. For details on configuring connections, refer to the Connection section below.

Node.js

Deno

Python

Rust

.NET

Futures (Java)

Reactor (Java)

Elixir

Copy

import {createClient} from 'edgedb';

const client = createClient();

client.querySingle(`select random()`).then((result) => {
  console.log(result);
});

Copy

import {createClient} from 'https://deno.land/x/edgedb/mod.ts';

const client = createClient();

const result = await client.querySingle(`select random()`);
console.log(result);

Copy

from edgedb import create_client

client = create_client()

result = client.query_single("select random()")
print(result)

Copy

// src/main.rs
#[tokio::main]
async fn main() {
    let conn = edgedb_tokio::create_client()
        .await
        .expect("Client initiation");
    let val = conn
        .query_required_single::<f64, _>("select random()", &())
        .await
        .expect("Returning value");
    println!("Result: {}", val);
}

Copy

// hello.go
package main

import (
  "context"
  "fmt"
  "log"

  "github.com/edgedb/edgedb-go"
)

func main() {
  ctx := context.Background()
  client, err := edgedb.CreateClient(ctx, edgedb.Options{})
  if err != nil {
    log.Fatal(err)
  }
  defer client.Close()

  var result float64
  err = client.
    QuerySingle(ctx, "select random();", &result)
  if err != nil {
    log.Fatal(err)
  }

  fmt.Println(result)
}

Copy

using EdgeDB;

var client = new EdgeDBClient();
var result = await client.QuerySingleAsync<double>("select random();");
Console.WriteLine(result);

Copy

import com.edgedb.driver.EdgeDBClient;
import java.util.concurrent.CompletableFuture;

public class Main {
    public static void main(String[] args) {
        var client = new EdgeDBClient();

        client.querySingle(String.class, "select random();")
            .thenAccept(System.out::println)
            .toCompletableFuture().get();
    }
}

Copy

import com.edgedb.driver.EdgeDBClient;
import reactor.core.publisher.Mono;

public class Main {
    public static void main(String[] args) {
        var client = new EdgeDBClient();

        Mono.fromFuture(client.querySingle(String.class, "select random();"))
            .doOnNext(System.out::println)
            .block();
    }
}

Copy

# lib/edgedb_quickstart.ex
defmodule EdgeDBQuickstart do
  def run do
    {:ok, client} = EdgeDB.start_link()
    result = EdgeDB.query_single!(client, "select random()")
    IO.inspect(result)
  end
end

Finally, execute the file.

Node.js

Deno

Python

Rust

.NET

Java

Elixir

Copy

npx tsx index.ts

Copy

deno run --allow-all --unstable index.deno.ts

Copy

python index.py

Copy

cargo run

Copy

go run .

Copy

dotnet run

Copy

javac Main.java

Copy

java Main

Copy

mix run -e EdgeDBQuickstart.run

You should see a random number get printed to the console. This number was generated inside your EdgeDB instance using EdgeQL’s built-in random() function.

Connection

All client libraries implement a standard protocol for determining how to connect to your database.

Using projects

In development, we recommend initializing a project in the root of your codebase.

Copy

edgedb project init

Once the project is initialized, any code that uses an official client library will automatically connect to the project-linked instance—no need for environment variables or hard-coded credentials. Follow the Using projects guide to get started.

Using environment variables

For EdgeDB Cloud

In production, connection information can be securely passed to the client library via environment variables. For EdgeDB Cloud instances, the recommended variables to set are EDGEDB_INSTANCE and EDGEDB_SECRET_KEY.

Set EDGEDB_INSTANCE to <org-name>/<instance-name> where <instance-name> is the name you set when you created the EdgeDB Cloud instance.

If you have not yet created a secret key, you can do so in the EdgeDB Cloud UI or by running edgedb cloud secretkey create via the CLI.

For self-hosted instances

Most commonly for self-hosted remote instances, you set a value for the EDGEDB_DSN environment variable.

If environment variables like EDGEDB_DSN are defined inside a project directory, the environment variables will take precedence.

A DSN is also known as a “connection string” and takes the following form.

edgedb://<username>:<password>@<hostname>:<port>

Each element of the DSN is optional; in fact edgedb:// is a technically a valid DSN. Any unspecified element will default to the following values.

`<host>`	`localhost`
`<port>`	`5656`
`<user>`	`edgedb`
`<password>`	`null`

A typical DSN may look like this:

edgedb://username:pas$$word@db.domain.com:8080

DSNs can also contain the following query parameters.

branch

The database branch to connect to within the given instance. Defaults to main.

tls_security

The TLS security mode. Accepts the following values.

"strict" (default) — verify certificates and hostnames
"no_host_verification" — verify certificates only
"insecure" — trust self-signed certificates

tls_ca_file

A filesystem path pointing to a CA root certificate. This is usually only necessary when attempting to connect via TLS to a remote instance with a self-signed certificate.

These parameters can be added to any DSN using web-standard query string notation.

edgedb://user:pass@example.com:8080?branch=my_branch&tls_security=insecure

For a more comprehensive guide to DSNs, see the DSN Specification.

Using multiple environment variables

If needed for your deployment pipeline, each element of the DSN can be specified independently.

EDGEDB_HOST
EDGEDB_PORT
EDGEDB_USER
EDGEDB_PASSWORD
EDGEDB_BRANCH
EDGEDB_TLS_CA_FILE
EDGEDB_CLIENT_TLS_SECURITY

If a value for EDGEDB_DSN is defined, it will override these variables!

Other mechanisms

EDGEDB_CREDENTIALS_FILE

A path to a .json file containing connection information. In some scenarios (including local Docker development) its useful to represent connection information with files.

Copy

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

EDGEDB_INSTANCE (local/EdgeDB Cloud only)

The name of an instance. Useful only for local or EdgeDB Cloud instances.

For more on EdgeDB Cloud instances, see the EdgeDB Cloud instance connection section above.

Reference

These are the most common ways to connect to an instance, however EdgeDB supports several other options for advanced use cases. For a complete reference on connection configuration, see Reference > Connection Parameters.

Client Libraries​

Available libraries​

Usage​

Connection​

Using projects​

Using environment variables​

For EdgeDB Cloud​

For self-hosted instances​

Using multiple environment variables​

Other mechanisms​

Reference​

Client Libraries

Available libraries

Usage

Connection

Using projects

Using environment variables

For EdgeDB Cloud

For self-hosted instances

Using multiple environment variables

Other mechanisms

Reference