class wpdb
WordPress database access abstraction class.
Since: 0.71
Source: wp-includes/class-wpdb.php
Overview
The wpdb class provides methods for interacting with the WordPress database. A global instance $wpdb is available throughout WordPress.
global $wpdb;
$results = $wpdb->get_results( "SELECT * FROM {$wpdb->posts}" );Properties
Table Name Properties (Per-Site)
These properties contain the prefixed table names for per-site tables.
| Property | Type | Since | Description |
|---|---|---|---|
$posts | string | 1.5.0 | Posts table |
$postmeta | string | 1.5.0 | Post metadata table |
$comments | string | 1.5.0 | Comments table |
$commentmeta | string | 2.9.0 | Comment metadata table |
$terms | string | 2.3.0 | Terms table |
$term_taxonomy | string | 2.3.0 | Term taxonomy table |
$term_relationships | string | 2.3.0 | Term relationships table |
$termmeta | string | 4.4.0 | Term metadata table |
$options | string | 1.5.0 | Options table |
$links | string | 1.5.0 | Links table |
Table Name Properties (Global)
Global tables shared across multisite.
| Property | Type | Since | Description |
|---|---|---|---|
$users | string | 1.5.0 | Users table |
$usermeta | string | 2.3.0 | User metadata table |
Table Name Properties (Multisite Global)
Multisite-only global tables.
| Property | Type | Since | Description |
|---|---|---|---|
$blogs | string|null | 3.0.0 | Blogs table |
$blogmeta | string|null | 5.1.0 | Blog metadata table |
$site | string|null | 3.0.0 | Sites table |
$sitemeta | string|null | 3.0.0 | Site metadata table |
$signups | string|null | 3.0.0 | Signups table |
$registration_log | string|null | 3.0.0 | Registration log table |
$sitecategories | string|null | 3.0.0 | Sitewide terms table (deprecated) |
Table List Arrays
| Property | Type | Since | Description |
|---|---|---|---|
$tables | string[] | 2.5.0 | List of per-site table names (unprefixed) |
$global_tables | string[] | 3.0.0 | List of global table names |
$ms_global_tables | string[] | 3.0.0 | List of multisite global table names |
$old_tables | string[] | 2.9.0 | List of deprecated table names |
$old_ms_global_tables | string[] | 6.1.0 | List of deprecated MS global table names |
Prefix Properties
| Property | Type | Since | Description |
|---|---|---|---|
$prefix | string | 2.5.0 | Current table prefix (includes blog ID in multisite) |
$base_prefix | string | 3.0.0 | Base table prefix (without blog ID) |
Query State Properties
| Property | Type | Since | Description |
|---|---|---|---|
$last_query | string | 0.71 | The last SQL query executed |
$last_result | stdClass[]|null | 0.71 | Results from the last query |
$last_error | string | 2.5.0 | Error message from the last query |
$num_queries | int | 1.2.0 | Total number of queries executed |
$num_rows | int | 0.71 | Number of rows returned by last SELECT |
$rows_affected | int | 0.71 | Number of rows affected by last query |
$insert_id | int | 0.71 | AUTO_INCREMENT ID from last INSERT |
$func_call | string | 3.0.0 | Description of last query call |
Query Logging
| Property | Type | Since | Description |
|---|---|---|---|
$queries | array[] | 1.5.0 | Log of executed queries (when SAVEQUERIES enabled) |
Each query log entry is an array: [ SQL, time, caller, start_time, custom_data ]
Error Handling Properties
| Property | Type | Since | Description |
|---|---|---|---|
$show_errors | bool | 0.71 | Whether to display SQL errors |
$suppress_errors | bool | 2.5.0 | Whether to suppress errors during bootstrap |
$error | WP_Error|string | 2.5.0 | Last SQL error encountered |
Connection Properties
| Property | Type | Since | Description |
|---|---|---|---|
$ready | bool | 2.3.2 | Whether connection is ready for queries |
$blogid | int | 3.0.0 | Current blog ID |
$siteid | int | 3.0.0 | Current site/network ID |
$is_mysql | bool | 3.3.0 | Whether using MySQL |
Character Set Properties
| Property | Type | Since | Description |
|---|---|---|---|
$charset | string | 2.2.0 | Database character set |
$collate | string | 2.2.0 | Database collation |
$field_types | array | 2.8.0 | Format specifiers for known columns |
Protected/Private Properties
| Property | Type | Since | Description |
|---|---|---|---|
$dbh | mysqli|false|null | 0.71 | Database connection handle |
$dbuser | string | 2.9.0 | Database username |
$dbpassword | string | 3.1.0 | Database password |
$dbname | string | 3.1.0 | Database name |
$dbhost | string | 3.1.0 | Database host |
$result | mysqli_result|bool|null | 0.71 | Raw query result |
$col_info | array | 0.71 | Column info from last query |
$col_meta | array | 4.2.0 | Cached column metadata |
$table_charset | string[] | 4.2.0 | Cached table charsets |
$reconnect_retries | int | 3.9.0 | Connection retry attempts (default 5) |
$incompatible_modes | string[] | 3.9.0 | SQL modes to disable |
$time_start | float | 1.5.0 | Query timer start time |
Methods
Constructor
__construct()
Creates a database connection.
public function __construct( $dbuser, $dbpassword, $dbname, $dbhost )| Parameter | Type | Description |
|---|---|---|
$dbuser | string | Database username |
$dbpassword | string | Database password |
$dbname | string | Database name |
$dbhost | string | Database host |
Note: WordPress creates the global $wpdb instance automatically. Don’t instantiate manually unless creating a secondary connection.
Query Methods
query()
Executes a database query.
public function query( $query ): int|bool| Parameter | Type | Description |
|---|---|---|
$query | string | SQL query to execute |
Returns:
int– Number of rows affected/selectedtrue– For CREATE, ALTER, TRUNCATE, DROPfalse– On error
Example:
// SELECT - returns row count
$count = $wpdb->query( "SELECT * FROM {$wpdb->posts}" );
// UPDATE - returns affected rows
$affected = $wpdb->query(
$wpdb->prepare( "UPDATE {$wpdb->posts} SET post_status = %s WHERE ID = %d", 'draft', 123 )
);
// CREATE - returns true
$result = $wpdb->query( "CREATE TABLE my_table (id INT)" );get_var()
Retrieves a single value from the database.
public function get_var( $query = null, $x = 0, $y = 0 ): string|null| Parameter | Type | Default | Description |
|---|---|---|---|
$query | string|null | null | SQL query. Null uses previous result |
$x | int | 0 | Column index |
$y | int | 0 | Row index |
Returns: String value or null on failure.
Example:
// Count posts
$count = $wpdb->get_var( "SELECT COUNT(*) FROM {$wpdb->posts}" );
// Get specific value
$title = $wpdb->get_var(
$wpdb->prepare( "SELECT post_title FROM {$wpdb->posts} WHERE ID = %d", 123 )
);
// Get from cached result (different column)
$wpdb->query( "SELECT post_title, post_date FROM {$wpdb->posts} LIMIT 1" );
$title = $wpdb->get_var( null, 0 ); // First column
$date = $wpdb->get_var( null, 1 ); // Second columnget_row()
Retrieves a single row from the database.
public function get_row( $query = null, $output = OBJECT, $y = 0 ): array|object|null|void| Parameter | Type | Default | Description |
|---|---|---|---|
$query | string|null | null | SQL query |
$output | string | OBJECT | Output format: OBJECT, ARRAY_A, ARRAY_N |
$y | int | 0 | Row to return (0-indexed) |
Returns: Row data or null.
Example:
// As object
$row = $wpdb->get_row(
$wpdb->prepare( "SELECT * FROM {$wpdb->posts} WHERE ID = %d", 123 )
);
echo $row->post_title;
// As associative array
$row = $wpdb->get_row(
$wpdb->prepare( "SELECT * FROM {$wpdb->posts} WHERE ID = %d", 123 ),
ARRAY_A
);
echo $row['post_title'];
// As numeric array
$row = $wpdb->get_row(
$wpdb->prepare( "SELECT * FROM {$wpdb->posts} WHERE ID = %d", 123 ),
ARRAY_N
);
echo $row[0]; // First columnget_col()
Retrieves one column from the database.
public function get_col( $query = null, $x = 0 ): array| Parameter | Type | Default | Description |
|---|---|---|---|
$query | string|null | null | SQL query |
$x | int | 0 | Column to return (0-indexed) |
Returns: Array of values from the specified column.
Example:
// Get all post IDs
$ids = $wpdb->get_col( "SELECT ID FROM {$wpdb->posts} WHERE post_status = 'publish'" );
// Returns: array( 1, 2, 3, 4, ... )
// Get second column from cached result
$wpdb->query( "SELECT ID, post_title FROM {$wpdb->posts}" );
$titles = $wpdb->get_col( null, 1 );get_results()
Retrieves multiple rows from the database.
public function get_results( $query = null, $output = OBJECT ): array|object|null| Parameter | Type | Default | Description |
|---|---|---|---|
$query | string|null | null | SQL query |
$output | string | OBJECT | Output format: OBJECT, OBJECT_K, ARRAY_A, ARRAY_N |
Returns: Array of results or null.
Output Formats:
| Constant | Description |
|---|---|
OBJECT | Array of row objects |
OBJECT_K | Associative array keyed by first column value |
ARRAY_A | Array of associative arrays |
ARRAY_N | Array of numeric arrays |
Example:
// Array of objects
$posts = $wpdb->get_results( "SELECT * FROM {$wpdb->posts} LIMIT 10" );
foreach ( $posts as $post ) {
echo $post->post_title;
}
// Keyed by ID
$posts = $wpdb->get_results(
"SELECT ID, post_title FROM {$wpdb->posts}",
OBJECT_K
);
echo $posts[123]->post_title; // Access by ID
// Array of associative arrays
$posts = $wpdb->get_results(
"SELECT * FROM {$wpdb->posts}",
ARRAY_A
);
foreach ( $posts as $post ) {
echo $post['post_title'];
}Data Manipulation Methods
insert()
Inserts a row into a table.
public function insert( $table, $data, $format = null ): int|false| Parameter | Type | Description |
|---|---|---|
$table | string | Table name |
$data | array | Column => value pairs |
$format | string[]|string|null | Format for each value (%d, %f, %s) |
Returns: Number of rows inserted (1) or false on error.
Example:
// Basic insert
$wpdb->insert(
$wpdb->postmeta,
array(
'post_id' => 123,
'meta_key' => '_custom_key',
'meta_value' => 'custom_value',
)
);
$meta_id = $wpdb->insert_id;
// With explicit formats
$wpdb->insert(
$wpdb->posts,
array(
'post_title' => 'Hello World',
'post_content' => 'Content here',
'post_status' => 'publish',
'post_author' => 1,
),
array( '%s', '%s', '%s', '%d' )
);
// NULL values
$wpdb->insert(
$wpdb->posts,
array(
'post_title' => 'Title',
'post_parent' => null, // Sets to NULL
)
);replace()
Replaces a row or inserts if it doesn’t exist (based on PRIMARY KEY or UNIQUE index).
public function replace( $table, $data, $format = null ): int|false| Parameter | Type | Description |
|---|---|---|
$table | string | Table name |
$data | array | Column => value pairs (must include key column) |
$format | string[]|string|null | Format for each value |
Returns: Number of rows affected (1 for insert, 2 for replace) or false on error.
Example:
// Replace existing or insert new
$wpdb->replace(
$wpdb->options,
array(
'option_name' => 'my_option',
'option_value' => 'new_value',
'autoload' => 'yes',
),
array( '%s', '%s', '%s' )
);update()
Updates rows in a table.
public function update( $table, $data, $where, $format = null, $where_format = null ): int|false| Parameter | Type | Description |
|---|---|---|
$table | string | Table name |
$data | array | Column => value pairs to update |
$where | array | Column => value pairs for WHERE clause |
$format | string[]|string|null | Format for $data values |
$where_format | string[]|string|null | Format for $where values |
Returns: Number of rows updated or false on error.
Example:
// Update post
$wpdb->update(
$wpdb->posts,
array(
'post_title' => 'New Title',
'post_status' => 'draft',
),
array( 'ID' => 123 ),
array( '%s', '%s' ),
array( '%d' )
);
// Update with NULL in WHERE
$wpdb->update(
$wpdb->posts,
array( 'post_status' => 'trash' ),
array( 'post_parent' => null ) // WHERE post_parent IS NULL
);delete()
Deletes rows from a table.
public function delete( $table, $where, $where_format = null ): int|false| Parameter | Type | Description |
|---|---|---|
$table | string | Table name |
$where | array | Column => value pairs for WHERE clause |
$where_format | string[]|string|null | Format for $where values |
Returns: Number of rows deleted or false on error.
Example:
// Delete post meta
$wpdb->delete(
$wpdb->postmeta,
array(
'post_id' => 123,
'meta_key' => '_custom_key',
),
array( '%d', '%s' )
);
// Delete by NULL
$wpdb->delete(
$wpdb->posts,
array( 'post_author' => null ) // WHERE post_author IS NULL
);Prepared Statement Methods
prepare()
Prepares a SQL query for safe execution.
public function prepare( $query, ...$args ): string|void| Parameter | Type | Description |
|---|---|---|
$query | string | Query with placeholders |
...$args | mixed | Values to substitute |
Placeholders:
| Placeholder | Type | Description |
|---|---|---|
%d | int | Integer |
%f | float | Float |
%s | string | String (auto-quoted) |
%i | identifier | Table/column name (since 6.2) |
Returns: Sanitized query string.
Example:
// Basic usage
$sql = $wpdb->prepare(
"SELECT * FROM {$wpdb->posts} WHERE ID = %d AND post_status = %s",
123,
'publish'
);
// Array of arguments
$sql = $wpdb->prepare(
"SELECT * FROM {$wpdb->posts} WHERE ID = %d",
array( 123 )
);
// Identifier placeholder
$sql = $wpdb->prepare(
"SELECT * FROM %i WHERE %i = %s",
'my_table',
'my_column',
'value'
);
// Numbered placeholders
$sql = $wpdb->prepare(
"SELECT * FROM {$wpdb->posts} WHERE post_author = %1$d OR post_parent = %1$d",
$user_id
);
// Escaping literal %
$sql = $wpdb->prepare(
"SELECT DATE_FORMAT(post_date, '%%Y-%%m-%%d') FROM {$wpdb->posts} WHERE ID = %d",
123
);esc_like()
Escapes LIKE wildcards (%, _, ) before using in prepare().
public function esc_like( $text ): string| Parameter | Type | Description |
|---|---|---|
$text | string | Raw text to escape |
Returns: Escaped text safe for LIKE.
Example:
$search = '%test_value%';
$like = '%' . $wpdb->esc_like( $search ) . '%';
$sql = $wpdb->prepare(
"SELECT * FROM {$wpdb->posts} WHERE post_title LIKE %s",
$like
);
// Result: WHERE post_title LIKE '%%test_value%%'Escaping Methods
_real_escape()
Escapes a string using mysqli_real_escape_string().
public function _real_escape( $data ): stringNote: Prefer prepare() over direct escaping.
_escape()
Escapes data (works on arrays).
public function _escape( $data ): string|arrayescape_by_ref()
Escapes content by reference.
public function escape_by_ref( &$data ): voidquote_identifier()
Quotes an identifier (table/column name).
public function quote_identifier( $identifier ): stringSince: 6.2.0
Example:
$quoted = $wpdb->quote_identifier( 'table_name' );
// Returns: `table_name`
$quoted = $wpdb->quote_identifier( 'col`name' );
// Returns: `col``name` (backtick escaped)Table & Prefix Methods
tables()
Returns an array of WordPress table names.
public function tables( $scope = 'all', $prefix = true, $blog_id = 0 ): string[]| Parameter | Type | Default | Description |
|---|---|---|---|
$scope | string | ‘all’ | Table scope: ‘all’, ‘blog’, ‘global’, ‘ms_global’, ‘old’ |
$prefix | bool | true | Whether to include table prefix |
$blog_id | int | 0 | Blog ID for prefix (multisite) |
Returns: Array of table names.
Example:
// All tables with prefix
$tables = $wpdb->tables();
// array( 'posts' => 'wp_posts', 'comments' => 'wp_comments', ... )
// Blog-specific tables only
$tables = $wpdb->tables( 'blog' );
// Global tables only
$tables = $wpdb->tables( 'global' );
// Without prefixes
$tables = $wpdb->tables( 'all', false );
// array( 'posts', 'comments', 'users', ... )set_prefix()
Sets the table prefix.
public function set_prefix( $prefix, $set_table_names = true ): string|WP_Error| Parameter | Type | Default | Description |
|---|---|---|---|
$prefix | string | – | New prefix (alphanumeric + underscore) |
$set_table_names | bool | true | Whether to update table name properties |
Returns: Old prefix or WP_Error on invalid prefix.
get_blog_prefix()
Gets the prefix for a specific blog.
public function get_blog_prefix( $blog_id = null ): string| Parameter | Type | Default | Description |
|---|---|---|---|
$blog_id | int|null | null | Blog ID (null for current) |
Returns: Blog table prefix.
Example:
$prefix = $wpdb->get_blog_prefix( 2 );
// Returns: wp_2_ (for blog ID 2 in multisite)set_blog_id()
Sets the blog ID and updates table prefixes.
public function set_blog_id( $blog_id, $network_id = 0 ): intReturns: Previous blog ID.
Connection Methods
db_connect()
Connects to the database server.
public function db_connect( $allow_bail = true ): bool| Parameter | Type | Default | Description |
|---|---|---|---|
$allow_bail | bool | true | Whether to die on failure |
Returns: True on success, false on failure.
check_connection()
Checks if connection is alive and reconnects if needed.
public function check_connection( $allow_bail = true ): bool|voidReturns: True if connected.
select()
Selects a database.
public function select( $db, $dbh = null ): voidclose()
Closes the database connection.
public function close(): boolSince: 4.5.0
Returns: True on success, false on failure.
parse_db_host()
Parses the DB_HOST setting for mysqli_real_connect().
public function parse_db_host( $host ): array|falseSince: 4.9.0
Returns: Array of [ host, port, socket, is_ipv6 ] or false.
Error Handling Methods
show_errors()
Enables showing database errors.
public function show_errors( $show = true ): boolReturns: Previous show_errors state.
hide_errors()
Disables showing database errors.
public function hide_errors(): boolReturns: Previous show_errors state.
suppress_errors()
Suppresses database errors.
public function suppress_errors( $suppress = true ): boolReturns: Previous suppress_errors state.
print_error()
Prints/logs a SQL error.
public function print_error( $str = '' ): void|falsebail()
Displays error and dies (if show_errors enabled).
public function bail( $message, $error_code = '500' ): void|falseCharacter Set Methods
init_charset()
Initializes charset and collate properties.
public function init_charset(): voiddetermine_charset()
Determines the best charset and collation.
public function determine_charset( $charset, $collate ): arrayReturns: Array with ‘charset’ and ‘collate’ keys.
set_charset()
Sets the connection’s character set.
public function set_charset( $dbh, $charset = null, $collate = null ): voidget_charset_collate()
Gets the database charset collate for CREATE TABLE.
public function get_charset_collate(): stringReturns: e.g., "DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_520_ci"
Example:
$charset_collate = $wpdb->get_charset_collate();
$sql = "CREATE TABLE my_table (
id INT AUTO_INCREMENT,
name VARCHAR(255),
PRIMARY KEY (id)
) $charset_collate";get_table_charset()
Gets the character set for a table.
protected function get_table_charset( $table ): string|WP_Errorget_col_charset()
Gets the character set for a column.
public function get_col_charset( $table, $column ): string|false|WP_Errorget_col_length()
Gets the maximum string length for a column.
public function get_col_length( $table, $column ): array|false|WP_ErrorReturns: Array with ‘type’ (‘byte’ or ‘char’) and ‘length’, or false.
SQL Mode Methods
set_sql_mode()
Sets SQL mode for WordPress compatibility.
public function set_sql_mode( $modes = array() ): voidRemoves incompatible modes: NO_ZERO_DATE, ONLY_FULL_GROUP_BY, STRICT_TRANS_TABLES, STRICT_ALL_TABLES, TRADITIONAL, ANSI.
Capability Methods
has_cap()
Checks if the database supports a feature.
public function has_cap( $db_cap ): bool| Capability | Since | Description |
|---|---|---|
collation | 2.5.0 | Collation support |
group_concat | 2.7.0 | GROUP_CONCAT function |
subqueries | 2.7.0 | Subquery support |
set_charset | 2.7.0 | SET NAMES support |
utf8mb4 | 4.1.0 | 4-byte UTF-8 (always true since 6.6) |
utf8mb4_520 | 4.6.0 | utf8mb4_unicode_520_ci |
identifier_placeholders | 6.2.0 | %i placeholder support |
Example:
if ( $wpdb->has_cap( 'utf8mb4_520' ) ) {
// Use better collation
}Column Info Methods
get_col_info()
Gets column metadata from the last query.
public function get_col_info( $info_type = 'name', $col_offset = -1 ): mixed| Parameter | Type | Default | Description |
|---|---|---|---|
$info_type | string | ‘name’ | Info type: name, table, def, max_length, not_null, etc. |
$col_offset | int | -1 | Column index (-1 for all columns) |
Example:
$wpdb->query( "SELECT * FROM {$wpdb->posts} LIMIT 1" );
// Get all column names
$names = $wpdb->get_col_info( 'name' );
// Get specific column's max length
$max_length = $wpdb->get_col_info( 'max_length', 0 );Utility Methods
flush()
Clears cached query results.
public function flush(): voidResets: last_result, col_info, last_query, rows_affected, num_rows, last_error, and frees mysqli_result.
db_version()
Gets the database server version.
public function db_version(): string|nullReturns: Version number (e.g., "8.0.28").
db_server_info()
Gets raw database server version string.
public function db_server_info(): stringSince: 5.5.0
Returns: Full version string (e.g., "8.0.28-0ubuntu0.20.04.3").
check_database_version()
Checks if database meets minimum version requirement.
public function check_database_version(): void|WP_Errortimer_start()
Starts the query timer.
public function timer_start(): truetimer_stop()
Stops the query timer.
public function timer_stop(): floatReturns: Time spent in seconds.
get_caller()
Gets comma-separated list of calling functions.
public function get_caller(): stringlog_query()
Logs a query to the queries array.
public function log_query( $query, $query_time, $query_callstack, $query_start, $query_data ): voidSince: 5.3.0
Text Processing Methods
strip_invalid_text_for_column()
Strips invalid characters for a specific column.
public function strip_invalid_text_for_column( $table, $column, $value ): string|WP_Errorcheck_ascii()
Checks if a string is ASCII.
protected function check_ascii( $input_string ): boolPlaceholder Methods
placeholder_escape()
Generates a placeholder escape string.
public function placeholder_escape(): stringSince: 4.8.3
add_placeholder_escape()
Escapes % characters in a query.
public function add_placeholder_escape( $query ): stringremove_placeholder_escape()
Removes placeholder escapes from a query.
public function remove_placeholder_escape( $query ): stringMagic Methods
__get()
Makes private properties readable.
public function __get( $name ): mixed__set()
Makes private properties settable.
public function __set( $name, $value ): void__isset()
Checks if a private property is set.
public function __isset( $name ): bool__unset()
Unsets a private property.
public function __unset( $name ): voidDeprecated Methods
supports_collation()
Deprecated: 3.5.0 – Use has_cap( 'collation' ) instead.
public function supports_collation(): boolescape()
Deprecated: 3.6.0 – Use prepare() or esc_sql() instead.
public function escape( $data ): string|array_weak_escape()
Deprecated: 3.6.0 – Use prepare() or esc_sql() instead.
public function _weak_escape( $data ): stringConstants
These constants are defined in class-wpdb.php:
| Constant | Value | Description |
|---|---|---|
EZSQL_VERSION | ‘WP1.25’ | ezSQL version identifier |
OBJECT | ‘OBJECT’ | Return rows as objects |
OBJECT_K | ‘OBJECT_K’ | Return objects keyed by first column |
ARRAY_A | ‘ARRAY_A’ | Return rows as associative arrays |
ARRAY_N | ‘ARRAY_N’ | Return rows as numeric arrays |