How to Change Magento Database Credentials

Magento stores important information such as products, customers, orders, configurations, and CMS content in its database. To connect to that database, Magento uses credentials defined in the app/etc/env.php file.

If you change your database name, database username, database password, or database host, you must update Magento’s database configuration accordingly. Otherwise, the storefront and Admin Panel may display database connection errors.

This guide explains how to safely change Magento database credentials on a Linux server.

What Are Magento Database Credentials?

Magento’s database connection information is stored in:

app/etc/env.php

A typical configuration looks similar to:

'db' => [
    'connection' => [
        'default' => [
            'host' => 'localhost',
            'dbname' => 'magento',
            'username' => 'magento_user',
            'password' => 'strong_password',
            'active' => '1'
        ]
    ]
],

The main values are:

• host — Database server hostname
• dbname — Magento database name
• username — Database user
• password — Database user’s password
• active — Determines whether the connection is active

Your exact configuration may contain additional options.

---

When Should You Change Magento Database Credentials?

You may need to update the credentials when:

• You change the database password.
• You create a new database user.
• You migrate Magento to another server.
• You rename or replace the database.
• You move from cPanel to DirectAdmin.
• Your database credentials were exposed.
• You move the database to another server.
• You change the database hostname.
• You are following a security policy requiring credential rotation.

Changing the password periodically can also reduce the risk associated with compromised credentials.

---

Before Changing the Credentials

Before modifying env.php, make sure you have:

• SSH or File Manager access
• Access to the Magento installation
• Database administrator access
• The new database credentials
• A recent Magento backup
• Permission to edit app/etc/env.php

Most importantly, do not change the Magento configuration before confirming that the new database credentials actually work.

---

Step 1: Locate Your Magento Installation

Log in to the server through SSH and move to your Magento directory.

For example:

cd /home/user/domains/example.com/public_html

Check that Magento is installed:

php bin/magento --version

You should see the installed Magento version.

---

Step 2: Back Up env.php

Before editing the configuration file, create a backup:

cp app/etc/env.php app/etc/env.php.backup

You can verify that the backup exists:

ls -l app/etc/env.php*

Keep this backup until you have confirmed that Magento works with the new credentials.

---

Step 3: Check the Existing Database Credentials

Open the configuration file:

nano app/etc/env.php

Look for:

'db' => [
    'connection' => [
        'default' => [
            'host' => 'localhost',
            'dbname' => 'magento',
            'username' => 'magento_user',
            'password' => 'old_password',
            'active' => '1'
        ]
    ]
],

Record the existing values before making any changes.

You can also search for the database section:

grep -n "'db'" app/etc/env.php

Be careful when displaying or sharing this file because it may contain sensitive credentials and encryption keys.

---

Step 4: Create or Change the Database User

If you are only changing the password of an existing database user, you can update that user’s password.

For example, from MySQL:

ALTER USER 'magento_user'@'localhost'
IDENTIFIED BY 'NewStrongPasswordHere';

Depending on the MySQL/MariaDB version, the exact syntax and authentication configuration may vary.

If you are creating a new database user, you can use:

CREATE USER 'new_magento_user'@'localhost'
IDENTIFIED BY 'NewStrongPasswordHere';

Then grant the required permissions:

GRANT ALL PRIVILEGES ON magento.* 
TO 'new_magento_user'@'localhost';

Apply the privilege changes if required by your database version:

FLUSH PRIVILEGES;

Important: Replace the database and username values with your actual values.

Do not grant unnecessary privileges to the Magento database user.

---

Step 5: Test the New Database Credentials

Before changing Magento, test the new credentials directly.

For example:

mysql -u new_magento_user -p magento

Enter the new password.

If the credentials are correct, you should receive a MySQL prompt:

mysql>

Run:

SHOW TABLES;

You should see Magento database tables.

Exit:

EXIT;

If the login fails, fix the database user, password, host, or permissions before changing Magento.

---

Step 6: Put Magento Into Maintenance Mode

For a production store, enable maintenance mode before changing the connection configuration:

