DBConnection.start_link
start_link
, go back to DBConnection module for more information.
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 toargs
ornil
where only returned options are passed to connect callback (default:nil
):after_connect
- A function to run on connect usingrun/3
, either a 1-arity fun,{module, function, args}
withDBConnection.t/0
prepended toargs
ornil
(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 inGenServer.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 theSupervisor
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
TheDBConnection.ConnectionError
struct which triggered the event.:pool
The connection pool in which this event was triggered.