Ask AI

Deploying EdgeDB to

In this guide we show how to deploy EdgeDB using a PostgreSQL cluster as the backend. The deployment consists of two apps: one running Postgres and the other running EdgeDB.

  • account

  • flyctl CLI (install)

Every app must have a globally unique name, including service VMs like Postgres and EdgeDB. Pick a name and assign it to a local environment variable called EDB_APP. In the command below, replace myorg-edgedb with a name of your choosing.

flyctl apps create --name $EDB_APP
New app created: myorg-edgedb

Now let’s use the read command to securely assign a value to the PASSWORD environment variable.

echo -n "> " && read -s PASSWORD

Now let’s assign this password to a Fly secret, plus a few other secrets that we’ll need. There are a couple more environment variables we need to set:

flyctl secrets set \
  EDGEDB_SERVER_TLS_CERT_MODE=generate_self_signed \
  --app $EDB_APP
Secrets are staged for the first deployment

Let’s discuss what’s going on with all these secrets.

  • The EDGEDB_SERVER_BACKEND_DSN_ENV tells the EdgeDB container where to look for the PostgreSQL connection string (more on that below)

  • The EDGEDB_SERVER_TLS_CERT_MODE tells EdgeDB to auto-generate a self-signed TLS certificate.

    You may instead choose to provision a custom TLS certificate. In this case, you should instead create two other secrets: assign your certificate to EDGEDB_SERVER_TLS_CERT and your private key to EDGEDB_SERVER_TLS_KEY.

  • Lastly, EDGEDB_SERVER_PORT tells EdgeDB to listen on port 8080 instead of the default 5656, because prefers 8080 for its default health checks.

Finally, let’s configure the VM size as EdgeDB requires a little bit more than the default VM side provides. Put this in a file called fly.toml in your current directory.:

  image = "edgedb/edgedb"

  memory = "512mb"
  cpus = 1
  cpu-kind = "shared"

Now we need to provision a PostgreSQL cluster and attach it to the EdgeDB app.

If you have an existing PostgreSQL cluster in your organization, you can skip to the attachment step.

Then create a new PostgreSQL cluster. This may take a few minutes to complete.

flyctl pg create --name $PG_APP --vm-size shared-cpu-1x
? Select region: sea (Seattle, Washington (US))
? Specify the initial cluster size: 1
? Volume size (GB): 10
Creating postgres cluster myorg-postgres in organization personal
Postgres cluster myorg-postgres created
    Username:    postgres
    Password:    <random password>
    Hostname:    myorg-postgres.internal
    Proxy Port:  5432
    PG Port: 5433
Save your credentials in a secure place, you won't be able to see them
Monitoring Deployment
--> v0 deployed successfully

In the output, you’ll notice a line that says Machine <machine-id> is created. The ID in that line is the ID of the virtual machine created for your Postgres cluster. We now need to use that ID to scale the cluster since the shared-cpu-1x VM doesn’t have enough memory by default. Scale it with this command:

flyctl machine update <machine-id> --memory 1024 --app $PG_APP -y
Searching for image 'flyio/postgres:14.6' remotely...
image found: img_0lq747j0ym646x35
Image size: 361 MB

Updating machine <machine-id>
  Waiting for <machine-id> to become healthy (started, 3/3)
Machine <machine-id> updated successfully!
==> Monitoring health checks
  Waiting for <machine-id> to become healthy (started, 3/3)

With the VM scaled sufficiently, we can now attach the PostgreSQL cluster to the EdgeDB app:

flyctl pg attach "$PG_APP" \
  --database-user "$PG_ROLE" \
  --app $EDB_APP
Postgres cluster myorg-postgres is now attached to myorg-edgedb
The following secret was added to myorg-edgedb:

Lastly, EdgeDB needs the ability to create Postgres databases and roles, so let’s adjust the permissions on the role that EdgeDB will use to connect to Postgres:

echo "alter role \"$PG_ROLE\" createrole createdb; \quit" \
  | flyctl pg connect --app $PG_APP

