May 06, 2021

Announcing EdgeDB Beta 2: Luyten

Looking to another nearby star, we’re pleased to announce the second public beta of EdgeDB: Luyten!

Back in February 2021, we released the first beta version of EdgeDB after three years in development and 7 alpha releases. Since then, we’ve shifted focus from implementing new features to improving stability and performance. And we did: this release is the culmination of 10 weeks of fixes and enhancements.

But we couldn’t help ourselves! We’re excited to introduce a new interactive CLI tool called edgedb project—a project scaffolding tool that makes the process of setting up an EdgeDB-powered project even easier—, plus Deno support, customizable transaction settings for our client libraries, and more!

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.

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:

Copy
# 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:

Copy
$ edgedb server upgrade my_instance

Or upgrade all instances simultaneously:

Copy
$ edgedb server upgrade

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 users: you can now use the EdgeDB JS/TypeScript client! It’s available for immediate import on deno.land/x.

Copy
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

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.

Copy
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:

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

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;
    # ...
  }
}

# ...

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.