Hazaar DBI Configuration

Hazaar provides a simple and easy to use database abstraction layer that allows you to interact with a variety of database systems in a consistent way. The database abstraction layer is built on top of the PDO extension and provides a simple and easy to use interface for interacting with databases.

Configuring a Database Connection

To use the database abstraction layer you first need to configure a database connection. This is done by creating a database.php file in your application configuration directory. The database configuration file is a PHP file that returns an array containing the connection details for each database you wish to connect to. The database configuration file is loaded automatically by the framework when it is required.

PHP

<?php
return [
    'development' => [
        'type' => 'pgsql',
        'host' => 'localhost',
        'dbname' => 'my_database',
        'user' => 'my_user',
        'password' => 'my_password',
    ],
    'test' => [
        'type' => 'sqlite',
        'file' => 'test.db',
    ],
];

JSON

{
    "development": {
        "type": "pgsql",
        "host": "localhost",
        "dbname": "my_database",
        "user": "my_user",
        "password": "my_password"
    },
    "test": {
        "type": "sqlite",
        "file": "test.db"
    }
}

INI

[development]
type = pgsql
host = localhost
dbname = my_database
user = my_user
password = my_password

[test]
type = sqlite
file = test.db

Configuration Options

The configuration keys available for each connection depend on the PDO driver you choose. Hazaar uses the driver-specific PDO options to build the DSN, so only keys supported by that driver are used for the connection string. For example, a PostgreSQL connection uses values like host, port, dbname, user, and password, while SQLite uses a local database path.

Alongside DSN keys, there are additional optional settings you can use in the connection config:

• type selects the PDO driver (for example, pgsql, sqlite).
• options allows you to pass PDO attributes (keys should match PDO:: constants like ATTR_ERRMODE).
• schema sets the default schema name for drivers that support schemas.
• timezone sets the session timezone after connecting.
• encrypt enables transparent table/column encryption (see the DBI encryption docs).
• master enables PostgreSQL replication support for read/write splitting.

The database configuration file can contain multiple database configurations. The default configuration to use is determined by the current APPLICATION_ENV environment variable. If the APPLICATION_ENV environment variable is not set, the default configuration is development.

$db = Hazaar\DBI\Adapter::create();

Alternatively, you can specify the configuration to use by passing the name of the configuration to Hazaar\DBI\Adapter::create().

$db = Hazaar\DBI\Adapter::create('test');

Lastly, you can also specify the configuration as an array. This is useful for quick testing or when you don't want to use a configuration file but is not recommended for production use.

$db = Hazaar\DBI\Adapter::create(array(
    'type' => 'pgsql',
    'host' => 'localhost',
    'dbname' => 'test',
    'user' => 'test',
    'password' => 'test'
));

PostgreSQL Replication

If your database host is running PostgreSQL 9.0+ replication then Hazaar has some extra magic for you. It's possible to use a read-only slave for most queries and then have Hazaar's database adapter automatically send all write operations to the master. Without the application knowing, or caring.

To achieve this, all you need to do is add the following to your database.php file:

'master' => 'master-db-host',

Add this parameter to the relevant environment configuration in your database.php file and the Hazaar DB adapter will take care of the rest.

How does it work?

Basically, if the db.master parameter is set, then the adapter knows to check if the db.host is a slave by executing thePGSQL specific query:

SELECT pg_is_in_recovery()

This query indicates that the host is in recovery mode, meaning it is a replication slave. If this is true, then the adapter will create a second connection using the main connection parameters but switches out the host parameter with the value in db.master.

After that, any write operations will use the second connection which will write to the master.