Configure a Magento 2 Database Connection

Configure a Magento 2 Database Connection

Want to configure a Magento 2 database connection? More than 250,000 businesses worldwide trust Magento to power their online store. Any successful online store requires a robust and well-configured database. In this article, we will show you how to set up your Magento database.

Key Takeaways:

  • Understand the connection between Magento 2 and database servers, enabling smooth data exchange.

  • Discover the flexibility offered by default and custom connections, allowing tailored configurations.

  • Learn about the advantages of optimizing performance, ensuring robust security measures, and facilitating scalability for business growth.

  • Learn the necessary prerequisites and instructional steps to establish correct remote connections during installation.

What is Magento 2 Database Connection?

A database connection is the channel between Magento 2 and the database server. The data can include product and customer details, order history, and other critical elements. Magento 2 database connection establishes a link between your Magento installation and the database server. This connection allows Magento to read, write, and update information in the database.

There are two main contexts to consider for Magento 2 database connections:

1. Default Connection

This is the primary connection Magento uses to interact with its core database. It's already configured during installation and doesn’t require modification.

2. Custom Connections

For advanced scenarios, Magento allows you to define additional database connections. This can be useful if you want Magento to interact with separate databases for specific purposes. Here are some reasons to opt for this:

  • Security

    Isolate sensitive data like customer information on a separate database.

  • Integration

    Connect to external systems like ERP or PIM for product data.

  • Performance

    Run reports on a replica database to avoid impacting the main store.

  • Scalability

    Implement database sharding to distribute data across multiple servers.

Benefits of a Well-Configured Database Connection

A well-configured database connection is the backbone of a smooth-running and secure online store. Here's how a proper configuration benefits your business:

1. Enhanced Performance and User Experience

Fast and reliable access to product information, customer data, and order history. A well-configured database ensures efficient data retrieval, leading to faster loading times and a more responsive store.

2. Robust Security

A proper configuration safeguards sensitive customer data like names, addresses, and payment information. This includes using strong passwords, access controls, and secure data transfer protocols. By prioritizing security, you protect both your business and your customers from potential breaches.

3. Scalability for Growth

As your business expands, your online store will experience an increase in traffic and data volume. A well-configured database can handle this growth efficiently without compromising site speed. This often involves using appropriate data types, indexing strategies, and proper normalization techniques.

4. Simplified Maintenance and Upgrades

A well-organized database is easier to maintain and troubleshoot. Regular backups and clear data structures make upgrades smoother and less time-consuming, allowing you to focus on more strategic initiatives.

Configuring the Magento 2 Database Connection


Before you can configure the database connection for Magento 2, there are several prerequisites. These include:

1. Web Server

Magento 2 requires web server software such as MySQL server or Nginx. The web server acts as an intermediary between your web browser and Magento. It serves the Magento application files and processes user requests.

2. Database Server

Magento 2 supports several database servers, including MySQL, MariaDB, and PostgreSQL. You need to have a database server installed and running on your server or local development environment. Ensure that you have the necessary credentials such as username and password to create a new database.

3. PHP

Magento 2 requires PHP version 7.4.x, 8.0, 8.1, or 8.2. Make sure you have the appropriate version installed.

Configuring the connection

Step 1. Create a Database

First, you need to create a new database for your Magento 2 installation. You can do this using a database management tool like phpMyAdmin or through your hosting control panel. Make a note of the database name, username, and password as you will need them later.

Step 2. Update the Environment Configuration File

Magento 2 Environment Configuration File

Magento 2 uses an environment configuration file to store sensitive information, including the database credentials. This file is located at “app/etc/env.php” in your Magento 2 installation directory.

Open the env.php file and find the db section. It should look something like this:

// db section example
'db' => [
    'table_prefix' => '',
    'connection' => [
        'default' => [
            'host' => 'localhost',
            'dbname' => 'magento',
            'username' => 'root',
            'password' => '',
            'active' => '1',

Update the hostname, database name, username, and password fields with the appropriate values for your database.

Creating Remote Connection

Step 1. Locate MySQL Configuration File

On the remote database server, access your MySQL configuration file with root privileges. Use the following command to identify its location:

mysql --help

The output will display the following configuration file path:

/etc/my.cnf /etc/mysql/my.cnf /usr/etc/my.cnf ~/.my.cnf

Step 2. Modify “bind-address”

Within the configuration file, locate the bind-address setting. If it exists, modify the value to the IP address of your Magento 2 web server node. If it's absent, add bind-address = to the [mysqld] section.

Step 3. Save and Restart

Save your changes to the configuration file and restart the MySQL service using the appropriate command. For example, service mysqld restart for CentOS or service mysql restart for Ubuntu.

Step 4. Granting Database User Access

To enable your web server node to interact with the remote database, a database user must be granted access. Here's an example granting full access to the root user on the remote database server:

Magento 2 Database User Grant Full Access

Replace placeholders with your specific details (e.g., GRANT ALL ON magento_remote.* TO dbuser@ IDENTIFIED BY 'dbuserpassword';).

Magento 2 Database Grant Full Access

If your web server is clustered, repeat this step on each web server node, ensuring a consistent username across all nodes.

Step 5. Verifying Database Access

On your Magento 2 web server node, use the following command to test the connection:

Magento 2 Database Verification

Enter the password when prompted. If successful, you'll see the MySQL monitor prompt, indicating a functioning connection. Perform this verification on all web server nodes in a clustered environment.

Magento 2 Database Verification All Nodes

Magento 2 Installation

During the Magento 2 installation, specify the following details:

  1. Base URL (Store Address): The hostname or IP address of your Magento 2 web server node.

  2. Database Host: The IP address of the remote database server (or load balancer if clustered).

  3. Database Username: The local web node database user with granted access.

  4. Database Password: The password for the local web node database user.

  5. Database Name: The name of the database created on the remote server.

This configuration ensures enhanced scalability, improved performance, and a robust foundation for your growing e-commerce business.

Selecting the Appropriate Database for Your Magento 2 Store

Choosing a suitable database system impacts your store's performance, security, and ongoing maintenance. Here's a breakdown of key considerations when choosing between MySQL/MariaDB and PostgreSQL.

Familiarity and Support

1. MySQL/MariaDB

These are the widely adopted options, boasting extensive documentation and a vast community of users and developers. This ensures easy access to troubleshooting and optimization resources.

2. PostgreSQL

While gaining popularity, it has a smaller community compared to MySQL/MariaDB. However, PostgreSQL offers strong community support through dedicated forums and mailing lists.

Feature Set

1. MySQL/MariaDB

These are easy to use and handle everyday store tasks efficiently. They excel at managing transactions such as purchases, order updates, and running basic queries.

2. PostgreSQL

Excels at handling complex data structures and unstructured data (like product descriptions with images). Additionally, PostgreSQL supports advanced functionalities such as stored procedures, beneficial for automating complex tasks.

Remote Database Trade-Offs for Magento 2 Stores

1. Increased Complexity

Setting up and maintaining a remote connection requires more configuration and ongoing management compared to a local database.

2. Potential Latency

Since the web server and database server are separate machines, there might be a slight delay in communication. This may be negligible for most stores, but for highly transactional operations, it's a factor to consider.

3. Security Considerations

Enabling remote access to your database introduces additional security concerns. Proper access controls and network security measures become even more critical.

However, remote connections have improved scalability. The database server can be scaled independently to handle increased data volume. It can handle growth without impacting the performance of your web servers.


1. How do I edit the Magento database configuration file?

The Magento 2 database configuration file, also known as the "db config file", is located at app/etc/env.php within your Magento 2 installation directory. You can edit this file using a configuration file editor of your choice.

2. Can I use a custom database for Magento 2?

Yes, you can configure Magento 2 to use a custom database. During the configuration process, you'll need to edit the db config file with your specific database details. These are username, password, and hostname.

3. What if I'm using Magento 1 for database configuration?

Magento 1 uses a different configuration file named local.xml. This guide focuses on Magento 2 database configuration.

4. I need to edit the Magento 2 database configuration to connect to a different server.

You'll edit the “db config” file again, specifically the host setting. Update this field with the new server hostname. Remember to save the file and clear your cache for the changes to take effect.

5. How do I clear the cache after updating the database configuration?

Magento 2 doesn't automatically detect changes to the db config file. To ensure it recognizes the new settings, go to the Magento 2 backend and navigate to System > Cache Management. Select all cache types and click Flush Magento Cache.

6. Can I change my Magento 2 database username and password?

Edit the “db config” file and update the username and password fields with your new credentials. Clear the cache afterward.


A well-configured Magento 2 database connection is the foundation for a secure and performant store. It lays the groundwork for efficient data management, protects sensitive customer information, and paves the way for future growth.

Here's a quick checklist to keep your database connection optimized for peak performance:

  • Server Setup

    Verify you have a compatible web server such as Nginx and database server (MySQL, MariaDB, or PostgreSQL) running.

  • Database Credentials

    Retain the database name, username, and password you created specifically for Magento 2. These credentials are essential for ongoing database access.

  • Editing Configuration File

    Locate and edit the env.php file within your Magento 2 directory using a text editor.

  • Update Database Settings

    Within the db section, update the host, dbname, username, and password fields with your database credentials.

  • Save and Clear the Cache

    After saving the changes, clear the Magento 2 cache for the new configuration to take effect.

To ensure optimal performance, explore managed Magento hosting options.

Magento Hosting Free Demo on AWS

Suchita Arya
Suchita Arya
Technical Writer

Suchita is a dedicated technical writer with a keen interest in Magento commerce and cloud technology. She offers fresh viewpoints, blending her knowledge and news of the ecommerce industry.

Get the fastest Magento Hosting! Get Started