Projects are the most convenient way to develop applications with EdgeDB. This is the recommended approach.

To get started, navigate to the root directory of your codebase in a shell and run edgedb project init. 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-rc3]:
> # 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.

Let’s unpack that.

  1. 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.

  2. Then it asks you how you’d like to run EdgeDB: locally, in a Docker image, or in the cloud (coming soon!).

  3. 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).

  4. Then it links the current directory to that instance. A “link” is represented as some metadata stored in EdgeDB’s config directory—feel free to peek inside to see how it’s stored.

  5. Then it creates an edgedb.toml file, which marks this directory as an EdgeDB project.

  6. Finally, it creates a dbschema directory and a dbschema/schema.esdl schema file (if they don’t already exist).

Once you’ve initialize a project, your project directory is linked to a particular instance. That means, 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, reads the current directory, and checks if it’s associated with an existing project. If it is, it looks up the credentials of the linked instance (they’re stored in a standardized location), uses that information to connect to the instance, and applies the command.

Similarly, all client libraries will use the same mechanism to auto-connect inside project directories, no hard-coded credentials required.

import edgedb from "edgedb";

const pool = edgedb.createPool("my_instance");
const pool = edgedb.createPool();

It doesn’t. Projects are intended as a convenient development tool that make it easier to develop EdgeDB-backed applications locally. In production, you should provide instance credentials to your client library of choice using environment variables. See Connection parameters page for more information.

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 configuration setting: server-version, This lets you specify the EdgeDB version expected by this project. The value in the created edgedb.toml is determined by the EdgeDB version you selected during the setup process.

If you already have an project on your computer that uses EdgeDB, follow these steps to convert it into an EdgeDB project:

  1. Navigate into the project directory (the one containing you dbschema directory).

  2. Run edgedb project init.

  3. 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?

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?

Just run 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, apply all unapplied migrations. Then you can start up the application and it should work out of the box.