php bin/magento maintenance:enable

Check the status:

php bin/magento maintenance:status

This prevents customers from interacting with the store while the database configuration is being changed.

---

Step 7: Update app/etc/env.php

Open the file:

nano app/etc/env.php

Change the database values.

For example:

'db' => [
    'connection' => [
        'default' => [
            'host' => 'localhost',
            'dbname' => 'magento',
            'username' => 'new_magento_user',
            'password' => 'NewStrongPasswordHere',
            'active' => '1'
        ]
    ]
],

Save the file.

If you are changing only the password, modify only:

'password' => 'NewStrongPasswordHere',

Avoid changing unrelated configuration values.

---

Step 8: Check the Configuration Syntax

Because env.php is a PHP file, a syntax mistake can prevent Magento from starting.

Run:

php -l app/etc/env.php

A successful result should look similar to:

No syntax errors detected in app/etc/env.php

If you receive a syntax error, fix it before continuing.

---

Step 9: Test Magento’s Database Connection

Run:

php bin/magento cache:status

If Magento can connect successfully, the command should execute normally.

You can also run:

php bin/magento cache:flush

If Magento reports an SQL or database connection error, check the credentials in env.php.

---

Step 10: Run a Magento Command

Run another Magento command to confirm that the application can communicate with the database:

php bin/magento indexer:status

If this works without a database connection error, the new credentials are likely functioning correctly.

You normally do not need to run:

php bin/magento setup:upgrade

merely because database credentials changed. That command is used for Magento module/schema changes and should not be run unnecessarily.

---

Step 11: Test the Storefront

Open your Magento website and verify:

• Homepage loads
• Categories work
• Product pages work
• Product search works
• Images load
• Customer login works
• Cart works
• Checkout works

Also check whether existing products and orders are visible.

---

Step 12: Test the Magento Admin

Log in to the Magento Admin Panel.

Check:

• Dashboard
• Products
• Categories
• Customers
• Orders
• Configuration
• Reports

If the Admin Panel works and existing data is available, Magento is successfully using the database.

---

Step 13: Check Magento Logs

If Magento fails after changing the credentials, check the logs:

ls -lah var/log/

Common files include:

var/log/system.log
var/log/exception.log

You can inspect recent errors with:

tail -f var/log/system.log

You may see errors such as:

SQLSTATE[HY000] [1045] Access denied for user

This usually indicates incorrect credentials or insufficient database permissions.

---

Step 14: Disable Maintenance Mode

Once you have confirmed that everything works:

php bin/magento maintenance:disable

Verify:

php bin/magento maintenance:status

The store should now be available to customers.

---

Changing Database Credentials in DirectAdmin

If your Magento website is hosted on DirectAdmin, the process is similar.

First create or modify the database user through:

DirectAdmin → Account Manager → MySQL Management

Depending on your DirectAdmin configuration, database names and usernames may automatically receive an account prefix.

For example:

Account: ehost
Database: ehost_magento
User: ehost_magento

After creating the database user and assigning it to the database, update:

app/etc/env.php

For example:

'dbname' => 'ehost_magento',
'username' => 'ehost_magento',
'password' => 'NEW_PASSWORD',

Then test the connection from SSH.

---

Changing Database Credentials on cPanel

If Magento is hosted on cPanel, you can manage database users through:

cPanel → MySQL Databases

From there you can:

1. Create a database.
2. Create a database user.
3. Assign the user to the database.
4. Grant the required privileges.
5. Update app/etc/env.php.

The exact database names may include your cPanel account username.

For example:

account_magento
account_magento_user

Use the exact names displayed by cPanel.

---

How to Change Only the Database Password

If you only want to rotate the password, the process is straightforward.

First change the database user’s password:

ALTER USER 'magento_user'@'localhost'
IDENTIFIED BY 'NewStrongPassword';

Then update:

app/etc/env.php

Change:

'password' => 'OldPassword',

to:

'password' => 'NewStrongPassword',

Test:

php bin/magento cache:status

Then check the storefront and Admin Panel.

---

How to Change the Database Name

