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.
(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.
To execute queries from your application code, use one of EdgeDB’s client libraries for the following languages.
Unofficial (community-maintained) libraries are available for the following languages.
To follow along with the guide below, first create a new directory and initialize a project.
$
mydir myproject$
cd myproject$
edgedb project initConfigure the environment as needed for your preferred language.
$
npm init -y$
tsc --init # (TypeScript only)$
touch index.ts$
touch index.ts$
python -m venv venv$
source venv/bin/activate$
touch main.py$
cargo init$
go mod init example/quickstart$
touch hello.go$
dotnet new console -o . -f net6.0Install the EdgeDB client library.
$
npm install edgedb # npm$
yarn add edgedb # yarnn/a$
pip install edgedb# Cargo.toml
[dependencies]
edgedb-tokio = "0.3.0"
# additional dependencies
tokio = { version = "1", features = ["full"] }
anyhow = "1.0.63"$
go get github.com/edgedb/edgedb-go$
dotnet add package EdgeDB.Net.DriverCopy 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.
import {createClient} from 'edgedb';
const client = createClient();
client.querySingle(`select random()`).then((result) => {
console.log(result);
});import {createClient} from 'https://deno.land/x/edgedb';
const client = createClient();
const result = await client.querySingle(`select random()`);
console.log(result);from edgedb import create_client
client = create_client()
result = client.query_single("select random()")
print(result)// src/main.rs
#[tokio::main]
async fn main() -> anyhow::Result<()> {
let conn = edgedb_tokio::create_client().await?;
let val = conn
.query_required_single::<f64, _>("select random()", &())
.await?;
println!("Result: {}", val);
Ok(())
}// 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)
}using EdgeDB;
var client = new EdgeDBClient();
var result = await client.QuerySingleAsync<double>("select random();");
Console.WriteLine(result);Finally, execute the file.
$
npx tsx index.ts$
deno run --allow-all --unstable index.deno.ts$
python index.py$
cargo run$
go run .$
dotnet runYou 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.
All client libraries implement a standard protocol for determining how to connect to your database.
In development, we recommend initializing a project in the root of your codebase.
$
edgedb project initOnce 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.
EDGEDB_DSNIn production, connection information can be securely passed to the client
library via environment variables. Most commonly, you set a value for
EDGEDB_DSN.
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.
|
|
|
|
|
|
|
|
|
|
|
|
A typical DSN may look like this:
edgedb://username:pas$$word@db.domain.com:8080DSNs can also contain the following query parameters.
|
|
The database to connect to within the given instance. Defaults to
|
|
|
The TLS security mode. Accepts the following values.
|
|
|
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?database=my_db&tls_security=insecureFor a more comprehensive guide to DSNs, see the DSN Specification.
If needed for your deployment pipeline, each element of the DSN can be specified independently.
EDGEDB_HOST
EDGEDB_PORT
EDGEDB_USER
EDGEDB_PASSWORD
EDGEDB_DATABASE
EDGEDB_TLS_CA_FILE
EDGEDB_CLIENT_TLS_SECURITY
If a value for EDGEDB_DSN is defined, it will override these variables!
EDGEDB_CREDENTIALS_FILEA path to a .json file containing connection information. In some
scenarios (including local Docker development) its useful to represent
connection information with files.
{
"host": "localhost",
"port": 10700,
"user": "testuser",
"password": "testpassword",
"database": "edgedb",
"tls_cert_data": "-----BEGIN CERTIFICATE-----\nabcdef..."
}EDGEDB_INSTANCE (local only)The name of a local instance. Only useful in development.
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.
