wp db

Last updated: February 15, 2026

Performs basic database operations using credentials stored in wp-config.php.

Subcommands

CommandDescription
wp db checkChecks the current status of the database.
wp db cleanRemoves all tables with $table_prefix from the database.
wp db cliOpens a MySQL console using credentials from wp-config.php.
wp db columnsDisplays information about a given table.
wp db createCreates a new database.
wp db dropDeletes the existing database.
wp db exportExports the database to a file or to STDOUT.
wp db importImports a database from a file or from STDIN.
wp db optimizeOptimizes the database.
wp db prefixDisplays the database table prefix.
wp db queryExecutes a SQL query against the database.
wp db repairRepairs the database.
wp db resetRemoves all tables from the database.
wp db searchFinds a string in the database.
wp db sizeDisplays the database name and size.
wp db tablesLists the database tables.

Examples

bash
# Create a new database.
$ wp db create
Success: Database created.

# Drop an existing database.
$ wp db drop --yes
Success: Database dropped.

# Reset the current database.
$ wp db reset --yes
Success: Database reset.

# Execute a SQL query stored in a file.
$ wp db query < debug.sql

wp db check

Checks the current status of the database.

Runs mysqlcheck utility with --check using DB_HOST, DB_NAME, DB_USER and DB_PASSWORD database credentials specified in wp-config.php.

Synopsis

bash
wp db check [--dbuser=<value>] [--dbpass=<value>] [--<field>=<value>] [--defaults]

Parameters

ParameterDescription
[--dbuser=<value>]Username to pass to mysqlcheck. Defaults to DB_USER.
[--dbpass=<value>]Password to pass to mysqlcheck. Defaults to DB_PASSWORD.
[--<field>=<value>]Extra arguments to pass to mysqlcheck.
[--defaults]Loads the environment’s MySQL option files.

Examples

bash
$ wp db check
Success: Database checked.

wp db clean

Removes all tables with $table_prefix from the database.

Runs DROP_TABLE for each table that has a $table_prefix as specified in wp-config.php.

Synopsis

bash
wp db clean [--dbuser=<value>] [--dbpass=<value>] [--yes] [--defaults]

Parameters

ParameterDescription
[--dbuser=<value>]Username to pass to mysql. Defaults to DB_USER.
[--dbpass=<value>]Password to pass to mysql. Defaults to DB_PASSWORD.
[--yes]Answer yes to the confirmation message.
[--defaults]Loads the environment’s MySQL option files.

Examples

bash
$ wp db clean --yes
Success: Tables dropped.

wp db cli

Opens a MySQL console using credentials from wp-config.php.

Synopsis

bash
wp db cli [--database=<database>] [--default-character-set=<character-set>] [--dbuser=<value>] [--dbpass=<value>] [--<field>=<value>] [--defaults]

Parameters

ParameterDescription
[--database=<database>]Use a specific database. Defaults to DB_NAME.
[--default-character-set=<character-set>]Use a specific character set. Defaults to DB_CHARSET when defined.
[--dbuser=<value>]Username to pass to mysql. Defaults to DB_USER.
[--dbpass=<value>]Password to pass to mysql. Defaults to DB_PASSWORD.
[--<field>=<value>]Extra arguments to pass to mysql.
[--defaults]Loads the environment’s MySQL option files.

Examples

bash
# Open MySQL console
$ wp db cli
mysql>

wp db columns

Displays information about a given table.

Synopsis

bash
wp db columns <table> [--format]

Parameters

ParameterDescription
<table>Name of the database table.
[--format]Render output in a particular format. Default: table. Options: table, csv, json, yaml

Examples

bash
$ wp db columns wp_posts
+-----------------------+---------------------+------+-----+---------------------+----------------+
|         Field         |        Type         | Null | Key |       Default       |     Extra      |
+-----------------------+---------------------+------+-----+---------------------+----------------+
| ID                    | bigint(20) unsigned | NO   | PRI |                     | auto_increment |
| post_author           | bigint(20) unsigned | NO   | MUL | 0                   |                |
| post_date             | datetime            | NO   |     | 0000-00-00 00:00:00 |                |
| post_date_gmt         | datetime            | NO   |     | 0000-00-00 00:00:00 |                |
| post_content          | longtext            | NO   |     |                     |                |
| post_title            | text                | NO   |     |                     |                |
...
+-----------------------+---------------------+------+-----+---------------------+----------------+

wp db create

Creates a new database.

Runs CREATE_DATABASE SQL statement using DB_HOST, DB_NAME, DB_USER and DB_PASSWORD database credentials specified in wp-config.php.

