EdgeDB Release Candidate 1

What is EdgeDB?​

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.

Remote instance linking​

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

$ edgedb instance link --dsn edgedb://username:password@hostname.com:5656
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`

High Availability Postgres support​

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.

$ 
  
  

edgedb-server \
  --backend-dsn postgres://xxx.rds.amazonaws.com \
  --enable-backend-adaptive-ha

Global CLI configuration​

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.

[shell]
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

Cardinality assertion​

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.

db> 

SELECT assert_exists((SELECT User FILTER .name = "Existing user"))

{default::User {id: ...}}

db> 

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.

Enforcing distinctness in computed links​

In the documentation, we use the term set to refer to the result of an EdgeDB expression; strictly speaking, though, EdgeDB sets are actually multisets, as they can contain duplicate elements in certain cases.

Until now, EdgeDB treated “real” and computed links differently. All “real” links were guaranteed to return a distinct set of results — no duplicates. This is implicitly enforced by how EdgeDB persists links under the hood. However, computed links weren’t subject to this constraint.

This is problematic. Practically speaking, an application’s logic may be written in such a way that it doesn’t expect duplicates in the results of a query. Philosophically speaking, this inconsistency runs counter to the design principles of EdgeDB.

So we fixed it. All computed links must now correspond to expressions that are guaranteed to be distinct. If this guarantee cannot be inferred, EdgeDB will throw an error during query compilation.

In most cases, distinctness can be properly inferred; however, subqueries containing UNIONs and FOR loops may return sets with duplicates. To accommodate this new constraint, users may either use the existing DISTINCT operator (which eliminates all duplicates from its operand) or the new std::assert_distinct assertion function.

Using std::assert_distinct is preferable in certain situations becauase it preserves the order of the result set, unlike DISTINCT. If you don’t expect duplicates to occur in your computed link, use std::assert_distinct; if you do, use DISTINCT.

Restructured documentation​

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.

Wrapping up​

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!