If you move Magento to a different database, update:

'dbname' => 'new_database',

For example:

'db' => [
    'connection' => [
        'default' => [
            'host' => 'localhost',
            'dbname' => 'new_magento',
            'username' => 'new_magento_user',
            'password' => 'StrongPassword',
            'active' => '1'
        ]
    ]
],

Before changing this value, make sure the new database already contains the Magento data.

---

How to Change the Database Host

If the database is hosted on another server, update:

'host' => 'localhost',

to the appropriate hostname or IP address:

'host' => 'db.example.com',

or:

'host' => '192.0.2.50',

The remote database server must allow connections from the Magento server, and the database user must have permission to connect from that host.

Do not expose a database server to the public Internet unnecessarily. Restrict access through firewall rules and network controls whenever possible.

---

Common Errors After Changing Magento Database Credentials

Access Denied for User

You may see:

SQLSTATE[HY000] [1045] Access denied for user

Check:

• Username
• Password
• Database host
• User permissions
• MySQL/MariaDB status

Test manually:

mysql -u username -p database_name

---

Unknown Database

An error such as:

Unknown database 'magento'

usually means that the database name in env.php does not exist.

Check:

SHOW DATABASES;

Then verify the value in:

app/etc/env.php

---

Can’t Connect to MySQL Server

An error such as:

Can't connect to MySQL server

can be caused by:

• Incorrect database hostname
• MySQL/MariaDB service stopped
• Firewall restrictions
• Incorrect port
• Remote database access not permitted

Test the database server separately before troubleshooting Magento.

---

Magento Shows a 500 Error

A 500 error after editing env.php may be caused by:

• Invalid PHP syntax
• Incorrect permissions
• Invalid database credentials
• PHP configuration problems

First check the syntax:

php -l app/etc/env.php

Then inspect Magento and web-server logs.

---

Security Best Practices

Database credentials should be treated as sensitive information.

Use a Strong Password

Use a long, unique password containing a combination of letters, numbers, and symbols.

Use a Dedicated Database User

Do not use a shared database account for multiple unrelated applications.

Grant Only Required Permissions

The Magento database user should have the permissions it needs for the Magento database, rather than unnecessary access to unrelated databases.

Protect env.php

The file contains sensitive configuration information. Make sure it is not publicly downloadable.

Avoid Sharing Credentials

Never post env.php, database passwords, or complete database connection strings in public forums or support tickets.

Rotate Exposed Credentials

If database credentials are accidentally exposed, change the database password immediately and update Magento’s configuration.

Keep Backups Secure

Database backups can contain customer and order information. Store them securely and restrict access.

---

Quick Command Reference

Check Magento version:

php bin/magento --version

Enable maintenance mode:

php bin/magento maintenance:enable

Check maintenance status:

php bin/magento maintenance:status

Test PHP syntax:

php -l app/etc/env.php

Check Magento cache:

php bin/magento cache:status

Flush Magento cache:

php bin/magento cache:flush

Check indexers:

php bin/magento indexer:status

Disable maintenance mode:

php bin/magento maintenance:disable

---

Magento Database Credential Change Checklist

Before finishing the change, verify:

• Magento backup created
• app/etc/env.php backed up
• New database user created or existing user updated
• New password tested
• Database permissions verified
• env.php updated
• PHP syntax checked
• Magento CLI command tested
• Cache checked/flushed
• Storefront tested
• Admin Panel tested
• Checkout tested
• Orders verified
• Magento logs checked
• Maintenance mode disabled
• Old credentials no longer exposed

Conclusion

Changing Magento database credentials is usually a simple configuration task, but an incorrect database username, password, hostname, or permission can make the entire store unavailable.

The safest approach is to back up app/etc/env.php, create and test the new database credentials, update the configuration, verify the PHP syntax, test Magento CLI commands, and then check the storefront and Admin Panel.

If you are migrating Magento between servers, changing the database credentials should be performed as part of the larger migration process rather than as an isolated change. Always keep a working backup of the previous configuration until the new database connection has been fully verified.