DBConnection.start_link

You're seeing just the function start_link, go back to DBConnection module for more information.
Link to this function

start_link(conn_mod, opts)

View Source

Specs

start_link(module(), opts :: Keyword.t()) :: GenServer.on_start()

Starts and links to a database connection process.

By default the DBConnection starts a pool with a single connection. The size of the pool can be increased with :pool_size. A separate pool can be given with the :pool option.

Options

  • :backoff_min - The minimum backoff interval (default: 1_000)
  • :backoff_max - The maximum backoff interval (default: 30_000)
  • :backoff_type - The backoff strategy, :stop for no backoff and to stop, :exp for exponential, :rand for random and :rand_exp for random exponential (default: :rand_exp)
  • :configure - A function to run before every connect attempt to dynamically configure the options, either a 1-arity fun, {module, function, args} with options prepended to args or nil where only returned options are passed to connect callback (default: nil)
  • :after_connect - A function to run on connect using run/3, either a 1-arity fun, {module, function, args} with DBConnection.t/0 prepended to args or nil (default: nil)
  • :after_connect_timeout - The maximum time allowed to perform function specified by :after_connect option (default: 15_000)
  • :connection_listeners - A list of process destinations to send notification messages whenever a connection is connected or disconnected. See "Connection listeners" below
  • :name - A name to register the started process (see the :name option in GenServer.start_link/3)
  • :pool - Chooses the pool to be started
  • :pool_size - Chooses the size of the pool
  • :idle_interval - Controls the frequency we ping the database when the connection is idle. Defaults to 1000ms.
  • :queue_target and :queue_interval - See "Queue config" below
  • :max_restarts and :max_seconds - Configures the :max_restarts and :max_seconds for the connection pool supervisor (see the Supervisor docs)
  • :show_sensitive_data_on_connection_error - By default, DBConnection hides all information during connection errors to avoid leaking credentials or other sensitive information. You can set this option if you wish to see complete errors and stacktraces during connection errors

Example

{:ok, conn} = DBConnection.start_link(mod, [idle_interval: 5_000])

Queue config

Handling requests is done through a queue. When DBConnection is started, there are two relevant options to control the queue:

  • :queue_target in milliseconds, defaults to 50ms
  • :queue_interval in milliseconds, defaults to 1000ms

Our goal is to wait at most :queue_target for a connection. If all connections checked out during a :queue_interval takes more than :queue_target, then we double the :queue_target. If checking out connections take longer than the new target, then we start dropping messages.

For example, by default our target is 50ms. If all connections checkouts take longer than 50ms for a whole second, we double the target to 100ms and we start dropping messages if the time to checkout goes above the new limit.

This allows us to better plan for overloads as we can refuse requests before they are sent to the database, which would otherwise increase the burden on the database, making the overload worse.

Connection listeners

The :connection_listeners option allows one or more processes to be notified whenever a connection is connected or disconnected. A listener may be a remote or local PID, a locally registered name, or a tuple in the form of {registered_name, node} for a registered name at another node.

Each listener process may receive the following messages where pid identifies the connection process:

  • {:connected, pid}
  • {:disconnected, pid}

Telemetry

A [:db_connection, :connection_error] event is published whenever a connection checkout receives a %DBConnection.ConnectionError{}.

Measurements:

  • :error A fixed-value measurement which always measures 1.

Metadata

  • :connection_listeners The list of connection listeners (as described above) passed to the connection pool. Can be used to relay this event to the proper connection listeners.

  • :connection_error The DBConnection.ConnectionError struct which triggered the event.

  • :pool The connection pool in which this event was triggered.