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

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

array

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 576.

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 2876 (+20 into the body)

   Filters the dbDelta SQL queries.

2. 2
   apply_filters( dbdelta_create_queries )filterline 2915 (+59 into the body)

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

3. 3
   apply_filters( dbdelta_insert_queries )filterline 2926 (+70 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 ↗

2856function dbDelta( $queries = '', $execute = true ) { // phpcs:ignore WordPress.NamingConventions.ValidFunctionName.FunctionNameInvalid2857	global $wpdb;2858 2859	if ( in_array( $queries, array( '', 'all', 'blog', 'global', 'ms_global' ), true ) ) {2860		$queries = wp_get_db_schema( $queries );2861	}2862 2863	// Separate individual queries into an array.2864	if ( ! is_array( $queries ) ) {2865		$queries = explode( ';', $queries );2866		$queries = array_filter( $queries );2867	}2868 2869	/**2870	 * Filters the dbDelta SQL queries.2871	 *2872	 * @since 3.3.02873	 *2874	 * @param string[] $queries An array of dbDelta SQL queries.2875	 */2876	$queries = apply_filters( 'dbdelta_queries', $queries );2877 2878	$cqueries   = array(); // Creation queries.2879	$iqueries   = array(); // Insertion queries.2880	$for_update = array();2881 2882	// Create a tablename index for an array ($cqueries) of recognized query types.2883	foreach ( $queries as $qry ) {2884		if ( preg_match( '|CREATE TABLE ([^ ]*)|', $qry, $matches ) ) {2885			$cqueries[ trim( $matches[1], '`' ) ] = $qry;2886			$for_update[ $matches[1] ]            = 'Created table ' . $matches[1];2887			continue;2888		}2889 2890		if ( preg_match( '|CREATE DATABASE ([^ ]*)|', $qry, $matches ) ) {2891			array_unshift( $cqueries, $qry );2892			continue;2893		}2894 2895		if ( preg_match( '|INSERT INTO ([^ ]*)|', $qry, $matches ) ) {2896			$iqueries[] = $qry;2897			continue;2898		}2899 2900		if ( preg_match( '|UPDATE ([^ ]*)|', $qry, $matches ) ) {2901			$iqueries[] = $qry;2902			continue;2903		}2904	}2905 2906	/**2907	 * Filters the dbDelta SQL queries for creating tables and/or databases.2908	 *2909	 * Queries filterable via this hook contain "CREATE TABLE" or "CREATE DATABASE".2910	 *2911	 * @since 3.3.02912	 *2913	 * @param string[] $cqueries An array of dbDelta create SQL queries.2914	 */2915	$cqueries = apply_filters( 'dbdelta_create_queries', $cqueries );2916 2917	/**2918	 * Filters the dbDelta SQL queries for inserting or updating.2919	 *2920	 * Queries filterable via this hook contain "INSERT INTO" or "UPDATE".2921	 *2922	 * @since 3.3.02923	 *2924	 * @param string[] $iqueries An array of dbDelta insert or update SQL queries.2925	 */2926	$iqueries = apply_filters( 'dbdelta_insert_queries', $iqueries );2927 2928	$text_fields = array( 'tinytext', 'text', 'mediumtext', 'longtext' );2929	$blob_fields = array( 'tinyblob', 'blob', 'mediumblob', 'longblob' );2930	$int_fields  = array( 'tinyint', 'smallint', 'mediumint', 'int', 'integer', 'bigint' );2931 2932	$global_tables  = $wpdb->tables( 'global' );2933	$db_version     = $wpdb->db_version();2934	$db_server_info = $wpdb->db_server_info();2935

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 6.7.7 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.