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

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|void

True if the connection is up.

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 ↗

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

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