Connection

The connection class is responsible for managing the lifecycle of a given database connection. You can access the connection instance using the Database.manager property.

import Database from '@ioc:Adonis/Lucid/Database'

const { connection } = Database.manager.get('primary')

The connection name is derived from the config/database.ts file. In the following example, primary is the connection name.

{
  connections: {
    primary: {
      client: 'pg',
      connection: {
        // ...
      },
    }
  }
}

Methods/properties

Following is the list of the available methods and properties on the connection class. The user land code doesn't interact with the connection instance directly, as the following methods are invoked internally.

connect

Invoking the connect method instantiates a new Knex.js instance. If you are using read/write replicas then two Knex.js instances are created, one for write and one for read.

connection.connect()

disconnect

The disconnect method disconnects the underlying driver connection and destroys the Knex instance(s).

await connection.disconnect()

getReport

Returns the health check report for given connection.

const report = await connection.getReport()

pool/readPool

Reference to the underlying tarnjs pool object . The property is available only after the connect method is called.

connection.pool.numFree()
connection.readPool.numFree()

client/readClient

Reference to the underlying Knex instance. The property is available only after the connect method is called.

connection.client
connection.readClient

hasReadWriteReplicas

A boolean to know if the connection is using read-write replicas or not.

connection.hasReadWriteReplicas

ready

A boolean to know if the connection is ready to make queries. If not, then you must call the connect method.

if (!connection.ready) {
  connection.connect()
}

config

Reference to the config object

connection.config

name

The reference to the connection name

connection.name

Events

Following is the list of events emitted by the connection class.

connect

Emitted when the connect method is called

connection.on('connect', (self) => {
  console.log(self === connection) // true
})

error

Emitted when the unable to establish the connection

connection.on('error', (error, self) => {
  console.log(error)
})

disconnect

Emitted when the connection and Knex instance(s) have been destroyed.

connection.on('disconnect', (self) => {
  console.log(self)
})

disconnect:error

Emitted when the unable to disconnect or destroy Knex instance(s).

connection.on('disconnect:error', (error, self) => {
  console.log(error)
})