Quartz 4

EdgeDB User Questions

11 min read

How to uninstall EdgeDB?

The EdgeDB CLI is comprised only of a single binary, so deleting it is relatively straightforward. If you also want to delete configuration files, do that first since the CLI is helpful in finding them.

Run edgedb info to list all directories the CLI uses to store data. Use rm -rf <dir> to remove them from a Linux or macOS terminal. Windows users may delete them using Windows Explorer or via your command line of choice.

You are now ready to delete the CLI itself. In Linux or macOS, you may use this command:

rm "$(which edgedb)"

In Windows you may use get-command edgedb from Powershell or where edgedb from Command Prompt to discover the location of the binary. You may then delete it using your preferred method.

How to uninstall on Windows?

How to Scale (for self-hosted)?

What is in edgedb.toml?

Does EdgeDB do authentication?

  • Elvis: There is no authentication layer in EdgeDB yet, but we intend to provide a mechanism to plug one. As for permissions/ACL, the next version will have a mechanism to specify values for global session variables via JWT claims, so all you’ll need is some authentication service that authorizes users and issues JWTs and then the app can talk to EdgeDB directly (given you’ve implemented ACL in schema with access policy)

How do I seed my database?

See seed.ts in this repo:

Why can’t I connect to my local DB?

See if EdgeDB is trying to connect on ::1. If so, the problem may be that EdgeDB is not listening on that address. If so, you can fix it by running this:

edgedb configure set listen_addresses 127.0.0.1 ::1

Is EdgeDB Postgres?

EdgeDB is not a Postgres extension, it is a server that wraps Postgres.

How do I wipe my database?

edgedb query "create database tmp"
edgedb -d tmp query "drop database edgedb" "create database edgedb" 
edgedb query "drop database tmp"

3.0 CLI will have edgedb database wipe command to make this easy

How do I make the EdgeDB UI available in production?

Set the EDGEDB_SERVER_ADMIN_UI env var to enabled.

How do I merge schema and migrations?

  1. Merge schema files with any git merge tool you like.
  2. Remove any migrations that were created by the code you’re merging in. (This would be any migrations that are not already on your main branch.)
  3. Drop the database and run edgedb migrate
  4. Run edgedb migration create to recreate migrations from the branch.

If you are just merging a single other branch back into your main branch, you wouldn’t have to do anything special. The migrations would just fall into line and work.

Once 3.0 is live with edgedb watch, you can just have that running and ensure no errors with step 3 instead of having to run edgedb migrate.

How is the performance?

How to upgrade production instance?

See https://github.com/edgedb/edgedb/issues/4236

Update EdgeDB Docker container tag with target version. If upgrading across major versions, dump data, spin up new instance, restore.

Do migrations lint against dangerous table-locking operations?

Yury: We do linting to ensure that type conversions (alters) are safe and properly defined. It’s on our list to continuously invest into the migrations engine to make users aware (and later guide) about scenarios where a migration can lock things for too long etc.

Elvis: The ultimate goal is for the migrations to “just work” without any worry for locks or downtime. Tight control over how queries get compiled and how the protocol works makes this very doable (a.k.a online migrations).

Isn’t it just an ORM?

Short answer is that it’s an implementation detail. Postgres is running under the hood and we communicate with it via SQL. In some future we might embed it and compile to its IR. When comparing to ORMs you should look at the entire EdgeDB value prop which is: a composable and expressive query language, schema with advanced concepts like multiple inheritance and polymorphism, advanced tooling, great efficient client APIs and many other things.

Do you hide round trips to Postgres for nested queries?

A single EdgeQL query, no matter how complex, is guaranteed to always compile into one SQL query. And then we directly talk to Postgres via its binary protocol for max efficiency.

All of this to say that even if your single query fetches multiple hierarchies and does multiple mutations, it will still be executed atomically and “all at once” by EdgeDB/internal Postgres.

How do I proxy the EdgeDB UI through Traefik?

See thread of https://discord.com/channels/841451783728529451/849377751370432573/1077711326618583210

Credit user Star-Lord#5303 on Discord

labels:
      ...
      - traefik.tcp.routers.db-edgedb.rule=HostSNI(`edgedb.${DOMAIN?Variable not set}`)
      - traefik.tcp.routers.db-edgedb.entrypoints=edgedb
      - traefik.tcp.routers.db-edgedb.tls=true
      # - traefik.tcp.routers.db-edgedb.tls.certresolver=le
      - traefik.tcp.routers.db-edgedb.tls.passthrough=true
      - traefik.tcp.routers.db-edgedb.service=db-edgedb-service
      - traefik.tcp.services.db-edgedb-service.loadbalancer.server.port=5656

