Create a project​

How does this help me?​

Once you’ve initialized 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();

What do you mean link?​

The “link” is just metaphor that makes projects easier to think about; in practice, it’s just a bit of metadata we store in the EdgeDB config directory. When the CLI or client libraries try to connect to an instance, they read the currect directory and cross-reference it against the list of initialized projects. If there’s a match, it reads the credentials of the project’s associated instance and auto-connects.

How does this work in production?​

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.

What’s the edgedb.toml file?​

The most important role of edgedb.toml is to mark a directory as an instance-linked project, but it can also specify the server version and the schema directory for a project. The server version value in the generated edgedb.toml is determined by the EdgeDB version you selected when you ran edgedb project init.

Read our reference documentation on edgedb.toml to learn more.

How do I use edgedb project for existing codebases?​

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?

How does this make projects more portable?​

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.

How do I unlink a project?​

If you want to remove the link between your project and its linked instance, run edgedb project unlink anywhere inside the project. This doesn’t affect the instance, it continues running as before. After unlinking, can run edgedb project init inside project again to create or select a new instance.

$ 

edgedb project init

No `edgedb.toml` found in `~/path/to/my_project` or above.
Do you want to initialize a new project? [Y/n]
> Y
Specify the name of EdgeDB instance to use with this project
[default: my_project]:
> my_project
Checking EdgeDB versions...
Specify the version of EdgeDB to use with this project [default: 2.x]:
> 2.x

How do I use edgedb project with a non-local instance?​

Sometimes you may want to work on an EdgeDB instance that is just not in your local development environment, like you may have a second workstation, or you want to test against a staging database shared by the team.

This is totally a valid case and EdgeDB fully supports it!

Before running edgedb project init, you just need to create a local link to the remote EdgeDB instance first:

$ 

edgedb instance link

Specify the host of the server [default: localhost]:
> 192.168.4.2
Specify the port of the server [default: 5656]:
> 10818
Specify the database user [default: edgedb]:
> edgedb
Specify the database name [default: edgedb]:
> edgedb
Unknown server certificate: SHA1:c38a7a90429b033dfaf7a81e08112a9d58d97286. Trust? [y/N]
> y
Password for 'edgedb':
Specify a new instance name for the remote server [default: 192_168_4_2_10818]:
> staging_db
Successfully linked to remote instance. To connect run:
  edgedb -I staging_db

Then you could run the normal edgedb project init and use staging_db as the instance name.