dbDelta( string[]|string $queries = '', bool $execute = true ): string[]

Description

Compatibility

Present in every tracked release (6.7.7 to 7.1.0), and compiles on PHP 7.4 through 8.6-dev.

Parameters

$queriesstring[]|stringoptional

The query to run. Can be multiple queries in an array, or a string of queries separated by semicolons. Default empty string.Default: ''

$executebooloptional

Whether or not to execute the query right away.
Default true.Default: true

Return value

string[]

Strings containing the results of the various update queries.

Performance profile

How much work a call to dbDelta() does, and what it touches: the algorithmic scaling, the Zend instruction count per call across PHP versions, the hooks it hands control to, and the core code that calls it. Measured from the compiled opcodes, not a stopwatch, so every number is identical on any machine running the same PHP version, and every function in core is ranked by cost.

Cost class

Light

Touches nothing outside its own arguments.

Scaling

Scales with input

The body loops, so the work grows with what you pass in.

Instructions

46–51

Executed per call on PHP 8.5, depending on the branch taken. The body compiles to 577.

Plugin surface

3 hooks

Third-party callbacks on 'dbdelta_queries', 'dbdelta_create_queries', 'dbdelta_insert_queries' run inside this call, and their cost is not bounded by anything here.

Called by

3

3 places in core call this, so the cost is paid more often than your own code shows.

What it touches

• hookthird-party callbacksapply_filters()called directly

What one call costs · 1 distinct outcome

One number would be a lie: the work depends on which branch runs. These are every distinct cost dbDelta() can have, taken from its control-flow graph on PHP 8.5.

This body has more branch combinations than are worth enumerating, so the table covers the outcomes found first rather than every one that exists.

Hooks and filters fired · 3

3 hooks fire while dbDelta() runs, in this order:

1. 1
   apply_filters( dbdelta_queries )filterline 2956 (+20 into the body)

   Filters the dbDelta SQL queries.

2. 2
   apply_filters( dbdelta_create_queries )filterline 2997 (+61 into the body)

   Filters the dbDelta SQL queries for creating tables and/or databases.

3. 3
   apply_filters( dbdelta_insert_queries )filterline 3008 (+72 into the body)

   Filters the dbDelta SQL queries for inserting or updating.

Uses · 4

• wp_get_db_schema()Retrieve the SQL for creating database tables.
• apply_filters()Calls the callback functions that have been added to a filter hook.
• wp_should_upgrade_global_tables()Determine if global tables should be upgraded.
• str_contains()Polyfill for `str_contains()` function added in PHP 8.0.

Used by · 3

• install_network()Install Network.
• make_db_current()Updates the database tables to a new schema.
• make_db_current_silent()Updates the database tables to a new schema, but without displaying results.

Source code

View on Trac ↗View on GitHub ↗

2936function dbDelta( $queries = '', $execute = true ) { // phpcs:ignore WordPress.NamingConventions.ValidFunctionName.FunctionNameInvalid2937	global $wpdb;2938 2939	if ( in_array( $queries, array( '', 'all', 'blog', 'global', 'ms_global' ), true ) ) {2940		$queries = wp_get_db_schema( $queries );2941	}2942 2943	// Separate individual queries into an array.2944	if ( ! is_array( $queries ) ) {2945		$queries = explode( ';', $queries );2946		$queries = array_filter( $queries );2947	}2948 2949	/**2950	 * Filters the dbDelta SQL queries.2951	 *2952	 * @since 3.3.02953	 *2954	 * @param string[] $queries An array of dbDelta SQL queries.2955	 */2956	$queries = apply_filters( 'dbdelta_queries', $queries );2957 2958	$cqueries   = array(); // Creation queries.2959	$iqueries   = array(); // Insertion queries.2960	$for_update = array();2961 2962	// Create a tablename index for an array ($cqueries) of recognized query types.2963	foreach ( $queries as $qry ) {2964		if ( preg_match( '|CREATE TABLE ([^ ]*)|', $qry, $matches ) ) {2965			$table_name = trim( $matches[1], '`' );2966 2967			$cqueries[ $table_name ]   = $qry;2968			$for_update[ $table_name ] = 'Created table ' . $matches[1];2969			continue;2970		}2971 2972		if ( preg_match( '|CREATE DATABASE ([^ ]*)|', $qry, $matches ) ) {2973			array_unshift( $cqueries, $qry );2974			continue;2975		}2976 2977		if ( preg_match( '|INSERT INTO ([^ ]*)|', $qry, $matches ) ) {2978			$iqueries[] = $qry;2979			continue;2980		}2981 2982		if ( preg_match( '|UPDATE ([^ ]*)|', $qry, $matches ) ) {2983			$iqueries[] = $qry;2984			continue;2985		}2986	}2987 2988	/**2989	 * Filters the dbDelta SQL queries for creating tables and/or databases.2990	 *2991	 * Queries filterable via this hook contain "CREATE TABLE" or "CREATE DATABASE".2992	 *2993	 * @since 3.3.02994	 *2995	 * @param string[] $cqueries An array of dbDelta create SQL queries.2996	 */2997	$cqueries = apply_filters( 'dbdelta_create_queries', $cqueries );2998 2999	/**3000	 * Filters the dbDelta SQL queries for inserting or updating.3001	 *3002	 * Queries filterable via this hook contain "INSERT INTO" or "UPDATE".3003	 *3004	 * @since 3.3.03005	 *3006	 * @param string[] $iqueries An array of dbDelta insert or update SQL queries.3007	 */3008	$iqueries = apply_filters( 'dbdelta_insert_queries', $iqueries );3009 3010	$text_fields = array( 'tinytext', 'text', 'mediumtext', 'longtext' );3011	$blob_fields = array( 'tinyblob', 'blob', 'mediumblob', 'longblob' );3012	$int_fields  = array( 'tinyint', 'smallint', 'mediumint', 'int', 'integer', 'bigint' );3013 3014	$global_tables  = $wpdb->tables( 'global' );3015	$db_version     = $wpdb->db_version();

Changelog

Introduced in 1.5.0. One change between 6.7.7 and 7.1.0.

1. 6.7.7
2. 6.8.8
3. 6.9.7
4. 7.0.4
5. 7.1.0

Signature, return type and hooks compared across 5 parsed releases.

About this page

Parsed data

Generated from the wordpress-develop 7.0.4 tag, from src/wp-admin/includes/upgrade.php, and regenerated for each WordPress release so it tracks the code rather than a snapshot of it.

Corrections

Something wrong on this page? Report it and it gets fixed in the next regeneration.