Synopsis

bash
wp db create [--dbuser=<value>] [--dbpass=<value>] [--defaults]

Parameters

ParameterDescription
[--dbuser=<value>]Username to pass to mysql. Defaults to DB_USER.
[--dbpass=<value>]Password to pass to mysql. Defaults to DB_PASSWORD.
[--defaults]Loads the environment’s MySQL option files.

Examples

bash
$ wp db create
Success: Database created.

wp db drop

Deletes the existing database.

Runs DROP_DATABASE SQL statement using DB_HOST, DB_NAME, DB_USER and DB_PASSWORD database credentials specified in wp-config.php.

Synopsis

bash
wp db drop [--dbuser=<value>] [--dbpass=<value>] [--yes] [--defaults]

Parameters

ParameterDescription
[--dbuser=<value>]Username to pass to mysql. Defaults to DB_USER.
[--dbpass=<value>]Password to pass to mysql. Defaults to DB_PASSWORD.
[--yes]Answer yes to the confirmation message.
[--defaults]Loads the environment’s MySQL option files.

Examples

bash
$ wp db drop --yes
Success: Database dropped.

wp db export

Exports the database to a file or to STDOUT.

Runs mysqldump utility using DB_HOST, DB_NAME, DB_USER and DB_PASSWORD database credentials specified in wp-config.php. Accepts any valid mysqldump flags.

Synopsis

bash
wp db export [<file>] [--dbuser=<value>] [--dbpass=<value>] [--<field>=<value>] [--tables=<tables>] [--exclude_tables=<tables>] [--include-tablespaces] [--porcelain] [--add-drop-table] [--defaults]

Parameters

ParameterDescription
[<file>]The name of the SQL file to export. If ‘-‘, then outputs to STDOUT. If omitted, it will be ‘{dbname}-{Y-m-d}-{random-hash}.sql’.
[--dbuser=<value>]Username to pass to mysqldump. Defaults to DB_USER.
[--dbpass=<value>]Password to pass to mysqldump. Defaults to DB_PASSWORD.
[--<field>=<value>]Extra arguments to pass to mysqldump.
[--tables=<tables>]The comma separated list of specific tables to export.
[--exclude_tables=<tables>]The comma separated list of specific tables that should be skipped from exporting.
[--include-tablespaces]Skips adding the default –no-tablespaces option to mysqldump.
[--porcelain]Output filename for the exported database.
[--add-drop-table]Include a DROP TABLE IF EXISTS statement before each CREATE TABLE statement.
[--defaults]Loads the environment’s MySQL option files.

Examples

bash
# Export database with drop query included
$ wp db export --add-drop-table
Success: Exported to 'wordpress_dbase-db72bb5.sql'.

# Export certain tables
$ wp db export --tables=wp_options,wp_users
Success: Exported to 'wordpress_dbase-db72bb5.sql'.

# Export all tables matching a wildcard
$ wp db export --tables=$(wp db tables 'wp_user*' --format=csv)
Success: Exported to 'wordpress_dbase-db72bb5.sql'.

# Export database to STDOUT.
$ wp db export -
-- MySQL dump 10.13  Distrib 5.7.19, for osx10.12 (x86_64)
...

wp db import

Imports a database from a file or from STDIN.

Runs SQL queries using DB_HOST, DB_NAME, DB_USER and DB_PASSWORD database credentials specified in wp-config.php.

Synopsis

bash
wp db import [<file>] [--dbuser=<value>] [--dbpass=<value>] [--<field>=<value>] [--skip-optimization] [--defaults]

Parameters

ParameterDescription
[<file>]The name of the SQL file to import. If ‘-‘, then reads from STDIN. If omitted, it will look for ‘{dbname}.sql’.
[--dbuser=<value>]Username to pass to mysql. Defaults to DB_USER.
[--dbpass=<value>]Password to pass to mysql. Defaults to DB_PASSWORD.
[--<field>=<value>]Extra arguments to pass to mysql.
[--skip-optimization]When using an SQL file, do not include speed optimization such as disabling auto-commit and key checks.
[--defaults]Loads the environment’s MySQL option files.

Examples

bash
$ wp db import wordpress_dbase.sql
Success: Imported from 'wordpress_dbase.sql'.

wp db optimize

Optimizes the database.

Runs mysqlcheck utility with --optimize=true using DB_HOST, DB_NAME, DB_USER and DB_PASSWORD database credentials specified in wp-config.php.

Synopsis