Everything is set! Time to start EdgeDB.

flyctl deploy --remote-only --app $EDB_APP
Finished launching new machines
 ✔ Machine e286630dce9638 [app] was created

That’s it! You can now start using the EdgeDB instance located at edgedb://myorg-edgedb.internal in your apps.

If deploy did not succeed:

  1. make sure you’ve created the fly.toml file.

  2. re-run the deploy command

  3. check the logs for more information: flyctl logs --app $EDB_APP

Now we need to persist the auto-generated TLS certificate to make sure it survives EdgeDB app restarts. (If you’ve provided your own certificate, skip this step).

flyctl ssh console --app $EDB_APP -C \
  " --format=toml $EDB_SECRETS" \
| tr -d '\r' | flyctl secrets import --app $EDB_APP

Let’s construct the DSN (AKA “connection string”) for our instance. DSNs have the following format: edgedb://<username>:<password>@<hostname>:<port>. We can construct the DSN with the following components:

  • <username>: the default value — edgedb

  • <password>: the value we assigned to $PASSWORD

  • <hostname>: the name of your EdgeDB app (stored in the $EDB_APP environment variable) suffixed with .internal. Fly uses this synthetic TLD to simplify inter-app communication. Ex: myorg-edgedb.internal.

  • <port>: 8080, which we configured earlier

We can construct this value and assign it to a new environment variable called DSN.


Consider writing it to a file to ensure the DSN looks correct. Remember to delete the file after you’re done. (Printing this value to the terminal with echo is insecure and can leak your password into shell logs.)

echo $DSN > dsn.txt
open dsn.txt
rm dsn.txt

To connect to this instance from another Fly app (say, an app that runs your API server) set the value of the EDGEDB_DSN secret inside that app.

flyctl secrets set \
  --app my-other-fly-app

We’ll also set another variable that will disable EdgeDB’s TLS checks. Inter-application communication is secured by Fly so TLS isn’t vital in this case; configuring TLS certificates is also beyond the scope of this guide.

flyctl secrets set EDGEDB_CLIENT_TLS_SECURITY=insecure \
  --app my-other-fly-app

You can also set these values as environment variables inside your fly.toml file, but using Fly’s built-in secrets functionality is recommended.

If you need to access EdgeDB from outside the network, you’ll need to configure the proxy to let external connections in.

Let’s make sure the [[services]] section in our fly.toml looks something like this:

    http_checks = []
    internal_port = 8080
    processes = ["app"]
    protocol = "tcp"
    script_checks = []
        hard_limit = 25
        soft_limit = 20
        type = "connections"

        port = 5656

        grace_period = "1s"
        interval = "15s"
        restart_limit = 0
        timeout = "2s"

In the same directory, redeploy the EdgeDB app. This makes the EdgeDB port available to the outside world. You can now access the instance from any host via the following public DSN: edgedb://edgedb:$PASSWORD@$

To secure communication between the server and the client, you will also need to set the EDGEDB_TLS_CA environment secret in your application. You can securely obtain the certificate content by running:

flyctl ssh console -a $EDB_APP \
  -C " --format=raw EDGEDB_SERVER_TLS_CERT"

To access the EdgeDB instance from local development machine/laptop, install the Wireguard VPN and create a tunnel, as described on Fly’s Private Networking docs.

Once it’s up and running, use edgedb instance link to create a local alias to the remote instance.

edgedb instance link \
  --trust-tls-cert \
  --dsn $DSN \
  --non-interactive \
Authenticating to edgedb://edgedb@myorg-edgedb.internal:5656/edgedb
Successfully linked to remote instance. To connect run:
  edgedb -I fly

You can now run CLI commands against this instance by specifying it by name with -I fly; for example, to apply migrations:

The command groups edgedb instance and edgedb project are not intended to manage production instances.

edgedb -I fly migrate

Using an HTTP client, you can perform health checks to monitor the status of your EdgeDB instance. Learn how to use them with our health checks guide.