We’re excited to introduce a new interactive command-line tool that makes it
easier than ever to set up EdgeDB projects:
If you want to try it right now, just upgrade your CLI to the latest version (beta2 or later), open a
terminal, navigate to a project directory (or create a new one), and run
edgedb project init inside.
This will open an interactive tool that will:
dbschema/schema.esdlfile if it doesn’t exist. This is where you will later define your application database schema.
edgedb.tomlconfig file if it doesn’t exist (more on that later).
Prompt you to either create a new EdgeDB instance on your local machine or select an existing one.
Create a link between that intance and your project directory. (More on that later too!)
And you’re off to the races! Start writing your schema in
dbschema/schema.esdl, run a migration, and start writing queries.
Before we dig into how it works, let’s talk about the problems we’re trying to solve.
The EdgeDB CLI experience
Our goal in building EdgeDB is to radically modernize the developer experience of using a database. That philosophy extends to our command line tools as well.
edgedb CLI is comprehensive, intuitive, quick to install, powerful, and
makes the adminstration of EdgeDB databases gloriously easy.
You can install and manage multiple EdgeDB versions with
edgedb server install.
You can spin up multiple instances with
edgedb instance init, each listening on a dedicated auto-assigned port.
You can inspect all existing instances with
edgedb server status.
There’s room for improvement
A few aspects of the EdgeDB developer experience are currently suboptimal.
It’s easy to spin up several active EdgeDB instances running simultaneously,
each listening on different ports. Unfortunately this flexibility introduces a
problem. When you run commands like
edgedb migrate, how does the CLI know
which instance it should run the command against? The answer: connection flags.
To open a REPL:
$ edgedb -I my_instance
Currently, you are required to pass the
-I instance_name flag to virtually
every top-level command:
restore, and more. Not ideal.
Connecting to local instances
When developing an application with one of EdgeDB’s client libraries, there are
a couple ways to connect to a local instance. You can either pass in an
instance name when creating a connection pool
edgedb.createPool("my_instance")) or set the appropriate environment
EDGEDB_INSTANCE). Both options come with
difficulties and drawbacks.
Most full-stack applications depend on the existence of a database—either local or cloud-hosted—to function properly. The database is a dependency of your application. Unfortunately it often requires a non-trivial configuration process to set up a local database properly.
With modern package management tools, we can configure our code dependencies
in a single command with
pip. Wouldn’t it be great if it was
equally easy to configure a database dependency?
We’re thrilled to introduce our solution to all these problems:
How do I use it?
First things first, upgrade your CLI to the latest version (beta2 or later, instructions here).
You can now convert any directory into an EdgeDB project by running
project init inside it. This will create a
dbschema/schema.esdl file (if
it doesn’t already exist) and a new config file called
After configuring your project, you’ll no longer need to use connection flags.
So CLI commands like
edgedb -I my_instance migrate become simply
migrate. Similarly, the EdgeDB’s first-party client libraries will be able to
automatically connect to the configured local instance, no hard-coded instance
names or environment variables required.
By checking in the
edgedb.toml file to version control, you make your
EdgeDB-powered project trivial to configure for anyone with the
just clone, run
edgedb project init, and the project will be ready to run.
Pretty neat! 🎉
How does it work?
edgedb project init starts an interactive command line tool. You’ll
see something like this:
$ edgedb project init No `edgedb.toml` found in this repo or above. Do you want to initialize a new project? [Y/n] > y How would you like to run EdgeDB for this project? 1. Local (native package) 2. Docker > 1 Checking EdgeDB versions... Specify the version of EdgeDB to use with this project [1-beta2]: > # left blank for default Specify the name of EdgeDB instance to use with this project: > my_instance Initializing EdgeDB instance... Bootstrap complete. Server is up and running now. Project initialialized. To connect, run: $ edgedb
Let’s unpack that.
First, it asks you to specify an EdgeDB version, defaulting to the most recent version you have installed. You can also specify a version you don’t have installed, in which case it will be installed.
Then it asks you how you’d like to run EdgeDB: locally, in a Docker image, or in the cloud (coming soon!).
Then it asks for an instance name. If no instance currently exists with this name, it will be created (using the method you specified in #2).
Then it links the current directory to that instance. A record of this link is stored in
~/.edgedb/projects—feel free to peek in that directory to see how it’s represented.
Then it creates an
edgedb.tomlfile, which marks this directory as an EdgeDB project.
Finally, it creates a
dbschemadirectory and a
dbschema/schema.esdlschema file (if they don’t already exist).
The contents of this file aren’t terribly important; this most important thing is simply that the file exists, since it’s how the CLI knows that a directory is an instance-linked EdgeDB project.
But since we’re talking about it,
edgedb.toml currently supports just one
server-version, This lets you specify the EdgeDB
version expected by this project. The value in the created
determined by the EdgeDB version you selected during the setup process.
How does this help me?
In all sorts of ways! From inside an EdgeDB project directory (or in any of its
children), you can run CLI commands without connection flags. For instance,
edgedb -I my_instance migrate becomes simply
edgedb migrate. The CLI
detects the existence of the
edgedb.toml file, looks up the project’s
associated instance, and applies the command accordingly.
Plus, when you use one of EdgeDB’s client libraries (for TypeScript, Python, Rust, or Deno), you no longer need to specify the instance name:
import edgedb from "edgedb"; const pool = edgedb.createPool("my_instance"); const pool = edgedb.createPool();
Like the CLI, the clients scan the filesystem for an
edgedb.toml file and
look up which local instance they should connect to.
How do I use
edgedb project for existing projects?
If you already have an project on your computer that uses EdgeDB, follow these steps to convert it into an EdgeDB project:
Navigate into the project directory (the one containing you
edgedb project init.
When asked for an instance name, enter the name of the existing local instance you use for development.
This will create
edgedb.toml and link your project directory to the
instance. And you’re done! Try running some commands without connection flags.
Feels good, right?
How does this work for cloned projects?
Let’s say you just cloned a full-stack application that uses EdgeDB. The
project directory already contains an
edgedb.toml file. What do you do?
edgedb project init inside the directory! This is the beauty of
edgedb project. You don’t need to worry about creating an instance with a
particular name, running on a particular port, creating users and passwords,
specifying environment variables, or any of the other things that make setting
up local databases hard. Running
edgedb project init will install the
necessary version of EdgeDB (if you don’t already have it installed), create an
instance, synchronize the database schema, and create the instance link. Then
you can start up the application and it should work out of the box.
How do I unlink a project?
If you want to remove the link between your project and its linked instance,
edgedb project unlink anywhere inside the project. This doesn’t affect
the instance, it continues running as before. After unlinking, can run
project init inside project again to create or select a new instance.
Hopefully that gives you a sense of how
edgedb project works and how it can
make your life easier!
We are releasing
edgedb project as part of EdgeDB Beta 2. If you haven’t
already, upgrade to the latest version of the CLI using the instructions in
If you’re looking to get started with EdgeDB, jump into the Quickstart or try our interactive tutorial.
Appendix A: Upgrade your CLI
If you haven’t installed the CLI before, you can do so with a single command:
# macOS/Unix $ curl https://sh.edgedb.com --proto '=https' -sSf1 | sh # Windows $ iwr https://ps1.edgedb.com -useb | iex
If you’ve already installed the CLI, upgrade to the latest version:
$ edgedb self-upgrade