Configuration​

EdgeQL​

The configure command can be used to set the configuration parameters using EdgeQL. For example, you can use the CLI REPL to set the listen_addresses parameter:

gel> 

configure instance set listen_addresses := {'127.0.0.1', '::1'};

CONFIGURE: OK

CLI​

The gel configure command allows modifying the system configuration from a terminal or a script:

$ 

gel configure set listen_addresses 127.0.0.1 ::1

Connection settings​

listen_addresses: multi str

Specifies the TCP/IP address(es) on which the server is to listen for connections from client applications. If the list is empty, the server does not listen on any IP interface at all.

listen_port: int16

The TCP port the server listens on; 5656 by default. Note that the same port number is used for all IP addresses the server listens on.

cors_allow_origins: multi str

Origins that will be calling the server that need Cross-Origin Resource Sharing (CORS) support. Can use * to allow any origin. When HTTP clients make a preflight request to the server, the origins allowed here will be added to the Access-Control-Allow-Origin header in the response.

Resource usage​

effective_io_concurrency: int64

Sets the number of concurrent disk I/O operations that can be executed simultaneously. Corresponds to the PostgreSQL configuration parameter of the same name.

query_work_mem: cfg::memory

The amount of memory used by internal query operations such as sorting. Corresponds to the PostgreSQL work_mem configuration parameter.

shared_buffers: cfg::memory

The amount of memory the database uses for shared memory buffers. Corresponds to the PostgreSQL configuration parameter of the same name. Changing this value requires server restart.

Query planning​

default_statistics_target: int64

Sets the default data statistics target for the planner. Corresponds to the PostgreSQL configuration parameter of the same name.

effective_cache_size: cfg::memory

Sets the planner's assumption about the effective size of the disk cache that is available to a single query. Corresponds to the PostgreSQL configuration parameter of the same name.

Query cacheAdded in v5.0​

auto_rebuild_query_cache: bool

Determines whether to recompile the existing query cache to SQL any time DDL is executed.

query_cache_mode: cfg::QueryCacheMode

Allows the developer to set where the query cache is stored. Possible values:

• cfg::QueryCacheMode.InMemory- All query cache is lost on server restart. This mirrors pre-5.0 EdgeDB behavior.

• cfg::QueryCacheMode.RegInline- The in-memory query cache is also stored in the database as-is so it can be restored on restart.

• cfg::QueryCacheMode.Default- Allow the server to select the best caching option. Currently, it will select InMemory for arm64 Linux and RegInline for everything else.

• cfg::QueryCacheMode.PgFunc- Wraps queries into stored functions in Postgres and reduces backend request size and preparation time.

Query behavior​

allow_bare_ddl: cfg::AllowBareDDL

Allows for running bare DDL outside a migration. Possible values are cfg::AllowBareDDL.AlwaysAllow and cfg::AllowBareDDL.NeverAllow.

When you create an instance, this is set to cfg::AllowBareDDL.AlwaysAllow until you run a migration. At that point it is set to cfg::AllowBareDDL.NeverAllow because it's generally a bad idea to mix migrations with bare DDL.

apply_access_policies: bool

Determines whether access policies should be applied when running queries. Setting this to false effectively puts you into super-user mode, ignoring any access policies that might otherwise limit you on the instance.

This setting can also be conveniently accessed via the "Config" dropdown menu at the top of the Gel UI (accessible by running the CLI command gel ui from within a project). The setting will apply only to your UI session, so you won't have to remember to re-enable it when you're done.

apply_access_policies_pg -> bool

Determines whether access policies should be applied when running queries over SQL adapter. Defaults to false.

force_database_error -> str

A hook to force all queries to produce an error. Defaults to 'false'.

This parameter takes a str instead of a bool to allow more verbose messages when all queries are forced to fail. The database will attempt to deserialize this str into a JSON object that must include a type (which must be a Gel error type name), and may also include message, hint, and details which can be set ad-hoc by the user.

For example, the following is valid input:

'{ "type": "QueryError", "message": "Did not work", "hint": "Try doing something else", "details": "Indeed, something went really wrong" }'

As is this:

'{ "type": "UnknownParameterError" }'

Client connections​

allow_user_specified_id: bool

Makes it possible to set the .id property when inserting new objects.

Enabling this feature introduces some security vulnerabilities:

1. An unprivileged user can discover ids that already exist in the database by trying to insert new values and noting when there is a constraint violation on .id even if the user doesn't have access to the relevant table.

2. It allows re-using object ids for a different object type, which the application might not expect.

Additionally, enabling can have serious performance implications as, on an insert, every object type must be checked for collisions.

As a result, we don't recommend enabling this. If you need to preserve UUIDs from an external source on your objects, it's best to create a new property to store these UUIDs. If you will need to filter on this external UUID property, you may add an index or exclusive constraint on it.

session_idle_timeout -> std::duration

Sets the timeout for how long client connections can stay inactive before being forcefully closed by the server.