also include the following config options for traefik instance

ports:
      - 80:80
      - 443:443
      # For edgedb
      - 5656:5656
command:
      ...
      - --entrypoints.edgedb.address=:5656

How do I find an intersection of two sets? the difference of two sets?

Pre 3.0:

select set_a filter set_a in set_b; # intersect
select set_a filter set_a not in set_b; # subtract

3.0 will add intersect and except: https://github.com/edgedb/edgedb/pull/4631

How to upgrade production EdgeDB?

From Frederick:

Upgrading a major version i.e. from 1.x to 2.x requires that you dump your database and create a new postgres and edgedb 2.x and restore. Upgrading a minor version only requires changing the docker image version. no other changes or actions are required.

How do I roll back migrations?

Migration steps - Rolling back / delete / reset Migrations · Issue #4300 · edgedb/edgedb · GitHub

  • Create another migration that reverts your schema if you need to migrate down
  • Try our new (as of 3.0) migration workflow for a way to experiment with your schema without creating migrations
  • In 3.0, you will be able to squash migrations.

Does EdgeDB support optimistic concurrency control?

https://discord.com/channels/841451783728529451/1082334221831520337/1083451656282320937 Let’s use Prisma’s movie ticket booking example:

type Seat { required link movie → Movie; link claimed_by → User; }

type Movie { property name → str; }

Consider two scenarios:

Scenario 1: short period read-write consistency. This is where in your application you perform a read, and then, very shortly after, a write and you need to make sure data is consistent. The recommended approach in EdgeDB for this case is to either:

  • compose the read and the write into a single query (EdgeQL and TS query bulilder can compose arbitrary subqueries!); this will not only reduce the possibility of concurrent races, but would also be more efficient as there would be fewer server roundtrips:

await e.update(e.Seat, seat ⇒ ({ filter: e.op( e.op(seat.movie.name, ’=’, movieName), ‘and’, e.op(‘not’, e.op(‘exists’, seat.claimed_by)) ), set: { claimed_by: e.select(e.User, user ⇒ ({ filter_single: {id: current_user} }) } }).run(client)

  • in cases when you need to put some application logic between the read and the write, just use a transaction block! A mutation in a transaction does not create an exclusive lock in EdgeDB, so independent readers are not blocked! However, since EdgeDB uses PostgreSQL’s serializable transaction isolation, the consistency of reads and writes happens automatically, you don’t need to write explicit application code to enforce it:

await client.transaction(tx ⇒ { const availableSeat = await e.select(e.Seat, seat ⇒ ({ id: true, filter: e.op( e.op(seat.movie.name, ’=’, movieName), ‘and’, e.op(‘not’, e.op(‘exists’, seat.claimed_by)) ), limit: 1 })).run(tx)

if (availableSeat.length === 0) { throw new Error(Oh no! ${movieName} is all booked.) }

await e.update(e.Seat, seat ⇒ ({ filter_single: {id: availableSeat[0].id}, set: { claimed_by: e.select(e.User, user ⇒ ({ filter_single: {id: current_user} })) } })).run(tx) }) If another concurrent client manages to update the Seat before this transaction commits, this transaction will raise a TransactionSerializationError and the transaction block will be automatically(!) retried. This all works thanks to how the serializable isolation level is implemented in Postgres.

Now, Scenario 2: long period read-write consistency, where the time between a read and a write could be significant, such as when you send the record to an external system for processing. We do not recommend using transactions in this scenario, so you can still implement the approach in Prisma’s example with an application-maintained version field.

type Seat { … required property version → int64 { default := 0 } }

const availableSeat = await e.select(e.Seat, seat ⇒ ({ id: true, version: true, filter: e.op( e.op(seat.movie.name, ’=’, movieName), ‘and’, e.op(‘not’, e.op(‘exists’, seat.claimed_by)) ), limit: 1 })).run(client)

if (availableSeat.length === 0) { throw new Error(Oh no! ${movieName} is all booked.) }

// Some time after

const updatedSeats = await e.update(e.Seat, seat ⇒ ({ filter_single: { id: availableSeat[0].id, version: availableSeat[0].version }, set: { claimed_by: e.select(e.User, user ⇒ ({ filter_single: {id: current_user} })), version: e.op(seat.version, ’+’, 1), } })).run(tx)

if (updatedSeats.length === 0) { throw new Error(That seat is already booked! Please try again.) } However, it gets better. The upcoming EdgeDB 3.0 will introduce support for mutation rewrites (a.k.a. “BEFORE triggers”), so you wouldn’t need to manually increment the version every time you mutate an object. Instead you’d declare that this should be done automatically in your schema:

type Seat { required link movie → Movie; link claimed_by → User; required property version → int64 { default := 0; # Inject version increment into every UPDATE rewrite update using (.version + 1); } }

I hope this answers your question.

Can EdgeDB be used on CloudFlare Workers or via Vercel Edge functions?

Yes.

Why doesn’t my alias’s shape hold?

https://discord.com/channels/841451783728529451/841451783728529454/1075174769399435366

Shapes in EdgeQL are not like traditional SQL projections, they are basically overlays. In other words, you can overload and add stuff to the underlying type, but you cannot subtract from a type (because the result would no longer really be the same type).

And aliases are just that — aliases to expressions.

If you really need a specific shape, you can try a free object:

alias B := (for a in A union { name := a.name })

How do I insert if an object doesn’t exist, select if it does, and know which happened?

https://discord.com/channels/841451783728529451/849377751370432573/1100902217583697980

with
  user := (
    insert User { name := 'sam' }
    unless conflict on .name else (
      select User filter .name = 'sam'
    )
  ),
select user {
  id,
  name,
  new := (select not exists (select User filter .id = user.id)),
};

How do I return from a query different types?

Cast the result to JSON

while maintaining type safety?

scope> with W := (select Named filter .name like 'B%'),
...... for x in W union {
......     user := x[is User] { name, deck_cost },
......     card := x[is Card] { name, cost, element },
...... };
{
  {
    user: {},
    card: default::Card {name: 'Bog monster', cost: 2, element: 'Water'},
  },
  {user: default::User {name: 'Bob', deck_cost: 9}, card: {}},
}

Is EdgeDB a graph database?

See Can edgeDB as “Graph Relational Database” be used for Data Graphs (~Graph Database)? · edgedb edgedb · Discussion #3964 · GitHub

Can you sort dynamically (parameterize order by)?

Elvis: You can do it by using if else, e.g:

order by 
  .prop1 if sortProperty = 'prop1' else
  .prop2 if sortProperty = 'prop2' else
  .default_prop

How do I set the EdgeDB password when connecting EdgeDB to an external Postgres database?

edgedb --admin --unix-path=/home/aswath/edgePsql query "alter role edgedb set password := 'password'"

How do we tell if a link or property is computed in introspection?

computed links and properties have a non-empty expr property in introspection.

links: {
  is_computed := exists .expr
}

How do I recover accidentally deleted migrations?

Elvis: There’s no automated way yet to recover unfortunately. However, you can recover the content by running this query:

for m in (schema::Migration { 
    name, 
    parent := (select .parents limit 1).name ?? "initial", 
    script
  }
)
union
  "CREATE MIGRATION " ++ m.name ++ " ONTO " ++ m.parent
  ++ " {" ++ m.script ++ "};";

You need to then copy each returned element to dbschema/migrations as files numbered nnnnn.edgeql. The order is determined by the parent (i.e the ONTO value). So ONTO initial would be the first migration in 00001.edgeql. The next, 00002.edgeql would be the one that has the name of the migration in 00001.edgeql in it’s ONTO clause, etc.

Cloud

Is EdgeDB Cloud going to be just the EdgeDB part of the system or also the postgres part?

https://discord.com/channels/841451783728529451/1049696883230113822/1050509599599505528 Both

If it is also the postgres part, is the underlying postgres going to be accessible?

https://discord.com/channels/841451783728529451/1049696883230113822/1050509599599505528 EdgeDB 3.0 will have the ability to pass arbitrary (read-only) SQL to Postgres. Other than that can you describe why you need access to the underlying Postgres cluster?

From what I’ve seen around it is going to be built on AWS first, is it true?

https://discord.com/channels/841451783728529451/1049696883230113822/1050509599599505528 Yes

If EdgeDB Cloud is on AWS, will it be available on all AWS regions?

https://discord.com/channels/841451783728529451/1049696883230113822/1050509599599505528 Specific regions would be based on popular demand, but we will run in regions on all continents

Have you also thought about developing a beefier EdgeDB UI? Something that might become a GUI above all (edgedb and edgedb-server) CLI?

https://discord.com/channels/841451783728529451/1049696883230113822/1050509599599505528 The UI is being actively worked on, yes it’ll be growing more features as time goes on.

Graph View

Backlinks