bash
wp db optimize [--dbuser=<value>] [--dbpass=<value>] [--<field>=<value>] [--defaults]

Parameters

ParameterDescription
[--dbuser=<value>]Username to pass to mysqlcheck. Defaults to DB_USER.
[--dbpass=<value>]Password to pass to mysqlcheck. Defaults to DB_PASSWORD.
[--<field>=<value>]Extra arguments to pass to mysqlcheck.
[--defaults]Loads the environment’s MySQL option files.

Examples

bash
$ wp db optimize
Success: Database optimized.

wp db prefix

Displays the database table prefix.

Display the database table prefix, as defined by the database handler’s interpretation of the current site.

Synopsis

bash
wp db prefix

Examples

bash
$ wp db prefix
wp_

wp db query

Executes a SQL query against the database.

Executes an arbitrary SQL query using DB_HOST, DB_NAME, DB_USER and DB_PASSWORD database credentials specified in wp-config.php.

Use the --skip-column-names MySQL argument to exclude the headers from a SELECT query. Pipe the output to remove the ASCII table entirely.

Synopsis

bash
wp db query [<sql>] [--dbuser=<value>] [--dbpass=<value>] [--<field>=<value>] [--defaults]

Parameters

ParameterDescription
[<sql>]A SQL query. If not passed, will try to read from STDIN.
[--dbuser=<value>]Username to pass to mysql. Defaults to DB_USER.
[--dbpass=<value>]Password to pass to mysql. Defaults to DB_PASSWORD.
[--<field>=<value>]Extra arguments to pass to mysql.
[--defaults]Loads the environment’s MySQL option files.

Examples

bash
# Execute a query stored in a file
$ wp db query < debug.sql

# Query for a specific value in the database
$ wp db query 'SELECT option_value FROM wp_options WHERE option_name="home"' --skip-column-names
+---------------------+
| https://example.com |
+---------------------+

# Check all tables in the database
$ wp db query "CHECK TABLE $(wp db tables | paste -s -d, -);"

Multisite Usage

Please note that the global --url parameter will have no effect on this command. In order to query for data in a site other than your primary site, you will need to manually modify the table names to use the prefix that includes the site’s ID.

bash
# Get the home option for your second site
$ wp db query 'SELECT option_value FROM wp_2_options WHERE option_name="home"' --skip-column-names

wp db repair

Repairs the database.

Runs mysqlcheck utility with --repair=true using DB_HOST, DB_NAME, DB_USER and DB_PASSWORD database credentials specified in wp-config.php.

Synopsis

bash
wp db repair [--dbuser=<value>] [--dbpass=<value>] [--<field>=<value>] [--defaults]

Parameters

ParameterDescription
[--dbuser=<value>]Username to pass to mysqlcheck. Defaults to DB_USER.
[--dbpass=<value>]Password to pass to mysqlcheck. Defaults to DB_PASSWORD.
[--<field>=<value>]Extra arguments to pass to mysqlcheck.
[--defaults]Loads the environment’s MySQL option files.

Examples

bash
$ wp db repair
Success: Database repaired.

wp db reset

Removes all tables from the database.

Runs DROP_DATABASE and CREATE_DATABASE SQL statements using DB_HOST, DB_NAME, DB_USER and DB_PASSWORD database credentials specified in wp-config.php.

Synopsis

bash
wp db reset [--dbuser=<value>] [--dbpass=<value>] [--yes] [--defaults]

Parameters

ParameterDescription
[--dbuser=<value>]Username to pass to mysql. Defaults to DB_USER.
[--dbpass=<value>]Password to pass to mysql. Defaults to DB_PASSWORD.
[--yes]Answer yes to the confirmation message.
[--defaults]Loads the environment’s MySQL option files.

Examples

bash
$ wp db reset --yes
Success: Database reset.

Finds a string in the database.

Searches through all of the text columns in a selection of database tables for a given string. Outputs colorized references to the string.

Defaults to searching through all tables registered to $wpdb. On multisite, this default is limited to the tables for the current site.

Synopsis

bash
wp db search <search> [<tables>...] [--network] [--all-tables-with-prefix] [--all-tables] [--before_context=<num>] [--after_context=<num>] [--regex] [--regex-flags=<regex-flags>] [--regex-delimiter=<regex-delimiter>] [--table_column_once] [--one_line] [--matches_only] [--stats] [--table_column_color=<color_code>] [--id_color=<color_code>] [--match_color=<color_code>] [--fields=<fields>] [--format=<format>]

Parameters

