EdgeDB is an open-source object-relational database built on top of PostgreSQL. The goal of EdgeDB is to empower its users to build safe and efficient software with less effort.
EdgeDB features:
- strict, strongly typed schema;
- powerful and expressive query language;
- rich standard library;
- built-in support for schema migrations;
- native GraphQL support.
See edgedb.com and the documentation for more information about EdgeDB and how to get started. This README contains information specifically on how to use the EdgeDB server Docker image.
This image is primarily intended to be used directly when there is a
requirement to use Docker containers, such as in production, or in a
development setup that involves multiple containers orchestrated by
Docker Compose or a similar tool. Otherwise, using the edgedb server
CLI on the host system is the recommended way to install and run
EdgeDB servers.
The simplest way to run the image (without data persistence) is this:
$ docker run --name edgedb -e EDGEDB_PASSWORD=secret \
-e EDGEDB_GENERATE_SELF_SIGNED_CERT=1 -d edgedb/edgedb
See the Customization section below for the meaning of
the EDGEDB_PASSWORD
variable and other options.
Then, to authenticate to the EdgeDB instance and store the credentials in a Docker volume, run:
$ docker run -it --rm --link=edgedb -e EDGEDB_PASSWORD=secret \
-v edgedb-cli-config:/.config/edgedb edgedb/edgedb-cli \
-H edgedb instance link my_instance
Now, to open an interactive shell to the database instance run this:
$ docker run -it --rm --link=edgedb \
-v edgedb-cli-config:/.config/edgedb edgedb/edgedb-cli \
-I my_instance
If you want the contents of the database to survive container restarts,
you must mount a persistent volume at the path specified by
EDGEDB_DATADIR
(/var/lib/edgedb/data
) by default. For example:
$ docker run \
--name edgedb -e EDGEDB_PASSWORD=secret \
-e EDGEDB_GENERATE_SELF_SIGNED_CERT=1 \
-v /my/data/directory:/var/lib/edgedb/data \
-d edgedb/edgedb
Note that on Windows you must use a Docker volume instead:
$ docker volume create --name=edgedb-data
$ docker run \
--name edgedb -e EDGEDB_PASSWORD=secret \
-e EDGEDB_GENERATE_SELF_SIGNED_CERT=1 \
-v edgedb-data:/var/lib/edgedb/data \
-d edgedb/edgedb
It is also possible to run an edgedb
container on a remote PostgreSQL
cluster specified by EDGEDB_POSTGRES_DSN
. See below for details.
A derived image may include application schema and migrations in
/dbschema
, in which case the container will attempt to apply the
schema migrations found in /dbschema/migrations
, unless
the EDGEDB_SKIP_MIGRATIONS
environment variable is set.
The behavior of the edgedb
image can be customized via environment
variables and initialization scripts.
When an edgedb
container starts on the specified data directory or remote
Postgres cluster for the first time, initial instance setup is performed.
This is called the bootstrap phase.
The following environment variables affect the bootstrap only and have no
effect on subsequent container runs. The _FILE
variants of the variables
allow passing the value via a file mounted inside a container.
Determines the password used for the default superuser account.
A variant of EDGEDB_PASSWORD
, where the specified value is a hashed password
verifier instead of plain text.
Optionally specifies the name of the default superuser account. Defaults to
edgedb
if not specified.
Set this option to 1
to tell the server to automatically generate a
self-signed certificate with key file in the EDGEDB_DATADIR
(if present,
see below), and echo the certificate content in the logs. If the certificate
file exists, the server will use it instead of generating a new one.
Self-signed certificates are usually used in development and testing, you should likely provide your own certificate and key file with the variables below.
Specify your own TLS certificate and key files to run the server. Note, the
value of these two variables are path inside the Docker container, so you may
want to mount your certificate files into the container with the -v
option.
Optionally specifies the name of a default database that is created during
bootstrap. Defaults to edgedb
if not specified.
Optionally specifies the authentication method used by the server instance.
Supported values are "scram"
(the default) and "trust"
. When set to
"trust"
, the database will allow complete unauthenticated access for all
who have access to the database port. In this case the EDGEDB_PASSWORD
(or equivalent) setting is not required.
Use at your own risk and only for testing.
Specifies one or more EdgeQL statements to run at bootstrap. If specified,
overrides EDGEDB_PASSWORD
, EDGEDB_PASSWORD_HASH
, EDGEDB_USER
and
EDGEDB_DATABASE
. Useful to fine-tune initial user and database creation,
and other initial setup. If neither the EDGEDB_BOOTSTRAP_COMMAND
variable
or the EDGEDB_BOOTSTRAP_SCRIPT_FILE
are explicitly specified, the container
will look for the presence of /edgedb-bootstrap.edgeql
in the container
(which can be placed in a derived image).
To perform additional initialization, a derived image may include one ore
more *.edgeql
, or *.sh
scripts, which are executed in addition to and
after the initialization specified by the environment variables above
or the /edgedb-bootstrap.edgeql
script.
Unlike options listed in the Initial container setup section above, the configuration documented below applies to all container invocations. It can be specified either as environment variables or command-line arguments.
Specifies the network port on which EdgeDB will listen inside the container.
The default is 5656
. This usually doesn't need to be changed unless you
run in host
networking mode.
Specifies the network interface on which EdgeDB will listen inside the
container. The default is 0.0.0.0
, which means all interfaces. This
usually doesn't need to be changed unless you run in host
networking mode.
Specifies a path within the container in which the database files are located.
Defaults to /var/run/edgedb/data
. The container needs to be able to
change the ownership of the mounted directory to edgedb
. Cannot be specified
at the same time with EDGEDB_POSTGRES_DSN
.
Specifies a PostgreSQL connection string in the
URI format.
If set, the PostgreSQL cluster specified by the URI is used instead of the
builtin PostgreSQL server. Cannot be specified at the same time with
EDGEDB_DATADIR
.
Specifies a path within the container in which EdgeDB will place its Unix socket and other transient files.
Extra arguments to be passed to EdgeDB server.
To perform additional initialization, a derived image may include one ore
more executable files in /docker-entrypoint.d/
, which will get executed
by the container entrypoint before any other processing takes place.