Title: maybe_convert_table_to_utf8mb4
Published: April 23, 2015
Last modified: May 20, 2026

---

# maybe_convert_table_to_utf8mb4( string $table ): bool

## In this article

 * [Parameters](https://developer.wordpress.org/reference/functions/maybe_convert_table_to_utf8mb4/?output_format=md#parameters)
 * [Return](https://developer.wordpress.org/reference/functions/maybe_convert_table_to_utf8mb4/?output_format=md#return)
 * [Source](https://developer.wordpress.org/reference/functions/maybe_convert_table_to_utf8mb4/?output_format=md#source)
 * [Related](https://developer.wordpress.org/reference/functions/maybe_convert_table_to_utf8mb4/?output_format=md#related)
 * [Changelog](https://developer.wordpress.org/reference/functions/maybe_convert_table_to_utf8mb4/?output_format=md#changelog)

[ Back to top](https://developer.wordpress.org/reference/functions/maybe_convert_table_to_utf8mb4/?output_format=md#wp--skip-link--target)

If a table only contains utf8 or utf8mb4 columns, convert it to utf8mb4.

## 󠀁[Parameters](https://developer.wordpress.org/reference/functions/maybe_convert_table_to_utf8mb4/?output_format=md#parameters)󠁿

 `$table`stringrequired

The table to convert.

## 󠀁[Return](https://developer.wordpress.org/reference/functions/maybe_convert_table_to_utf8mb4/?output_format=md#return)󠁿

 bool True if the table was converted, false if it wasn’t.

## 󠀁[Source](https://developer.wordpress.org/reference/functions/maybe_convert_table_to_utf8mb4/?output_format=md#source)󠁿

    ```php
    function maybe_convert_table_to_utf8mb4( $table ) {
    	global $wpdb;

    	$results = $wpdb->get_results( "SHOW FULL COLUMNS FROM `$table`" );
    	if ( ! $results ) {
    		return false;
    	}

    	foreach ( $results as $column ) {
    		if ( $column->Collation ) {
    			list( $charset ) = explode( '_', $column->Collation );
    			$charset         = strtolower( $charset );
    			if ( 'utf8' !== $charset && 'utf8mb4' !== $charset ) {
    				// Don't upgrade tables that have non-utf8 columns.
    				return false;
    			}
    		}
    	}

    	$table_details = $wpdb->get_row( "SHOW TABLE STATUS LIKE '$table'" );
    	if ( ! $table_details ) {
    		return false;
    	}

    	list( $table_charset ) = explode( '_', $table_details->Collation );
    	$table_charset         = strtolower( $table_charset );
    	if ( 'utf8mb4' === $table_charset ) {
    		return true;
    	}

    	return $wpdb->query( "ALTER TABLE $table CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci" );
    }
    ```

[View all references](https://developer.wordpress.org/reference/files/wp-admin/includes/upgrade.php/)
[View on Trac](https://core.trac.wordpress.org/browser/tags/7.0/src/wp-admin/includes/upgrade.php#L2796)
[View on GitHub](https://github.com/WordPress/wordpress-develop/blob/7.0/src/wp-admin/includes/upgrade.php#L2796-L2827)

## 󠀁[Related](https://developer.wordpress.org/reference/functions/maybe_convert_table_to_utf8mb4/?output_format=md#related)󠁿

| Uses | Description | 
| [wpdb::get_row()](https://developer.wordpress.org/reference/classes/wpdb/get_row/)`wp-includes/class-wpdb.php` |

Retrieves one row from the database.

  | 
| [wpdb::query()](https://developer.wordpress.org/reference/classes/wpdb/query/)`wp-includes/class-wpdb.php` |

Performs a database query, using current database connection.

  | 
| [wpdb::get_results()](https://developer.wordpress.org/reference/classes/wpdb/get_results/)`wp-includes/class-wpdb.php` |

Retrieves an entire SQL result set from the database (i.e., many rows).

  |

[Show 1 more](https://developer.wordpress.org/reference/functions/maybe_convert_table_to_utf8mb4/?output_format=md#)
[Show less](https://developer.wordpress.org/reference/functions/maybe_convert_table_to_utf8mb4/?output_format=md#)

| Used by | Description | 
| [pre_schema_upgrade()](https://developer.wordpress.org/reference/functions/pre_schema_upgrade/)`wp-admin/includes/upgrade.php` |

Runs before the schema is upgraded.

  | 
| [upgrade_network()](https://developer.wordpress.org/reference/functions/upgrade_network/)`wp-admin/includes/upgrade.php` |

Executes network-level upgrade routines.

  |

## 󠀁[Changelog](https://developer.wordpress.org/reference/functions/maybe_convert_table_to_utf8mb4/?output_format=md#changelog)󠁿

| Version | Description | 
| [4.2.0](https://developer.wordpress.org/reference/since/4.2.0/) | Introduced. |

## User Contributed Notes

You must [log in](https://login.wordpress.org/?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fmaybe_convert_table_to_utf8mb4%2F)
before being able to contribute a note or feedback.