ParameterDescription
<search>String to search for. The search is case-insensitive by default.
[<tables>...]One or more tables to search through for the string.
[--network]Search through all the tables registered to $wpdb in a multisite install.
[--all-tables-with-prefix]Search through all tables that match the registered table prefix.
[--all-tables]Search through ALL tables in the database, regardless of the prefix.
[--before_context=<num>]Number of characters to display before the match. Default: 40
[--after_context=<num>]Number of characters to display after the match. Default: 40
[--regex]Runs the search as a regular expression (without delimiters).
[--regex-flags=<regex-flags>]Pass PCRE modifiers to the regex search.
[--stats]Output stats on the number of matches found, time taken, tables/columns/rows searched.
[--format=<format>]Render output in a particular format. Options: table, csv, json, yaml, ids, count

Examples

bash
# Search through the database for the 'wordpress-develop' string
$ wp db search wordpress-develop
wp_options:option_value
1:http://wordpress-develop.dev
...

# Search using regular expressions with stats
$ wp db search 'https?://' --regex --stats
wp_comments:comment_author_url
1:https://wordpress.org/
...
Success: Found 99146 matches in 10.752s (10.559s searching). Searched 12 tables, 53 columns, 1358907 rows.

# Search for a string and print the result as a table
$ wp db search https://localhost:8889 --format=table --fields=table,column,match
+------------+--------------+-----------------------------+
| table      | column       | match                       |
+------------+--------------+-----------------------------+
| wp_options | option_value | https://localhost:8889      |
| wp_options | option_value | https://localhost:8889      |
| wp_posts   | guid         | https://localhost:8889/?p=1 |
| wp_users   | user_url     | https://localhost:8889      |
+------------+--------------+-----------------------------+

wp db size

Displays the database name and size.

Synopsis

bash
wp db size [--size_format=<format>] [--tables] [--human-readable] [--format=<format>] [--scope=<scope>] [--network] [--decimals=<decimals>] [--all-tables-with-prefix] [--all-tables]

Parameters

ParameterDescription
[--size_format=<format>]Display the database size in a specific format. Default: b. Options: b (bytes), kb, mb, gb, tb
[--tables]Show information for each table.
[--human-readable]Display the database size in a human readable format.
[--format=<format>]Render output in a particular format. Default: table. Options: table, csv, json, yaml
[--scope=<scope>]Filter tables by scope. Options: all, global, blog, old
[--network]Show the database sizes for all network sites.
[--decimals=<decimals>]Number of decimals to display. Default: 0
[--all-tables-with-prefix]Show all tables that match the prefix, even if not registered.
[--all-tables]Show ALL tables in the database.

Examples

bash
$ wp db size
+------------------+------+
| Name             | Size |
+------------------+------+
| wordpress_dbase  | 128M |
+------------------+------+

$ wp db size --tables
+-----------------------+-------+
| Name                  | Size  |
+-----------------------+-------+
| wp_comments           | 64KB  |
| wp_options            | 128KB |
| wp_posts              | 1MB   |
...
+-----------------------+-------+

wp db tables

Lists the database tables.

Synopsis

bash
wp db tables [<table>...] [--scope=<scope>] [--network] [--all-tables-with-prefix] [--all-tables] [--format=<format>]

Parameters

ParameterDescription
[<table>...]List tables based on wildcard search pattern or specific table name.
[--scope=<scope>]Can be all, global, blog, or old tables. Default: all
[--network]List all network tables based on multisite setup.
[--all-tables-with-prefix]List all tables that match the table prefix even if not registered on $wpdb.
[--all-tables]List all tables in the database, regardless of the prefix.
[--format=<format>]Render output in a particular format. Default: list. Options: list, csv

Examples

bash
# List tables for a single site, delimited by a space.
$ wp db tables --format=csv
wp_users,wp_usermeta,wp_posts,wp_comments,wp_links,wp_options,wp_postmeta,wp_terms,wp_term_taxonomy,wp_term_relationships,wp_termmeta,wp_commentmeta

# List all tables with wildcard
$ wp db tables 'wp_user*'
wp_users
wp_usermeta

More in Db

wp eval

Executes arbitrary PHP code. Note: because code is executed within a method, global variables need…

wp menu

Lists, creates, assigns, and deletes the active theme's navigation menus. See the Navigation Menus reference…

wp role list

Lists all roles. Synopsis wp role list [--fields=<fields>] [--field=<field>] [--format=<format>] Options [--fields=] Limit the output…

wp sidebar

Lists registered sidebars. A sidebar is any widgetized area of your theme. Subcommands Command Description…

All WP-CLI Docs View all Db
View on GitHub