Time spent on waiting for query results doesn't count as idling. E.g. if the session idle timeout is set to 1 minute it would be OK to run a query that takes 2 minutes to compute; to limit the query execution time use the query_execution_timeout setting.

The default is 60 seconds. Setting it to <duration>'0' disables the mechanism. Setting the timeout to less than 2 seconds is not recommended.

Note that the actual time an idle connection can live can be up to two times longer than the specified timeout.

This is a system-level config setting.

session_idle_transaction_timeout -> std::duration

Sets the timeout for how long client connections can stay inactive while in a transaction.

The default is 10 seconds. Setting it to <duration>'0' disables the mechanism.

For session_idle_transaction_timeout and query_execution_timeout, values under 1ms are rounded down to zero, which will disable the timeout. In order to set a timeout, please set a duration of 1ms or greater.

session_idle_timeout can take values below 1ms.

query_execution_timeout -> std::duration

Sets a time limit on how long a query can be run.

Setting it to <duration>'0' disables the mechanism. The timeout isn't enabled by default.

For session_idle_transaction_timeout and query_execution_timeout, values under 1ms are rounded down to zero, which will disable the timeout. In order to set a timeout, please set a duration of 1ms or greater.

session_idle_timeout can take values below 1ms.

GEL_DEBUG_HTTP_INJECT_CORS​

Set to 1 to have Gel send appropriate CORS headers with HTTP responses.

GEL_SERVER_ADMIN_UI​

Set to enabled to enable the web-based admininstrative UI for the instance.

Maps directly to the gel-server flag --admin-ui.

GEL_SERVER_ALLOW_INSECURE_BINARY_CLIENTS​

Specifies the security mode of the server's binary endpoint. When set to 1, non-TLS connections are allowed. Not set by default.

GEL_SERVER_ALLOW_INSECURE_HTTP_CLIENTS​

Specifies the security mode of the server's HTTP endpoint. When set to 1, non-TLS connections are allowed. Not set by default.

GEL_SERVER_BACKEND_DSN / _FILE / _ENV​

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 alongside GEL_SERVER_DATADIR. Maps directly to the gel-server flag --backend-dsn.

The _FILE and _ENV variants are also supported.

GEL_SERVER_MAX_BACKEND_CONNECTIONS​

The maximum NUM of connections this Gel instance could make to the backend PostgreSQL cluster. If not set, Gel will detect and calculate the NUM: RAM/100MiB for local Postgres, or pg_settings.max_connections for remote Postgres minus the NUM of --reserved-pg-connections.

GEL_SERVER_BINARY_ENDPOINT_SECURITY​

Specifies the security mode of the server's binary endpoint. When set to optional, non-TLS connections are allowed. Default is tls.

GEL_SERVER_BIND_ADDRESS / _FILE / _ENV​

Specifies the network interface on which Gel will listen. Maps directly to the gel-server flag --bind-address.

The _FILE and _ENV variants are also supported.

GEL_SERVER_BOOTSTRAP_COMMAND​

Useful to fine-tune initial user creation and other initial setup. Maps directly to the gel-server flag --bootstrap-command.

The _FILE and _ENV variants are also supported.

GEL_SERVER_BOOTSTRAP_ONLY​

When set, bootstrap the database cluster and exit. Not set by default.

GEL_SERVER_DATADIR​

Specifies a path where the database files are located. Default is /var/lib/gel/data. Cannot be specified alongside GEL_SERVER_BACKEND_DSN.

Maps directly to the gel-server flag --data-dir.

GEL_SERVER_DEFAULT_AUTH_METHOD / _FILE / _ENV​

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.

This is often useful when setting an admin password on an instance that lacks one.

Use at your own risk and only for development and testing.

The _FILE and _ENV variants are also supported.

GEL_SERVER_HTTP_ENDPOINT_SECURITY​

Specifies the security mode of the server's HTTP endpoint. When set to optional, non-TLS connections are allowed. Default is tls.

GEL_SERVER_INSTANCE_NAME​

Specify the server instance name.

GEL_SERVER_JWS_KEY_FILE​

Specifies a path to a file containing a public key in PEM format used to verify JWT signatures. The file could also contain a private key to sign JWT for local testing.

GEL_SERVER_LOG_LEVEL​

Set the logging level. Default is info. Other possible values are debug, warn, error, and silent.

GEL_SERVER_PORT / _FILE / _ENV​

Specifies the network port on which Gel will listen. Default is 5656. Maps directly to the gel-server flag --port.

The _FILE and _ENV variants are also supported.

GEL_SERVER_RUNSTATE_DIR​

Specifies a path where Gel will place its Unix socket and other transient files. Maps directly to the gel-server flag --runstate-dir.

GEL_SERVER_SECURITY​

When set to insecure_dev_mode, sets GEL_SERVER_DEFAULT_AUTH_METHOD to Trust, and GEL_SERVER_TLS_CERT_MODE to generate_self_signed (unless an explicit TLS certificate is specified). Finally, if this option is set, the server will accept plaintext HTTP connections. Maps directly to the gel-server flag --security.

