Announcing EdgeDB Beta 2: Luyten

What’s EdgeDB?

EdgeDB is an advanced open source relational database based on PostgreSQL. The project aims to give developers and data engineers a highly efficient and productive database technology while addressing the shortcomings of SQL and its surrounding ecosystem.

It takes the best features of ORMs and GraphQL—declarative schemas, migrations, easy deep fetching—and bakes them into a strict relational database:

• a high-level data model and type system;

• a powerful, expressive and extensible query language called EdgeQL

• first-class support for schema migrations;

• support for converting arbitrary strictly typed data to and from JSON via a simple cast operator;

• out-of-the-box interoperability via REST and GraphQL;

• first-party database clients JavaScript, Go, and Python.

Installing Beta 2

To upgrade to Beta 2, you’ll first need need to install the latest version of our CLI.

If you already have an version installed, just run edgedb self-upgrade to get the latest CLI, then run edgedb server upgrade.

If you’ve never used EdgeDB before, you can install the CLI with a single command:

# macOS/Linux
$ curl --proto '=https' --tlsv1.2 -sSf https://sh.edgedb.com | sh

# Windows
$ iwr https://ps1.edgedb.com/ -useb | iex

Then run edgedb server install.

Once you’ve got the latest versions of the CLI and EdgeDB, you’re ready to get started. And getting started is easier than ever before!

Upgrade your instances

To upgrade an existing EdgeDB instance to Beta 2:

$ edgedb server upgrade my_instance

Or upgrade all instances simultaneously:

$ edgedb server upgrade

Introducing edgedb project

The primary new feature of Beta 2 is the addition of edgedb project to our CLI and its associated edgedb.toml config file, which lives in your project root directory.

Turn any directory on your computer into an “EdgeDB Project” by running edgedb project init inside it. This command does a lot:

• It scaffolds your project by creating a dbschema folder and an empty dbschema/schema.esdl inside it (if they don’t already exist).

• It prompts you to either create a new EdgeDB instance on your machine or specify an existing one that’s already running on your computer.

• It creates a link between that instance and the current project directory. This link is recorded in the ~/.edgedb/projects directory.

• It generates an edgedb.toml file if it doesn’t already exist. This identifies the directory as an EdgeDB Project. Check this file into version control so it’s easy for others to easily spin up a local EdgeDB instance for this project.

Once your project is initialized, you no longer need to use connection flags in CLI commands. Instead of edgedb -I my_instance migrate, you can simply run edgedb migrate inside your project directory! 🎉

Plus, you no longer need to provide an instance name or set environment variables with connection information if you’re using one of EdgeDB’s first-party client libraries for JavaScript/TypeScript, Python, and Go). The library automatically detects the edgedb.toml file and connects to the linked instance automatically.

For a more complete explanation of how to get started with edgedb project, read the dedicated post: Introducing EdgeDB Projects.

Deno support

Deno users: you can now use the EdgeDB JS/TypeScript client! It’s available for immediate import on deno.land/x.

import * as edgedb from "https://deno.land/x/edgedb/mod.ts"

const conn = await edgedb.connect();

// (for remote instances)
// const conn = await edgedb.connect(
//   "edgedb://edgedb@example.com/test"
// );

// run a query
const result = await conn.queryOneJSON(`SELECT 2 + 2;`);
result; // => 4

Customizable retry logic

Beta 1 introduced best-in-class automatic retrying and transaction logic across EdgeDBs first-party client libraries for JavaScript/TypeScript, Python, and Go. For more information, read the Robust Client API RFC.

Now, we’ve made every aspect of that logic configurable. You can override the default transaction & retry settings for your connection pool with the immutable withTransactionOptions and withRetryOptions methods. The example below uses the TypeScript client but there are equivalent APIs for Python and Go. Read the docs to learn the syntax for your preferred language.

import * as edgedb from "./index.node";

async function main() {
  const defaultPool = await edgedb.createPool();

const retryOptions = new edgedb.RetryOptions(
  5, // defaults to 3
  edgedb.defaultBackoff // (attemptNo: number)=>number
);

const transactionOptions = new edgedb.TransactionOptions({
  // defaults to RepeatableRead
  isolation: edgedb.IsolationLevel.Serializable,
  // defaults to false
  readonly: true,
  // defaults to false
  deferrable: true,
});

const customizedPool = defaultPool
  .withTransactionOptions(transactionOptions)
  .withRetryOptions(retryOptions);

  await customizedPool.retryingTransaction(async (tx) => {
    await tx.queryJSON(`SELECT User FILTER id = <uuid>`, {});
  });
}

By default all transactions are executed using the RepeatableRead isolation level. You can now customize transactions to run as Serializable instead, and explictly mark transactions as readonly or deferrable. Read more about these terms in the Postgres Transaction docs.

You can also specify the max number of retries (defaults to 3) and a custom exponential backoff function, which defaults to this:

export function defaultBackoff(attemptNo: number): number {
  return 2 ** attemptNo * 100 + Math.random() * 100;
}

DESCRIBE SCHEMA AS SDL

For instances running EdgeDB 1.0 Beta 2 or later, you can now introspect the current schema as SDL with the DESCRIBE SCHEMA AS SDL DDL command. This is useful if you want to conveniently compare your local schema file(s) to the instance’s current schema state. Just open a repl and run the command:

$ edgedb -I my_instance
edgedb> DESCRIBE SCHEMA AS SDL;
{
  type default::User {
    required property name -> std:str;
    # ...
  }
}

# ...

Start using Beta 2

For a full breakdown of the bug fixes and stability improvements in Beta 2, check out the full Changelog.

To start playing with EdgeDB, go through the 5-minute Quickstart or try the interactive tutorial (no need to install anything)! We’re happy to give assistance and debug issues, just reach out on GitHub Discussions or file a a bug report or a feature request.

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