Database Setup & Configuration
Relevant source files
The following files were used as context for generating this wiki page:
CodeIgniter 4 provides a robust database abstraction layer that simplifies connecting to and interacting with your database. Configuration is centralized and flexible, allowing for different settings across multiple environments (e.g., development, testing, production). The primary configuration is handled through a dedicated configuration file, which defines connection parameters for various database groups.
This system is designed to be easily accessible throughout the application, either by loading it automatically or by instantiating connections manually. Once configured, the connection can be used by other core components like the Query Builder and Database Migrations to manage data and schema.
Sources: source/database/configuration.rst:3-10, app/Config/Database.php
Core Configuration
Database configuration is primarily managed within the app/Config/Database.php file. This file contains a Database class that extends Config\BaseConfig and holds all connection settings for the application.
Sources: app/Config/Database.php:1-12, source/database/configuration.rst:12-14
Configuration Properties
The Database class defines several key public properties that control the default behavior of the database layer.
| Property | Type | Description | Default Value |
|---|---|---|---|
$defaultGroup | string | The default database group to use when a specific group is not provided. | 'default' |
$testsGroup | string | The database group to use when running tests. | 'tests' |
These properties determine which connection group is used by default for application logic and for automated testing, respectively.
Sources: app/Config/Database.php:21-29
Connection Groups
The configuration file allows you to define multiple "groups" of connection settings. By default, two groups are provided: default for general application use and tests for running feature and system tests. Each group is an array of connection parameters stored in a public property with the same name as the group (e.g., $default, $tests).
The following diagram illustrates the structure of the database configuration class.
This diagram shows that the Database configuration class contains properties that point to specific connection group arrays.
Sources: app/Config/Database.php:21-40, source/database/configuration.rst:33-35
Connection Parameters
Each connection group array contains the parameters needed to establish a database connection. You can also use a DSN string for a more compact configuration.
| Parameter | Description | Example |
|---|---|---|
DSN | A full Data Source Name string. If used, individual parameters are ignored. | '' |
hostname | The hostname of your database server. | 'localhost' |
username | The username used to connect to the database. | 'root' |
password | The password used to connect to the database. | '' |
database | The name of the database you want to connect to. | 'ci4' |
DBDriver | The database driver. e.g., MySQLi, Postgre, SQLite3. | 'MySQLi' |
DBPrefix | An optional table prefix which will be added to query builder queries. | '' |
port | The database port number. | 3306 |
pConnect | true/false to use persistent connections. | false |
DBDebug | true/false to enable/disable database errors. | true in development |
charset | The character set used in communicating with the database. | 'utf8' |
DBCollat | The character collation used in communicating with the database. | 'utf8_general_ci' |
swapPre | A default table prefix that should be swapped with DBPrefix. | '' |
encrypt | Whether or not to use an encrypted connection. | false |
compress | Whether or not to use client compression. | false |
strictOn | true/false to force "Strict Mode" connections. | false |
failover | An array of connection settings to try if the main connection fails. | [] |
Sources: app/Config/Database.php:43-73, source/database/configuration.rst:64-156
Connecting to the Database
CodeIgniter provides two primary methods for establishing a database connection based on the defined configuration.
Sources: source/database/connections.rst:3-5
Automatic Connection
The framework can be configured to automatically connect to the database on every page load. This is achieved by calling the database service without any parameters. It will use the group specified in the $defaultGroup property of the configuration file.
// Loads the default database group
$db = \Config\Services::database();
Sources: source/database/connections.rst:12-19
Manual Connection
For greater control, you can connect to the database manually using the db_connect() helper function. This function allows you to specify which connection group to use. If no group is provided, it will connect to the $defaultGroup.
// Connect to the default group
$db = db_connect();
// Connect to the 'tests' group
$testDb = db_connect('tests');
The following sequence diagram shows the process of a manual database connection.
This diagram illustrates how the db_connect() helper uses the Services system, which in turn reads the Database config file to instantiate and return the correct database connection object.
Sources: source/database/connections.rst:26-40
Integration with Framework Components
The database configuration is fundamental to other parts of the framework that require database access, such as the Query Builder and Migrations.
Query Builder
The Query Builder class provides a fluent interface for creating and running database queries. To use it, you first need a database connection instance. From there, you can get a Query Builder instance for a specific table.
// 1. Get the default database connection
$db = \Config\Services::database();
// 2. Get a Query Builder instance for the 'users' table
$builder = $db->table('users');
// 3. Build and run a query
$users = $builder->get()->getResult();
The flow for using the Query Builder is straightforward:
Database Migrations
Database migrations allow for programmatic version control of your database schema. The migration runner relies on the database configuration to connect to the correct database and apply schema changes. Migrations are typically run via the command line using Spark.
# Run all pending migrations on the 'default' database group
php spark migrate
# Specify a different database group
php spark migrate -g tests
The migration command uses the configured database connection to manage the schema's state.
Sources: source/dbmgmt/migration.rst:10-12, 108-111
Summary
CodeIgniter 4's database configuration is managed through the app/Config/Database.php file, which supports multiple connection groups for different environments. This centralized approach simplifies database management and ensures that components like the Query Builder and Migrations can seamlessly access the database. Connections can be established automatically or manually, providing developers with both convenience and fine-grained control over database interactions.
Sources: source/database/configuration.rst, source/database/connections.rst