GEL_SERVER_TLS_CERT_FILE​

The TLS certificate file, exclusive with GEL_SERVER_TLS_CERT_MODE=generate_self_signed. Maps directly to the gel-server flag --tls-cert-file.

GEL_SERVER_TLS_KEY_FILE​

The TLS private key file, exclusive with GEL_SERVER_TLS_CERT_MODE=generate_self_signed. Maps directly to the gel-server flag --tls-key-file.

GEL_SERVER_TLS_CERT_MODE / _FILE / _ENV​

Specifies what to do when the TLS certificate and key are either not specified or are missing.

• When set to require_file, the TLS certificate and key must be specified in the GEL_SERVER_TLS_CERT and GEL_SERVER_TLS_KEY variables and both must exist.

• When set to generate_self_signed a new self-signed certificate and private key will be generated and placed in the path specified by GEL_SERVER_TLS_CERT and GEL_SERVER_TLS_KEY, if those are set. Otherwise, the generated certificate and key are stored as edbtlscert.pem and edbprivkey.pem in GEL_SERVER_DATADIR, or, if GEL_SERVER_DATADIR is not set, they will be placed in /etc/ssl/gel.

Default is generate_self_signed when GEL_SERVER_SECURITY=insecure_dev_mode. Otherwise, the default is require_file.

Maps directly to the gel-server flag --tls-cert-mode.

The _FILE and _ENV variants are also supported.

GEL_DOCKER_ABORT_CODE​

If the process fails, the arguments are logged to stderr and the script is terminated with this exit code. Default is 1.

GEL_DOCKER_APPLY_MIGRATIONS​

The container will attempt to apply migrations in dbschema/migrations unless this variable is set to never.

Values: always (default), never

GEL_DOCKER_BOOTSTRAP_TIMEOUT_SEC​

Sets the number of seconds to wait for instance bootstrapping to complete before timing out. Default is 300.

GEL_DOCKER_LOG_LEVEL​

Change the logging level for the docker container.

Values: trace, debug, info (default), warn, error

GEL_DOCKER_SHOW_GENERATED_CERT​

Shows the generated TLS certificate in console output.

Values: always (default), never

GEL_SERVER_BINARY​

Sets the Gel server binary to run. Default is gel-server.

GEL_SERVER_BOOTSTRAP_COMMAND_FILE​

Run the script when initializing the database. The script is run by the default user within the default branch. May be used with or without GEL_SERVER_BOOTSTRAP_ONLY.

GEL_SERVER_COMPILER_POOL_MODE​

Choose a mode for the compiler pool to scale. fixed means the pool will not scale and sticks to GEL_SERVER_COMPILER_POOL_SIZE, while on_demand means the pool will maintain at least 1 worker and automatically scale up (to GEL_SERVER_COMPILER_POOL_SIZE workers ) and down to the demand.

Values: fixed, on_demand

Default is fixed in production mode and on_demand in development mode.

GEL_SERVER_COMPILER_POOL_SIZE​

When GEL_SERVER_COMPILER_POOL_MODE is fixed, this setting is the exact size of the compiler pool. When GEL_SERVER_COMPILER_POOL_MODE is on_demand, this will serve as the maximum size of the compiler pool.

GEL_SERVER_EMIT_SERVER_STATUS​

Instruct the server to emit changes in status to DEST, where DEST is a URI specifying a file (file://<path>), or a file descriptor (fd://<fileno>). If the URI scheme is not specified, file:// is assumed.

GEL_SERVER_EXTRA_ARGS​

Additional arguments to pass when starting the Gel server.

GEL_SERVER_PASSWORD / _FILE / _ENV​

The password for the default superuser account (or the user specified in GEL_SERVER_USER) will be set to this value. If no value is provided, a password will not be set, unless set via GEL_SERVER_BOOTSTRAP_COMMAND. (If a value for GEL_SERVER_BOOTSTRAP_COMMAND is provided, this variable will be ignored.)

The _FILE and _ENV variants are also supported.

GEL_SERVER_PASSWORD_HASH / _FILE / _ENV​

A variant of GEL_SERVER_PASSWORD, where the specified value is a hashed password verifier instead of plain text.

If GEL_SERVER_BOOTSTRAP_COMMAND is set, this variable will be ignored.

The _FILE and _ENV variants are also supported.

GEL_SERVER_TENANT_ID​

Specifies the tenant ID of this server when hosting multiple Gel instances on one Postgres cluster. Must be an alphanumeric ASCII string, maximum 10 characters long.

GEL_SERVER_UID​

Specifies the ID of the user which should run the server binary. Default is 1.

GEL_SERVER_USER​

If set to anything other than the default username admin, the username specified will be created. The user defined here will be the one assigned the password set in GEL_SERVER_PASSWORD or the hash set in GEL_SERVER_PASSWORD_HASH.