Remote Database Access

WP Engine provides access to an install’s database via phpMyAdmin in the User Portal. In some cases though, you may prefer an alternate method of running SQL queries against your website. This can be done using SSH Gateway or with a remote database management tool.

---

SSH Gateway

SSH Gateway is secure shell access which allows a user to run wp db query without allowlisting any IPs or using any additional MySQL programs. The wp db query command is part of the open source WordPress software package, and allows you to run a SQL query against the database information supplied in the wp-config.php file.

Learn more about wp db query here.

Before you can run a query, you will need to connect to your website’s root directory using SSH Gateway. If you haven’t connected to this feature yet, the step by step process can be found in our SSH Gateway article.

Once you have access to SSH Gateway the process will look like this:

1. Connect to SSH Gateway:
   • ssh environmentname@environmentname.ssh.wpengine.net
2. Move to your environment’s root directory:
   • cd sites/environmentname
3. Run a database query:
   • wp db query "your query here;"
   • For example, this will list all post titles: wp db query 'SELECT post_title FROM wp_posts;'

To learn more about MySQL syntax and variables, see the official documentation here and the Getting Started guide here.

---

MySQL Workbench

Open MySQL Workbench and create a new connection by clicking on Database → Manage Connections in the menu, then click New.

Give your connection a name and use the following values to configure the connection:

• Connection Method: Standard (TCP/IP) over SSH
• SSH Hostname: environmentname.ssh.wpengine.net (EX: acoolsite.ssh.wpengine.net)
• SSH Username: environmentname
• SSH Password: Leave this blank
• SSH Key File: Use the key file created here
• MySQL Host Name: 127.0.0.1
• MySQL Server Port: 3306
• Username: environmentname
• Password: Use the database password for the website. Found in your wp-config.php file on the line DB_PASSWORD.
• Default Schema: wp_environmentname (EX: wp_acoolsite)

Click Test Connection and you’ll be prompted for the database password you retrieved above. This can be found in ./_wpeprivate/config.json as WPENGINE_SESSION_DB_PASSWORD.

---

Sequel Ace

Open Sequel Ace and create a new connection by clicking on MySQL in the menu.

Give your connection a name and use the following values to configure the connection:

• Connection Method: SSH
• MySQL Hostname: 127.0.0.1
• Username: environmentname
• Password: Use the database password for the website. Found in your wp-config.php file on the line DB_PASSWORD.
• Database: wp_environmentname (EX: wp_acoolsite)
• Port: 3306
• SSH Host: environmentname.ssh.wpengine.net (EX: acoolsite.ssh.wpengine.net)
• SSH User: environmentname
• SSH Password: Click the Key, and Use the key file created here
• SSH Port: Leave blank

---

Other Database Management Tools

If you wish to use a different tool to access your database the first step is to start an SSH session with local port forwarding.

ssh -L 3307:127.0.0.1:3306 environmentname@environmentname.ssh.wpengine.net

Now you’ll need to retrieve your MySQL database’s password. Once the connection has been made, enter the following:

grep WPENGINE_SESSION_DB_PASSWORD ./sites/environmentname/_wpeprivate/config.json

After local port forwarding has been configured, your database management application will require inputting connection information. Here are the standard set of values you’ll typically need to enter:

• Hostname: 127.0.0.1
• Port: 3307
• Username: environmentname (EX: acoolsite)
• Password: Use the database password retrieved above.
• Database: wp_environmentname (EX: wp_acoolsite)

---

NEXT STEP: Learn about SSH Gateway at WP Engine