Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Node.js, PHP and APIs

CodeIgniter cannot connect to the MySQL database server

ErrorUnable to connect to your database server using the provided settings.

Short answer

CodeIgniter only reports that its connection failed. Test the same host, port, user and password in a plain mysqli call first: its error number names the cause. It is usually a wrong password (1045), a missing database (1049), a port that localhost ignores, or a wrong driver name.

  • Applies to CodeIgniter 3.1, CodeIgniter 4.5, PHP 8.3, MySQL 8.x
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Take the values from your CodeIgniter config and open the connection with plain mysqli, with exceptions switched on. The error text is the real reason.

    <?php
    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    try {
        new mysqli('127.0.0.1', 'my_user', 'my_password', 'my_db', 3306);
        echo 'connected';
    } catch (mysqli_sql_exception $e) {
        echo $e->getCode() . ': ' . $e->getMessage();
    }
  2. 2Match what you see, then jump to its fix

    1. 1Access denied for user '...'@'...' (using password: YES), error 1045Wrong username or passwordFix
    2. 2Unknown database 'my_db', error 1049The database named in the config does not existFix
    3. 3Can't connect to local MySQL server through socket '...' (2002), or the server on port 3307 is never reachedA port is set but hostname is localhostFix
    4. 4The mysqli test connects but CodeIgniter still fails right awayThe driver name is wrong for the framework versionFix

What does the error look like?

  • Unable to connect to your database server using the provided settings.

Cause 1 of 4

Wrong username or password

1Check

CodeIgniter 3 reads username and password from application/config/database.php. CodeIgniter 4 reads app/Config/Database.php, and values in the .env file override it. A stale .env value is a common surprise.

grep -n "username\|password" application/config/database.php
grep -n "database.default" .env

2Fix

Set the same credentials your mysqli test accepted, in the file the framework really uses.

# CodeIgniter 4 .env
database.default.username = 'my_user'
database.default.password = 'my_password'

3Verify

Reload the page that failed.

curl -I http://localhost:8080/

Confirmed by dev.mysql.com

Did this fix it?

Cause 2 of 4

The database named in the config does not exist

1Check

The login can be right while the database name is wrong or not created on this server. CodeIgniter 4 ships with the placeholder database_name.

mysql -u my_user -p -e "SHOW DATABASES;"

2Fix

Create the database, or set the name in the config to one that exists.

// CodeIgniter 3: application/config/database.php
'database' => 'my_db',
// CodeIgniter 4: app/Config/Database.php or .env
database.default.database = 'my_db'

3Verify

Run the mysqli test again and confirm it prints connected.

php test-mysqli.php

Confirmed by dev.mysql.com

Did this fix it?

Cause 3 of 4

A port is set but hostname is localhost

1Check

With the hostname localhost, mysqli uses a local pipe or Unix socket and the port value is ignored. A MySQL server on a non-default port, as in many local stacks, is then not reached. Error 2003 means the TCP address and port you gave answered nothing.

php -r 'mysqli_report(MYSQLI_REPORT_OFF); $m=@new mysqli("127.0.0.1","my_user","my_password","my_db",3307); echo $m->connect_errno,": ",$m->connect_error;'

2Fix

Use 127.0.0.1 as the hostname when you need a specific port, and make sure the port matches the server.

// CodeIgniter 3
'hostname' => '127.0.0.1',
'port'     => 3307,
// CodeIgniter 4
database.default.hostname = 127.0.0.1
database.default.port = 3307

3Verify

Run the mysqli check with the same host and port and confirm it connects.

php test-mysqli.php

Confirmed by php.net

Did this fix it?

Cause 4 of 4

The driver name is wrong for the framework version

1Check

In CodeIgniter 3 the dbdriver value must be written in lower case, for example mysqli, and the old mysql driver is deprecated. In CodeIgniter 4 the setting is DBDriver and the default is MySQLi.

grep -n "dbdriver\|DBDriver" application/config/database.php app/Config/Database.php 2>/dev/null

2Fix

Use mysqli, and add the port line yourself in CodeIgniter 3 if you need a non-default port.

// CodeIgniter 3
'dbdriver' => 'mysqli',
// CodeIgniter 4
'DBDriver' => 'MySQLi',

3Verify

Reload the page and confirm the database error is gone.

curl -I http://localhost:8080/

Confirmed by codeigniter.com

Did this fix it?

How do I stop it coming back?

  • Keep real credentials in .env (CodeIgniter 4) or per-environment config (CodeIgniter 3), not in the committed default file.
  • Keep a one-file mysqli test script for the server so connection problems are tested without the framework.
  • Use 127.0.0.1 and an explicit port in every environment.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.