September 30, 2021

EdgeDB Release Candidate 1

We’re pleased to announce the first Release Candidate of EdgeDB. In a few weeks, we’ll release RC2, followed shortly thereafter by a long-awaited stable 1.0 release. Follow @edgedatabase to stay apprised of new releases.

In the meantime: if you’re looking to build something with the future of relational databases: now is the time to start!

This release is called Epsilon Eridani, named (as always) after a nearby star. Epsilon Eridani is a mere 10.5 lightyears away and a sprightly 800 million years old. In Isaac Asimov’s Foundation series (which just premiered as a series on Apple TV+!), its solar system contained the first planet colonized by non-Spacer Earthmen. In reality, neither of its two confirmed planets are believed to be habitable. Nice try, Isaac.

As we rapidly approach 1.0, we continue to squash bugs, refine our documentation, and streamline development and deployment workflows. Click a link below to jump to the appropriate section of the post.

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

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

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

  • performant, first-party database clients for JavaScript/TypeScript, Python, and Go that implement our blazing fast binary protocol

  • a unified edgedb CLI with idiomatic workflows for managing instances, opening REPLs, and creating and applying migrations

  • built-in REST and GraphQL 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.

To get started, install the latest version of our CLI.

Go through our 10-minute Quickstart; it’ll walk you through the process of installing EdgeDB, spinning up an instance, creating/executing a migration, and running your first query.

Just run edgedb cli upgrade and the CLI will self-upgrade. If you have local instances on your machine you’ll need to upgrade those too:

  • If you’re using edgedb project, navigate to the root directory of your project and run edgedb project upgrade --to-latest. This will install the latest version of EdgeDB, upgrade the instance, migrate the data, and update your edgedb.toml.

  • To upgrade an instance that isn’t linked to a project (not recommended), run edgedb instance upgrade <instance_name> --to-latest.

Now onto the new features.

Remote EdgeDB instances can now be “linked” to your machine with the edgedb instance link command.

$ edgedb instance link --dsn edgedb://
Specify a new instance name for the remote server [default: hostname_5656]:
> hostname_5656
Successfully linked to remote instance. To connect run:
  edgedb -I hostname_5656

You now have a remote instance named hostname_5656. You can now refer to this instance by its name just like a local instance. You can even link this instance to a local project during the edgedb project init workflow:

$ edgedb project init
Found `edgedb.toml` in `/path/to/dir`
Initializing project...
Specify the name of EdgeDB instance to use with this project:
> hostname_5656
# initialization...
Project initialized.
To connect to hostname_5656, run `edgedb`

EdgeDB runs on top of Postgres. Commonly, EdgeDB internally manages its own Postgres instances, but it can also be run on top of a cloud- or self-hosted Postgres.

Some cluster management tools are capable of emitting events when the leader node fails. In this case, EdgeDB automatically listens to these events and directs all queries to the current leader node.

To indicate to EdgeDB that API-based HA is possible with your setup, specify the appropriate protocol in your --backend-dsn. Currently EdgeDB only supports API-based HA when using Stolon as the backend in a Consul-based setup.

  • stolon+consul+http://

  • stolon+consul+https://

Most cloud-based Postgres hosting services are DNS-based; these systems update DNS records with the IP address of the current leader node. There’s no direct way for EdgeDB to get notified of failover events; instead, EdgeDB uses some heuristics and an internal state machine to determine when a backend has initiated failover. For details on this implementation, check out the Backend HA docs.

When failover is detected, EdgeDB terminates and re-establishes all connections with the backend. Since EdgeDB doesn’t cache resolved DNS values, the new connections will be established to the new leader node.

Enable adaptive HA with the --enable-backend-adaptive-ha flag like so:

edgedb-server \
  --backend-dsn postgres:// \

You can now persistently customize the behavior of the CLI and REPL across your system with a global configuration file. Just create a file called cli.toml in your EdgeDB config directory. The location of this directory differs between operating systems; to find its location on your system, run edgedb info.

$ edgedb info
EdgeDB uses the following local paths:
│ Cache      │ /Users/colinmcd94/Library/Caches/edgedb/                        │
│ Config     │ /Users/colinmcd94/Library/Application Support/edgedb/           │
│ CLI Binary │ /Users/colinmcd94/Library/Application Support/edgedb/bin/edgedb │
│ Data       │ /Users/colinmcd94/Library/Application Support/edgedb/data/      │
│ Service    │ /Users/colinmcd94/Library/LaunchAgents/                         │

Navigate to the directory labelled “Config” and create a file called cli.toml with the following structure. All fields are optional.

expand-strings = true         # Stop escaping newlines in quoted strings
history-size = 10000          # Set number of entries retained in history
implicit-properties = false   # Print implicit properties of objects
implicit-limit = 100          # Set implicit LIMIT
                              # Defaults to 100, specify 0 to disable
input-mode = "emacs"          # Set input mode. One of: vi, emacs
output-format = "default"     # Set output format.
                              # One of: default, json, json-pretty, json-lines
print-stats = false           # Print statistics on each query
verbose-errors = false        # Print all errors with maximum verbosity

RC1 introduces a new top-level function assert_exists, the complement of assert_single (which was introduced in Beta 3). Calling assert_exists on an expression ensures at runtime that it includes at least one element; if the set is empty, an error is thrown.

SELECT assert_exists((SELECT User FILTER .name = "Existing user"))
{default::User {id: ...}}
SELECT assert_exists((SELECT User FILTER .name = "Nonexistent user"))
ERROR: CardinalityViolationError: assert_exists violation: expression
  returned an empty set.

Notably, the function enables the declaration required computed links and properties in object types, which was not previously possible.

We’ve made some changes to the structure of our documentation to make it more approachable for new users.

  • The reference documentation for all built-in operators and functions has been moved from the EdgeQL section to a new top-level section called Standard Library. The EdgeQL section still contains breakdowns of the major concepts and language constructs.

  • We’ve merged the Quickstart and Cheatsheets page into a unified Guides section. We’ve also written several new guides on broadly useful subjects like Updating Data and Defining Object Types.

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

Looking to learn more about EdgeDB?

  • If you’re just starting out, go through 5-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!