EdgeDB Release Candidate 2

Introducing Lacaille​

As always, this release is named after a nearby star. This time it’s Lacaille—a red dwarf about 10.74 lightyears from Earth. It’s named after Nicolas-Louis de Lacaille, a prolific French astronomer who named 17 IAU-recognized constellations, second only to Ptolemy’s 47.

We’ve been hard at work squashing bugs and streamlining developer workflows. Click a link below to jump to the relevant section.

• What is EdgeDB?

• A simplified client API

• Retrying transactions by default

• Idle connection cleanup

• Observability with Prometheus

• A new memory scalar

• Improved local Docker workflow

• Standardized connection behavior

What is EdgeDB?​

If you haven’t heard of EdgeDB yet, it’s a next-generation open source object-relational database with an obsessive focus on developer experience. Featuring:

• a strict, robust typesystem

• object-oriented schema modeling with multiple inheritance, key-less relations, computed properties, JSON support, and more

• a next-generation query language called EdgeQL, featuring JOIN-less deep fetching, composable subquerying, and an extensive standard library

• performant, first-party database clients for JavaScript/TypeScript, Python, and Go

• a binary protocol for blazing fast querying

• a unified developer experience via our comprehensive edgedb CLI, which can manage instances, create and apply migrations, and open a shell to local or remote instances

• built-in REST and GraphQL query and mutation endpoints

And plenty more. Our goal is to modernize every aspect of the database developer experience. Check out the 10-minute quickstart to learn more.

A simplified client API​

Previously, our client libraries made a distinction between an individual Connection and a connection Pool. This is a common convention in language bindings for other databases. When we designed our client APIs, we chose to conform to this convention.

import * as edgedb from "edgedb";

async function run(){
  const conn = await edgedb.connect(); // Connection
  const pool = await edgedb.createPool(); // Pool
}

But that decision didn’t sit well with us. In modern backend development, connection pooling is a best practice. Your API throughput should never be bottlenecked by the capacity of single physical connection to your database. Moreover, there’s no practical difference between a single “raw” connection and a connection pool of size one. Why bother with two separate concepts?

We decided there’s no good reason. So we’re introducing a new abstraction: the client.

import * as edgedb from "edgedb";
const client = edgedb.createClient();

// later
await client.querySingle(`select "hello world!"`);

import edgedb
client = edgedb.create_async_client('my_name')

# later
await client.query_single('select "hello world!"');

ctx := context.Background()
client, err := edgedb.CreateClient(ctx, opts)

// later
var result string
err = client.QuerySingle(ctx, "select 'hello world!'", &result)

// connection.js
import * as edgedb from "edgedb";

export const client = edgedb.createClient()

// api.js
import { client } from "./connection.js"

async function endpoint() {
  const result = await client.query(`select 2 + 2;`);
  console.log(result);
}

export const client = edgedb.createClient()

async function endpoint() {
  await client.ensureConnected();
  // ...
}

import * as edgedb from "edgedb";

async function main() {

  const client = edgedb.createClient();

  const results = await Promise.all([
    client.querySingle(`select 0`),
    client.querySingle(`select 1`),
    client.querySingle(`select 2`),
    client.querySingle(`select 3`),
    client.querySingle(`select 4`),
  ]);
  // [0, 1, 2, 3, 4]
}

import * as edgedb from "edgedb";

const client = edgedb.createClient({ concurrency: 1 });

Retrying transactions by default​

On the theme of next-generation client libraries, let’s talk about transactions.

EdgeDB’s client libraries include the concept of a “retrying transaction”; such transactions detect when “retryable” errors occur, roll back the current attempt, and try again. The delay between successive attempts is increased exponentially until a maximum number of attempts is hit.

const conn = edgedb.connect();

await conn.rawTransaction(async tx => {
  // do stuff
});

await conn.retryingTransaction(async tx => {
  // do stuff
});

const client = edgedb.createClient();

await client.transaction(async tx => {
  // do stuff
});

import * as edgedb from "edgedb";

const client = edgedb.createClient();

