wpdb::query() WordPress Method

The wpdb::query() method is used to execute a SQL query on the WordPress database. This method should be used when you need to execute a SQL query that is not a SELECT, UPDATE, DELETE, or INSERT query. For example, if you need to create or drop a database table, you would use the wpdb::query() method.

wpdb::query( string $query ) #

Performs a database query, using current database connection.

Description
Parameters
Return
Source
Related
- Uses
- Used By
Changelog

Description

More information can be found on the documentation page.

Top ↑

Parameters

$query: (string)(Required)Database query.

Top ↑

Return

(int|bool) Boolean true for CREATE, ALTER, TRUNCATE and DROP queries. Number of rows affected/selected for all other queries. Boolean false on error.

Top ↑

Source

File: wp-includes/wp-db.php

public function query( $query ) {
    if ( ! $this->ready ) {
        $this->check_current_query = true;
        return false;
    }
 
    /**
     * Filters the database query.
     *
     * Some queries are made before the plugins have been loaded,
     * and thus cannot be filtered with this method.
     *
     * @since 2.1.0
     *
     * @param string $query Database query.
     */
    $query = apply_filters( 'query', $query );
 
    if ( ! $query ) {
        $this->insert_id = 0;
        return false;
    }
 
    $this->flush();
 
    // Log how the function was called.
    $this->func_call = "\$db->query(\"$query\")";
 
    // If we're writing to the database, make sure the query will write safely.
    if ( $this->check_current_query && ! $this->check_ascii( $query ) ) {
        $stripped_query = $this->strip_invalid_text_from_query( $query );
        // strip_invalid_text_from_query() can perform queries, so we need
        // to flush again, just to make sure everything is clear.
        $this->flush();
        if ( $stripped_query !== $query ) {
            $this->insert_id  = 0;
            $this->last_query = $query;
 
            wp_load_translations_early();
 
            $this->last_error = __( 'WordPress database error: Could not perform query because it contains invalid data.' );
 
            return false;
        }
    }
 
    $this->check_current_query = true;
 
    // Keep track of the last query for debug.
    $this->last_query = $query;
 
    $this->_do_query( $query );
 
    // Database server has gone away, try to reconnect.
    $mysql_errno = 0;
    if ( ! empty( $this->dbh ) ) {
        if ( $this->use_mysqli ) {
            if ( $this->dbh instanceof mysqli ) {
                $mysql_errno = mysqli_errno( $this->dbh );
            } else {
                // $dbh is defined, but isn't a real connection.
                // Something has gone horribly wrong, let's try a reconnect.
                $mysql_errno = 2006;
            }
        } else {
            if ( is_resource( $this->dbh ) ) {
                $mysql_errno = mysql_errno( $this->dbh );
            } else {
                $mysql_errno = 2006;
            }
        }
    }
 
    if ( empty( $this->dbh ) || 2006 === $mysql_errno ) {
        if ( $this->check_connection() ) {
            $this->_do_query( $query );
        } else {
            $this->insert_id = 0;
            return false;
        }
    }
 
    // If there is an error then take note of it.
    if ( $this->use_mysqli ) {
        if ( $this->dbh instanceof mysqli ) {
            $this->last_error = mysqli_error( $this->dbh );
        } else {
            $this->last_error = __( 'Unable to retrieve the error message from MySQL' );
        }
    } else {
        if ( is_resource( $this->dbh ) ) {
            $this->last_error = mysql_error( $this->dbh );
        } else {
            $this->last_error = __( 'Unable to retrieve the error message from MySQL' );
        }
    }
 
    if ( $this->last_error ) {
        // Clear insert_id on a subsequent failed insert.
        if ( $this->insert_id && preg_match( '/^\s*(insert|replace)\s/i', $query ) ) {
            $this->insert_id = 0;
        }
 
        $this->print_error();
        return false;
    }
 
    if ( preg_match( '/^\s*(create|alter|truncate|drop)\s/i', $query ) ) {
        $return_val = $this->result;
    } elseif ( preg_match( '/^\s*(insert|delete|update|replace)\s/i', $query ) ) {
        if ( $this->use_mysqli ) {
            $this->rows_affected = mysqli_affected_rows( $this->dbh );
        } else {
            $this->rows_affected = mysql_affected_rows( $this->dbh );
        }
        // Take note of the insert_id.
        if ( preg_match( '/^\s*(insert|replace)\s/i', $query ) ) {
            if ( $this->use_mysqli ) {
                $this->insert_id = mysqli_insert_id( $this->dbh );
            } else {
                $this->insert_id = mysql_insert_id( $this->dbh );
            }
        }
        // Return number of rows affected.
        $return_val = $this->rows_affected;
    } else {
        $num_rows = 0;
        if ( $this->use_mysqli && $this->result instanceof mysqli_result ) {
            while ( $row = mysqli_fetch_object( $this->result ) ) {
                $this->last_result[ $num_rows ] = $row;
                $num_rows++;
            }
        } elseif ( is_resource( $this->result ) ) {
            while ( $row = mysql_fetch_object( $this->result ) ) {
                $this->last_result[ $num_rows ] = $row;
                $num_rows++;
            }
        }
 
        // Log and return the number of rows selected.
        $this->num_rows = $num_rows;
        $return_val     = $num_rows;
    }
 
    return $return_val;
}

