Struct Builder

pub struct Builder { /* private fields */ }

A builder used to create connections.

Implementations

impl Builder

pub async fn from_env() -> Result<Builder, Error>

Initializes a Builder using environment variables or project config.

pub async fn read_project( &mut self, override_dir: Option<&Path>, search_parents: bool, ) -> Result<&mut Self, Error>

Reads the project config if it exists.

Projects are initialized using the command-line tool:

edgedb project init

Linking to an already running EdgeDB is also possible:

edgedb project init --link

Returns a boolean value indicating whether the project was found.

pub fn is_initialized(&self) -> bool

Indicates whether credentials are set for this builder.

pub async fn read_env_vars(&mut self) -> Result<&mut Self, Error>

Read environment variables and set respective configuration parameters.

This function initializes the builder if one of the following is set:

• EDGEDB_CREDENTIALS_FILE
• EDGEDB_INSTANCE
• EDGEDB_DSN
• EDGEDB_HOST or EDGEDB_PORT

If it finds one of these then it will reset all previously set credentials.

If one of the following are set:

• EDGEDB_DATABASE
• EDGEDB_USER
• EDGEDB_PASSWORD

Then the value of that environment variable will be used to set just the parameter matching that environment variable.

The insecure_dev_mode and connection parameters are never modified by this function for now.

pub fn read_extra_env_vars(&mut self) -> Result<&mut Self, Error>

Read environment variables that aren’t credentials

pub fn credentials( &mut self, credentials: &Credentials, ) -> Result<&mut Self, Error>

Set all credentials.

This marks the builder as initialized.

pub async fn read_instance(&mut self, name: &str) -> Result<&mut Self, Error>

Read credentials from the named instance.

Named instances are created using the command-line tool, either directly:

edgedb instance create <name>

or when initializing a project:

edgedb project init

In the latter case you should use read_project() instead if possible.

This will mark the builder as initialized (if reading is successful) and overwrite all credentials. However, insecure_dev_mode, pools sizes, and timeouts are kept intact.

pub async fn read_credentials( &mut self, path: impl AsRef<Path>, ) -> Result<&mut Self, Error>

Read credentials from a file.

This will mark the builder as initialized (if reading is successful) and overwrite all credentials. However, insecure_dev_mode, pools sizes, and timeouts are kept intact.

pub async fn read_dsn(&mut self, dsn: &str) -> Result<&mut Self, Error>

Initialize credentials using data source name (DSN).

DSN’s that EdgeDB like are URL with egdgedb::/scheme:

edgedb://user:secret@localhost:5656/

All the credentials can be specified using a DSN, although parsing a DSN may also lead to reading of environment variables (if query arguments of the for *_env are specified) and local files (for query arguments named *_file).

This will mark the builder as initialized (if reading is successful) and overwrite all the credentials. However, insecure_dev_mode, pools sizes, and timeouts are kept intact.

pub fn uninitialized() -> Builder

Creates a new builder that has to be intialized by calling some methods.

This is only useful if you have connections to multiple unrelated databases, or you want to have total control of the database initialization process.

Usually, Builder::from_env() should be used instead.

pub fn as_credentials(&self) -> Result<Credentials, Error>

Extract credentials from the Builder so they can be saved as JSON.

pub fn get_host(&self) -> &str

Get the host this builder is configured to connect to.

For unix-socket-configured builder (only if admin_socket feature is enabled) returns “localhost”

pub fn get_port(&self) -> u16

Get the port this builder is configured to connect to.

pub fn host_port( &mut self, host: Option<impl Into<String>>, port: Option<u16>, ) -> &mut Self

Initialize credentials using host/port data.

If either of host or port is None, they are replaced with the default of localhost and 5656 respectively.

This will mark the builder as initialized and overwrite all the credentials. However, insecure_dev_mode, pools sizes, and timeouts are kept intact.

pub fn get_user(&self) -> &str

Get the user name for SCRAM authentication.

pub fn user(&mut self, user: impl Into<String>) -> &mut Self

Set the user name for SCRAM authentication.

pub fn password(&mut self, password: impl Into<String>) -> &mut Self

Set the password for SCRAM authentication.

pub fn database(&mut self, database: impl Into<String>) -> &mut Self

Set the database name.

pub fn get_database(&self) -> &str

Get the database name.

pub fn wait_until_available(&mut self, time: Duration) -> &mut Self

Set the time to wait for the database server to become available.

This works by ignoring certain errors known to happen while the database is starting up or restarting (e.g. “connection refused” or early “connection reset”).

Note: the amount of time establishing a connection can take is the sum of wait_until_available plus connect_timeout

pub fn connect_timeout(&mut self, timeout: Duration) -> &mut Self

A timeout for a single connect attempt.

The default is 10 seconds. A subsecond timeout should be fine for most networks. However, in some cases this can be much slower. That’s because this timeout includes authentication, during which:

• The password is checked (slow by design).
• A compiler process is launched (slow now, may be optimized later).

So in a concurrent case on slower VMs (such as CI with parallel tests), 10 seconds is more reasonable default.

The wait_until_available setting should be larger than this value to allow multiple attempts.

Note: the amount of time establishing a connection can take is the sum of wait_until_available plus connect_timeout

pub fn pem_certificates( &mut self, cert_data: &String, ) -> Result<&mut Self, Error>

Set the allowed certificate as a PEM file.

pub fn tls_security(&mut self, value: TlsSecurity) -> &mut Self

Updates the client TLS security mode.

By default, the certificate chain is always verified; but hostname verification is disabled if configured to use only a specific certificate, and enabled if root certificates are used.

pub fn insecure_dev_mode(&mut self, value: bool) -> &mut Self

Enables insecure dev mode.

This disables certificate validation entirely.

pub fn display_addr<'x>(&'x self) -> impl Display + 'x

A displayable form for an address this builder will connect to

pub fn build(&self) -> Result<Config, Error>

Build connection and pool configuration object

pub fn max_connections(&mut self, value: usize) -> &mut Self

Set the maximum number of underlying database connections.

Trait Implementations

impl Clone for Builder

fn clone(&self) -> Builder

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Builder

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.