await client
  .withRetryOptions({attempts: 1})
  .transaction(async tx => {
    // this transaction will not be retried
  });

Idle connection cleanup​

We’ve implemented three mechanisms to automatically clean up idle connections and hanging transactions.

Observability with Prometheus​

EdgeDB instances now expose a Prometheus-compatible /metrics endpoint to provide observability into resource usage, performance, and error rates, including:

• The total and current number of spawned compiler processes.

• The total and current number of connections to the backend Postgres instance or cluster.

• The total and current number of incoming connections from clients.

• A histogram of query compilation and execution times.

• Several more — the full set of available metrics is documented in the Observability page.

To inspect these metrics, construct your instance’s Prometheus URL by appending /metrics to its address—for example, http://db.domain.com:5656/metrics. Plug this into your Prometheus instance.

A new scalar type cfg::memory​

EdgeDB exposes several memory configuration settings of the underlying Postgres database, including query_work_mem, shared_buffers, and effective_cache_size. Previously these values were represented with simple strings; however to represent these settings (and any future memory settings) safely and explicitly, we’ve implemented a new scalar type: cfg::memory.

As with uuid, datetime, and several other types, cfg::memory values are declared by casting from an appropriately formatted string.

db> 

select <cfg::memory>'1B'; # 1 byte

{<cfg::memory>'1B'}

db> 

select <cfg::memory>'5KiB'; # 5 kibibytes

{<cfg::memory>'5KiB'}

db> 

select <cfg::memory>'128MiB'; # 128 mebibytes

{<cfg::memory>'128MiB'}

db> 

select cfg::Config{session_idle_timeout, shared_buffers};

{cfg::Config {
  session_idle_timeout: <duration>'0:00:00',
  shared_buffers: <cfg::memory>'128MiB'
}}

Improved local Docker workflow​

Some users prefer to run EdgeDB in Docker container while developing locally, in an effort to standardize their development and production workflows. This approach is possible, but creates some friction with the recommended CLI-based workflows.

Standardized connection behavior​

There are several mechanisms for configuring a connection to an EdgeDB instance, whether using a client library or the CLI.

• You need to specify what instance to connect to, with an instance name, DSN, or credentials file.

• Depending on how you specify an instance, it may be necessary to separately provide a username, password, database name, or TLS settings.

• Moreover, all these settings can be provided to the client explicitly (say, passed as an argument to createClient) or via environment variables.

But what happens if you specify multiple conflicting connection methods? What is the relative priority of environment variables vs explicit parameters? In RC2 we’ve established a standard resolution algorithm that answers these questions and implements it uniformly across the CLI and all client libraries. Here’s a simple breakdown:

• There are three “priority levels”. From highest to lowest priority: 1) explicit connection parameters, 2) environment variables, 3) project-linked connections.

• Connection information specified in a higher priority level overrides any and all connection information from lower levels.

• Ambiguity within a given priority level is not allowed. For instance, specifying both EDGEDB_DSN and EDGEDB_INSTANCE environment variables will throw an error.

• So-called “granular parameters” (username, password, database, and TLS settings) can override individual components of non-granular parameters (e.g. DSNs) specified at the same or lower priority level. For instance, EDGEDB_USER will override a username specified within EDGEDB_DSN, but will have no effect when using --dsn (since --dsn takes priority).

This standardized resolution algorithm is implemented across all client libraries and the CLI. For a full breakdown of the algorithm, consult Connection Parameters.

Wrapping up​

For a full breakdown of the bug fixes and stability improvements in RC2, check out the full Changelog. To keep tabs on future announcements, follow us on Twitter @edgedatabase or GitHub!

Looking to learn more about EdgeDB?

• If you’re just starting out, go through 10-minute Quickstart guide.

• To dig into the EdgeQL query language, try the web-based interactive tutorial — no need to install anything.

• For an immersive, comprehensive walkthrough of EdgeDB concepts, check out our illustrated e-book Easy EdgeDB. It’s designed to walk a total beginner through EdgeDB, from the basics all the way through advanced concepts.

To keep tabs on future announcements, follow us on Twitter @edgedatabase!