wpdb::check_connection( bool $allow_bail = true ): bool

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

$allow_bailbooloptional

Allows the function to bail. Default true.Default: true

Return value

bool

Whether the connection is up. Exits if down and $allow_bail is true.

Performance profile

How much work a call to wpdb::check_connection() 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

12–88

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

Plugin surface

None

Nothing here hands control to plugin code.

Called by

1

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

What one call costs · 25 distinct outcomes

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

Uses · 6

• did_action()Retrieves the number of times an action has been fired during the current request.
• wp_load_translations_early()Attempts an early load of translations.
• __()Retrieves the translation of $text.
• dead_db()Loads custom DB error or display WordPress DB error.
• wpdb::db_connect()Connects to and selects database.
• wpdb::bail()Wraps errors in a nice header and footer and dies.

Used by · 1

• wpdb::query()Performs a database query, using current database connection.

Source code

View on Trac ↗View on GitHub ↗

2124	public function check_connection( $allow_bail = true ) {2125		// Check if the connection is alive.2126		if ( ! empty( $this->dbh ) && mysqli_query( $this->dbh, 'DO 1' ) !== false ) {2127			return true;2128		}2129 2130		$error_reporting = false;2131 2132		// Disable warnings, as we don't want to see a multitude of "unable to connect" messages.2133		if ( WP_DEBUG ) {2134			$error_reporting = error_reporting();2135			error_reporting( $error_reporting & ~E_WARNING );2136		}2137 2138		for ( $tries = 1; $tries <= $this->reconnect_retries; $tries++ ) {2139			/*2140			 * On the last try, re-enable warnings. We want to see a single instance2141			 * of the "unable to connect" message on the bail() screen, if it appears.2142			 */2143			if ( $this->reconnect_retries === $tries && WP_DEBUG ) {2144				error_reporting( $error_reporting );2145			}2146 2147			if ( $this->db_connect( false ) ) {2148				if ( $error_reporting ) {2149					error_reporting( $error_reporting );2150				}2151 2152				return true;2153			}2154 2155			sleep( 1 );2156		}2157 2158		/*2159		 * If template_redirect has already happened, it's too late for wp_die()/dead_db().2160		 * Let's just return and hope for the best.2161		 */2162		if ( did_action( 'template_redirect' ) ) {2163			return false;2164		}2165 2166		if ( ! $allow_bail ) {2167			return false;2168		}2169 2170		wp_load_translations_early();2171 2172		$message = '<h1>' . __( 'Error reconnecting to the database' ) . "</h1>\n";2173 2174		$message .= '<p>' . sprintf(2175			/* translators: %s: Database host. */2176			__( 'This means that the contact with the database server at %s was lost. This could mean your host&#8217;s database server is down.' ),2177			'<code>' . htmlspecialchars( $this->dbhost, ENT_QUOTES ) . '</code>'2178		) . "</p>\n";2179 2180		$message .= "<ul>\n";2181		$message .= '<li>' . __( 'Are you sure the database server is running?' ) . "</li>\n";2182		$message .= '<li>' . __( 'Are you sure the database server is not under particularly heavy load?' ) . "</li>\n";2183		$message .= "</ul>\n";2184 2185		$message .= '<p>' . sprintf(2186			/* translators: %s: Support forums URL. */2187			__( 'If you are unsure what these terms mean you should probably contact your host. If you still need help you can always visit the <a href="%s">WordPress support forums</a>.' ),2188			__( 'https://wordpress.org/support/forums/' )2189		) . "</p>\n";2190 2191		// We weren't able to reconnect, so we better bail.2192		$this->bail( $message, 'db_connect_fail' );2193 2194		/*2195		 * Call dead_db() if bail didn't die, because this database is no more.2196		 * It has ceased to be (at least temporarily).2197		 */2198		dead_db();2199	}

Changelog

Introduced in 3.9.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.1.0 tag, from src/wp-includes/class-wpdb.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.