Database Connection Settings

Craft supports several database connection settings that give you control over how Craft connects to the database.

Ultimately, database connection settings must be set from config/db.php, but we recommend you initially set them as environment variables (such as in your .env file), and then pull the environment variable value into config/db.php using getenv() (opens new window).

For example, in a new Craft 3 project, your .env file should define these environment variables:

ENVIRONMENT="dev"
SECURITY_KEY=""
DB_DRIVER="mysql"
DB_SERVER="<host>"
DB_PORT="<port>"
DB_DATABASE="<dbname>"
DB_USER="root"
DB_PASSWORD=""
DB_SCHEMA="public"
DB_TABLE_PREFIX=""

The variables that start with DB_ are database connection settings, and they get pulled into config/db.php like this:

return [
    'driver' => getenv('DB_DRIVER'),
    'server' => getenv('DB_SERVER'),
    'port' => getenv('DB_PORT'),
    'database' => getenv('DB_DATABASE'),
    'user' => getenv('DB_USER'),
    'password' => getenv('DB_PASSWORD'),
    'schema' => getenv('DB_SCHEMA'),
    'tablePrefix' => getenv('DB_TABLE_PREFIX'),
];

You may also provide a DB_DSN environment variable. If defined, Craft will use that.

We recommend this environment variable approach for two reasons:

It keeps sensitive information out of your project’s codebase. (.env files should never be shared or committed to Git.)
It makes collaborating with other developers easier, as each developer can define their own settings without overwriting someone else’s settings.

Here’s the full list of database connection settings that Craft supports:

# `attributes`

Allowed types: array (opens new window)
Default value: []
Defined by: DbConfig::$attributes (opens new window)

An array of key => value pairs of PDO attributes to pass into the PDO constructor.

# `charset`

Allowed types: string (opens new window)
Default value: 'utf8'
Defined by: DbConfig::$charset (opens new window)

The charset to use when creating tables.

# `collation`

Allowed types: string (opens new window), null (opens new window)
Default value: null
Defined by: DbConfig::$collation (opens new window)
Since: 3.6.4

The collation to use when creating tables.

# `database`

Allowed types: string (opens new window), null (opens new window)
Default value: null
Defined by: DbConfig::$database (opens new window)

The name of the database to select.

# `driver`

Allowed types: string (opens new window), null (opens new window)
Default value: null
Defined by: DbConfig::$driver (opens new window)

The database driver to use. Either mysql for MySQL or pgsql for PostgreSQL.

# `dsn`

Allowed types: string (opens new window), null (opens new window)
Default value: null
Defined by: DbConfig::$dsn (opens new window)

The Data Source Name (“DSN”) that tells Craft how to connect to the database.

# `password`

Allowed types: string (opens new window)
Default value: ''
Defined by: DbConfig::$password (opens new window)

The database password to connect with.

# `port`

Allowed types: integer (opens new window), null (opens new window)
Default value: null
Defined by: DbConfig::$port (opens new window)

The database server port. Defaults to 3306 for MySQL and 5432 for PostgreSQL.

# `schema`

Allowed types: string (opens new window)
Default value: 'public'
Defined by: DbConfig::$schema (opens new window)

The schema that Postgres is configured to use by default (PostgreSQL only).

# `server`

Allowed types: string (opens new window), null (opens new window)
Default value: null
Defined by: DbConfig::$server (opens new window)

The database server name or IP address. Usually localhost or 127.0.0.1.

# `setSchemaOnConnect`

Allowed types: boolean (opens new window)
Default value: false
Defined by: DbConfig::$setSchemaOnConnect (opens new window)
Since: 3.7.27

Whether the schema (opens new window) should be explicitly used for database queries (PostgreSQL only).

# `tablePrefix`

Allowed types: string (opens new window)
Default value: ''
Defined by: DbConfig::$tablePrefix (opens new window)

If you’re sharing Craft installs in a single database (MySQL) or a single database and using a shared schema (PostgreSQL), you can set a table prefix here to avoid per-install table naming conflicts. This can be no more than 5 characters, and must be all lowercase.

# `unixSocket`

Allowed types: string (opens new window), null (opens new window)
Default value: null
Defined by: DbConfig::$unixSocket (opens new window)

MySQL only. If this is set, the CLI connection string (used for yiic) will connect to the Unix socket instead of the server and port. If this is specified, then server and port settings are ignored.

# `url`

Allowed types: string (opens new window), null (opens new window)
Default value: null
Defined by: DbConfig::$url (opens new window)

The database connection URL, if one was provided by your hosting environment.

# `useUnbufferedConnections`

Allowed types: boolean (opens new window)
Default value: false
Defined by: DbConfig::$useUnbufferedConnections (opens new window)
Since: 3.7.0

Whether batched queries should be executed on a separate, unbuffered database connection.

# `user`

Allowed types: string (opens new window)
Default value: 'root'
Defined by: DbConfig::$user (opens new window)

The database username to connect with.

Database Connection Settings

# attributes

# charset

# collation

# database

# driver

# dsn

# password

# port

# schema

# server

# setSchemaOnConnect

# tablePrefix

# unixSocket

# url

# useUnbufferedConnections

# user

Was this page helpful?

# `attributes`

# `charset`

# `collation`

# `database`

# `driver`

# `dsn`

# `password`

# `port`

# `schema`

# `server`

# `setSchemaOnConnect`

# `tablePrefix`

# `unixSocket`

# `url`

# `useUnbufferedConnections`

# `user`