Connection manager
The connections manager class
is responsible for managing one or more database connection
instances. You can access the manager
from the Database module.
import Database from '@ioc:Adonis/Lucid/Database'
const manager = Database.manager
Methods/properties
Following is the list of methods/properties available on the connection manager class. Usually, you don't have to interact with the manager directly, as the following methods are invoked internally.
add
Register a new connection to the manager by providing the connection name
and it's configuration. The database module automatically registers all the connections defined inside the config/database.ts
file.
const name = 'pg'
const config = {
client: 'pg',
connection: {
// ...
},
healthCheck: true
}
Database.manager.add(name, config)
connect
The connect
method instantiates a pre-registered connection by its name. Under the hood, it calls the connect method on the Connection class
.
Calling this method multiple times results is a no-op.
Database.manager.connect('pg')
get
Returns the connection node for a pre-registered connection by its name.
const {
name,
state,
connection,
config
} = Database.manager.get('pg')
Following is the list of available properties.
name
The name of the connection, as defined at the time of adding it.
config
Reference to the registered config
connection
Reference to the underlying connection class instance.
state
The current state of the connection.
registered
: The connection has been registered using theadd
method.open
: The connection is open to accept new requests.closing
: In the process of closing the connection. No new queries can be created or executed from this connection anymore.closed
: The connection has been closed and cannot accept any more request. You must call theconnect
method again.migrating
: The connection config has been patched and it is migrating to create a new connection instance with the new config.
has
Returns a boolean telling if the connection has been registered with the manager or not.
if (!Database.manager.has('pg')) {
Database.manager.add('pg', {})
}
isConnected
Find if a connection is in open
state or not.
if (!Database.manager.isConnected('pg')) {
Database.manager.connect('pg')
}
patch
The patch
method allows you to update the config for a given connection without closing the existing connection or aborting the ongoing queries.
After the connection has been patched, all new queries will use the newer config.
The patch
method is really helpful when you have a multi-tenant app and you want to register connections on the fly for the tenants.
Database.manager.patch('pg', {
client: 'pg',
connection: {},
})
// Uses new config
Database.manager.connect('pg')
close
Close a given connection. The connection manager will still keep the connection node until you release the connection explicitly by passing the second argument.
// Close
await Database.manager.close('pg')
Database.manager.has('pg') // true
// Close + Release
await Database.manager.close('pg', true)
Database.manager.has('pg') // false
closeAll
Close all registered connections. A boolean parameter can be passed to also release the connection.
await Database.manager.closeAll()
await Database.manager.closeAll(true)
release
Release a connection from the managed list of connections. The connection will be closed automatically (if not already closed).
await Database.manager.release(true)
report
Returns the health check report for all the registered connections.
const report = await Database.manager.report()
console.log(report.name)
console.log(report.health.healthy)
Events
Following is the list of events emitted by the connection manager class.
db:connection:connect
Emitted when the connect
method is called
Database.manager.on('db:connection:connect', (connection) => {
console.log(self === connection) // true
})
db:connection:error
Emitted when the unable to establish the connection
Database.manager.on('db:connection:error', (error, connection) => {
console.log(connection)
})
db:connection:disconnect
Emitted when the connection and Knex instance(s) have been destroyed.
Database.manager.on('db:connection:disconnect', (connection) => {
console.log(connection)
})