Expand full source code Collapse full source codeView on TracView on GitHub

Top ↑

Uses

Uses
Uses	Description
wp-includes/wp-db.php:wpdb::check_ascii()	Checks if a string is ASCII.
wp-includes/wp-db.php:wpdb::strip_invalid_text_from_query()	Strips any invalid characters from the query.
wp-includes/l10n.php:__()	Retrieve the translation of $text.
wp-includes/load.php:wp_load_translations_early()	Attempt an early load of translations.
wp-includes/plugin.php:apply_filters()	Calls the callback functions that have been added to a filter hook.
wp-includes/wp-db.php:wpdb::_do_query()	Internal function to perform the mysql_query() call.
wp-includes/wp-db.php:wpdb::check_connection()	Checks that the connection to the database is still up. If not, try to reconnect.
wp-includes/wp-db.php:query	Filters the database query.
wp-includes/wp-db.php:wpdb::flush()	Kills cached query results.
wp-includes/wp-db.php:wpdb::print_error()	Prints SQL/DB error.

Show 5 more uses Hide more uses

Top ↑

Used By

Used By
Used By	Description
wp-includes/comment.php:_wp_batch_update_comment_type()	Updates the comment type for a batch of comments.
wp-includes/ms-site.php:wp_uninitialize_site()	Runs the uninitialization routine for a given site.
wp-admin/includes/schema.php:populate_network_meta()	Creates WordPress network meta and sets the default values.
wp-admin/includes/schema.php:populate_site_meta()	Creates WordPress site meta and sets the default values.
wp-includes/option.php:delete_expired_transients()	Deletes all expired transients.
wp-admin/includes/class-wp-upgrader.php:WP_Upgrader::create_lock()	Creates a lock using WordPress options.
wp-includes/taxonomy.php:_wp_batch_split_terms()	Splits a batch of shared taxonomy terms.
wp-admin/includes/media.php:wp_media_attach_action()	Encapsulates the logic for Attach/Detach actions.
wp-admin/includes/upgrade.php:maybe_convert_table_to_utf8mb4()	If a table only contains utf8 or utf8mb4 columns, convert it to utf8mb4.
wp-admin/install-helper.php:maybe_drop_column()	Drops column from database table, if it exists.
wp-admin/includes/schema.php:populate_options()	Create WordPress options and set the default values.
wp-admin/includes/upgrade.php:pre_schema_upgrade()	Runs before the schema is upgraded.
wp-admin/includes/upgrade.php:maybe_create_table()	Creates a table in the database, if it doesn’t already exist.
wp-admin/includes/upgrade.php:maybe_add_column()	Adds column to a database table, if it doesn’t already exist.
wp-admin/includes/upgrade.php:upgrade_network()	Executes network-level upgrade routines.
wp-admin/includes/upgrade.php:drop_index()	Drops a specified index from a table.
wp-admin/includes/upgrade.php:add_clean_index()	Adds an index to a specified table.
wp-admin/includes/upgrade.php:dbDelta()	Modifies the database based on specified SQL statements.
wp-admin/includes/upgrade.php:wp_install_defaults()	Creates the initial content for a newly-installed site.
wp-includes/deprecated.php:delete_usermeta()	Remove user meta data.
wp-includes/taxonomy.php:wp_set_object_terms()	Creates term and taxonomy relationships.
wp-includes/taxonomy.php:wp_remove_object_terms()	Removes term(s) associated with a given object.
wp-includes/option.php:add_option()	Adds a new option.
wp-includes/post.php:wp_untrash_post_comments()	Restore comments for a post from the Trash.
wp-includes/revision.php:_wp_upgrade_revisions_of_post()	Upgrade the revisions author, add the current post as a revision and set the revisions version to 1
wp-includes/ms-functions.php:remove_user_from_blog()	Removes a user from a blog.
wp-includes/wp-db.php:wpdb::_insert_replace_helper()	Helper function for insert and replace.
wp-includes/wp-db.php:wpdb::update()	Updates a row in the table.
wp-includes/wp-db.php:wpdb::delete()	Deletes a row in the table.
wp-includes/wp-db.php:wpdb::get_var()	Retrieves one variable from the database.
wp-includes/wp-db.php:wpdb::get_row()	Retrieves one row from the database.
wp-includes/wp-db.php:wpdb::get_col()	Retrieves one column from the database.
wp-includes/wp-db.php:wpdb::get_results()	Retrieves an entire SQL result set from the database (i.e., many rows).
wp-includes/comment.php:trackback()	Sends a Trackback.
wp-includes/comment.php:do_trackbacks()	Performs trackbacks.
wp-includes/meta.php:delete_metadata()	Deletes metadata for the specified object.

Show 31 more used by Hide more used by

Top ↑

Changelog

Changelog
Version	Description
0.71	Introduced.

wpdb::query() WordPress Method

wpdb::query( string $query ) #

Contents

Description

Parameters

Return

Source

Changelog

Hook

Class

Class Method