Database Optimization

WordPress Database Connection: SSL, Charset, Collation, and Repair Constants

What DB_CHARSET, DB_COLLATE, WP_ALLOW_REPAIR and MYSQL_CLIENT_FLAGS do in core, plus a TLS test on WordPress's own connection. Checked 16 Nov 2026.

Varun DubeyVarun Dubey
·13 min read
Diagram of WordPress connecting to MySQL with the MYSQLI_CLIENT_SSL flag and the note that an empty Ssl_cipher means plain text

The database block in wp-config.php has four constants that change how WordPress talks to MySQL or MariaDB: DB_CHARSET and DB_COLLATE set the text encoding, MYSQL_CLIENT_FLAGS switches on TLS, and WP_ALLOW_REPAIR opens a repair page that needs no login. For a modern site, set DB_CHARSET to utf8mb4, leave DB_COLLATE empty, add MYSQLI_CLIENT_SSL to the flags when the database is on another host, and leave the repair flag out until you are mid-incident. We read the current WordPress core source (class-wpdb.php, load.php, repair.php and the upgrade routines on the trunk branch, 7.2 Beta 5 on the day we checked) and the official docs on 16 November 2026, and found that several things older guides say about these constants are wrong. We flag each of them below.

No search queries have been recorded for this page yet, so the headings follow the questions people ask when this goes wrong: what the constants do, how to convert an old database, why an import fails with an unknown collation, whether the repair flag is safe, and how to know that the database connection is really encrypted.

Constant

Sample file value

What core does with it

Set it when

DB_CHARSET

utf8mb4

Used for the connection and for new tables; a value of utf8 is upgraded to utf8mb4 at runtime

Always, to utf8mb4

DB_COLLATE

empty string

Empty means core picks a collation for the charset

Rarely, to pin one

WP_ALLOW_REPAIR

not set

Unlocks the repair page, with no login

Only during an incident

MYSQL_CLIENT_FLAGS

not set (0)

Passed as flags to the database connection call

For TLS to a remote database

Checked on 16 November 2026 against wp-config-sample.php and class-wpdb.php in WordPress core trunk.

What do DB_CHARSET and DB_COLLATE actually do?

They tell WordPress which character set and sort rules to use for the connection and for any table it creates. The character set decides which characters can be stored. The collation decides how they compare and sort. The sample config file ships DB_CHARSET as utf8mb4 and DB_COLLATE as an empty string, and for most sites that pair should stay as it is.

The behaviour is more forgiving than most guides suggest. In wpdb::init_charset(), core reads both constants and then passes them to determine_charset() once it has a live connection. That method makes three changes:

  1. If the charset is utf8, it switches to utf8mb4. MySQL’s own manual says utf8mb3 is deprecated and that utf8 is a deprecated alias for it.
  2. If the charset is utf8mb4 and the collation is empty or utf8_general_ci, it uses utf8mb4_unicode_ci. Other utf8_ collation names get the utf8mb4_ prefix.
  3. If the result is utf8mb4_unicode_ci and the server is version 5.6 or later, it upgrades again to utf8mb4_unicode_520_ci.

So an empty DB_COLLATE does not mean “the server default”, which is what an earlier version of this article said. It means core’s own choice, which is utf8mb4_unicode_520_ci on any current server. That matters when your server default is different. MySQL 8 tags new tables with utf8mb4_0900_ai_ci when nothing else is specified, but WordPress creates its tables through dbDelta() using get_charset_collate(), which writes the charset and collation core resolved. Tables made by plugins that skip that helper take the server default, which is how a mix of collations gets into one database.

Two more details worth knowing:

  • On multisite, core starts from utf8 and utf8_general_ci, then lets DB_CHARSET and DB_COLLATE override them. The runtime upgrade to utf8mb4 still applies afterwards.
  • Since WordPress 6.6, the utf8mb4 capability check in wpdb::has_cap() always returns true, so core no longer treats a server as “unable to do utf8mb4”.

When should you set DB_COLLATE yourself? Pin it only when you need identical collations between a primary and replicas, or when a host’s tooling creates tables with a collation you do not want and you need core’s tables to match a fixed target. For everything else, leave it empty and let core resolve it.

How can I check which collation my tables really use?

Ask the database. The constants describe what WordPress asks for on each connection, while the tables hold what is actually stored. This query counts tables by collation, which shows a half-finished migration at a glance.

# Tables per collation (checked 16 Nov 2026)
wp db query "
  SELECT TABLE_COLLATION, COUNT(*) AS tables_count
  FROM information_schema.TABLES
  WHERE TABLE_SCHEMA = DATABASE() AND TABLE_TYPE = 'BASE TABLE'
  GROUP BY TABLE_COLLATION
  ORDER BY tables_count DESC;
"

A healthy result has one row, or two where a plugin deliberately uses a binary collation. If you see utf8_general_ci or utf8mb3 collations beside utf8mb4 ones, you have an unfinished conversion. Fix it before the first cross-table join fails with the MySQL error Illegal mix of collations. Plugin tables are the usual cause, because core only converts its own tables.

Note that wp db query runs through the MySQL command-line client, using the credentials from your config. That is fine for reading table metadata. It is not fine for testing the encryption of WordPress’s own connection, and we explain why further down.

How do I convert an old database to utf8mb4?

Core converts its own tables once, then stops. The upgrade routine runs maybe_convert_table_to_utf8mb4() for the standard tables when a site upgrades from a database version older than 33055 (that is the WordPress 4.2 era). The function only converts a table whose columns are all utf8 or utf8mb4, and it runs ALTER TABLE ... CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci. It does not touch plugin tables, and it skips any table that holds a column in some other charset.

That leaves plugin and custom tables for you to convert. Work through it in this order, on a staging copy first.

  1. Take a backup you can restore. Run wp db export and keep the file somewhere other than the server.
  2. Generate the statements and read them. The query below writes one ALTER per base table that is not already utf8mb4.
  3. Run them in a quiet window. Converting a table rebuilds it, so big tables take time and extra disk space, and writes to that table wait meanwhile.
  4. Re-run the collation count from the previous section and expect one row.
# 1. Back up (checked 16 Nov 2026)
wp db export ~/backup-before-utf8mb4.sql

# 2. Generate the statements for tables that are not utf8mb4 yet
wp db query --skip-column-names "
  SELECT CONCAT('ALTER TABLE \`', TABLE_NAME, '\` CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_520_ci;')
  FROM information_schema.TABLES
  WHERE TABLE_SCHEMA = DATABASE()
    AND TABLE_TYPE = 'BASE TABLE'
    AND TABLE_COLLATION NOT LIKE 'utf8mb4%';
" > convert.sql

# 3. Read convert.sql, then run it
wp db query < convert.sql

We chose utf8mb4_unicode_520_ci to match what core resolves for an empty DB_COLLATE. If you run MariaDB, check that your version offers that collation with SHOW COLLATION LIKE 'utf8mb4_unicode_520_ci' before you start.

What if the ALTER fails with “key was too long”?

A 4-byte character set needs more bytes per character, and an index over a long text column can pass the engine’s limit. Core’s own schema avoids the problem by indexing only the first 191 characters of a column such as option_name (the $max_index_length = 191 value in schema.php). Current MySQL and MariaDB defaults allow much longer keys than the old 767-byte limit, so this mostly appears on very old servers or on plugin tables with unusually long indexed columns. If you hit the error, shorten the index to a prefix for that table, then repeat the conversion for it alone.

What about code that names a collation?

Search your custom code and plugin code for hard-coded COLLATE utf8_general_ci in raw SQL. After a global conversion those clauses still run, but they now compare a utf8mb4 column against an old collation name, and MySQL rejects the mix with the collation error above. Change the clause or remove it.

Why does an import fail with “Unknown collation utf8mb4_0900_ai_ci”?

Because the dump came from a newer MySQL than the one you are importing into. MySQL 8 gives new tables the utf8mb4_0900_ai_ci collation. MariaDB does not know that name, and neither do MySQL 5.7 and older, so the import stops with error 1273. The cause is the dump file, not WordPress. It is a common migration failure: a WordPress.org thread about a MySQL 8 to MariaDB move shows a migration plugin’s collation check passing for utf8mb4_unicode_520_ci and failing for utf8mb4_0900_ai_ci on the target.

The fix is to rewrite the collation name in the dump before you import it. Pick a collation the target supports, and use the same one that WordPress itself resolves so the site ends up consistent.

# Rewrite the collation in a dump, keeping a copy (checked 16 Nov 2026)
cp site.sql site.sql.orig
sed -i.bak 's/utf8mb4_0900_ai_ci/utf8mb4_unicode_520_ci/g' site.sql
wp db import site.sql

The -i.bak form works on both GNU and macOS sed. Do not rewrite utf8mb4 to utf8 to make an import pass. That throws away emoji and every other 4-byte character in your content, and it is the opposite of what this article is about. Several hosting knowledge bases, including cPanel’s article on this exact error, describe the same edit-the-dump route.

What does WP_ALLOW_REPAIR do, and is it safe to leave on?

It unlocks /wp-admin/maint/repair.php, and it is not safe to leave on. The WordPress documentation says the flag “should only be enabled if needed and disabled once the issue is solved,” and states that a user “does not need to be logged in” to use the page. Core’s own text on the success screen says to remove the line to stop “unauthorized users” from using the page.

What the page does is also narrower than older guides claim. Without the flag it only prints the line to add. With the flag, it shows two links. The first runs a check and repair on the standard tables. The second adds an optimise step through the repair=2 query value. A tables_to_repair filter lets plugins add their own tables to the list. Core runs REPAIR TABLE only on tables that report a problem.

Here is the catch that makes the page less useful than it sounds. MySQL documents REPAIR TABLE as working for MyISAM, ARCHIVE and CSV tables. It does not list InnoDB, which is the default engine for almost every current WordPress database. If your tables are InnoDB, the repair step cannot do what its name promises, and a crash is handled by the engine’s own recovery when the server restarts. The page is mostly relevant to old MyISAM databases.

If you have shell access, skip the web page entirely. WP-CLI provides the same checks without an open endpoint:

# Check, then repair, then optimise (checked 16 Nov 2026)
wp db check
wp db repair
wp db optimize

When you must use the page, set the flag at the moment you need it and remove it straight after, so it never reaches version control:

wp config set WP_ALLOW_REPAIR true --raw
# ... open /wp-admin/maint/repair.php, run the repair ...
wp config delete WP_ALLOW_REPAIR

Both wp config set and wp config delete belong to WP-CLI’s config command group, and --raw writes the value as PHP rather than as a quoted string, as the config set reference describes.

How do I connect to MySQL over TLS from WordPress?

Define MYSQL_CLIENT_FLAGS as MYSQLI_CLIENT_SSL in wp-config.php. Core reads that constant in wpdb::db_connect() and passes it as the flags argument of mysqli_real_connect(). That is the whole built-in mechanism. WordPress has no DB_SSL constant and does not call mysqli_ssl_set(): we searched the current class-wpdb.php for any SSL handling and the flags line is the only match.

define( 'DB_HOST', 'db.internal.example.com:3306' );
define( 'MYSQL_CLIENT_FLAGS', MYSQLI_CLIENT_SSL );

The two flags worth knowing, according to the PHP manual:

Flag

What PHP says it does

Use it when

MYSQLI_CLIENT_SSL

Use SSL (encryption)

The database is on another host or network

MYSQLI_CLIENT_SSL_DONT_VERIFY_SERVER_CERT

Like the first, but disables validation of the server’s certificate; MySQL Native Driver and MySQL 5.6 or later only

A temporary diagnostic, or a trusted private network with a self-signed certificate

Checked on 16 November 2026 against the mysqli_real_connect manual page.

Does the TLS flag also verify the server?

Not by itself. The flag asks for encryption. Checking that the server is the one you meant requires a certificate authority file, and PHP’s mysqli_ssl_set() is where that is supplied. The manual says it must be called before mysqli_real_connect(). Since core makes both calls inside one method and never calls mysqli_ssl_set(), a CA path cannot be added from wp-config.php. You have three practical routes:

  • Private network plus encryption. Keep the database on a private network, require TLS on the server, and use the plain flag. The traffic is encrypted, the path is not exposed to the internet, and there is no custom code to maintain. This is the right answer for most sites.
  • A wp-content/db.php drop-in. Core loads this file in place of the default database class if it exists (load.php includes it right after the core class). A drop-in can subclass wpdb and call mysqli_ssl_set() before connecting, but it has to replace db_connect() in full, so it is code you own and re-test on each major release. A broken drop-in stops WordPress from booting, and there is no admin screen to remove it, so deploy it to staging first.
  • An existing drop-in plugin. The Secure DB Connection plugin does exactly this with custom constants, but its WordPress.org listing shows version 1.1.5, last updated July 2018, tested only up to WordPress 4.9 and about 100 active installs. We have not tested it on current WordPress, and we would not run unmaintained code at the database layer without reading it first.

Some managed hosts handle the certificate chain on their side and document the exact constants they expect. If you are on one, follow the host’s page over any generic advice.

Why does the connection fail once the server requires TLS?

MySQL has a server setting called require_secure_transport. When it is on, the server rejects any client that does not use an encrypted connection (or a Unix socket or shared memory), and the failure is reported as ER_SECURE_TRANSPORT_REQUIRED. In WordPress that appears as the “Error establishing a database connection” page, and with WP_DEBUG on you will see the PHP warning “Connections using insecure transport are prohibited while - require_secure_transport=ON”. A WordPress.org thread from 2017 shows the exact warning on a site whose database accepted only encrypted connections. The fix is the flag from the first code block, added before you turn the server setting on. Staging first, then production, in that order.

How do I prove that WordPress is really using TLS?

Ask the database from inside WordPress, using the connection WordPress itself opened. This is the most common mistake in TLS checks. wp db query runs the MySQL command-line client, and WP-CLI’s own page describes its options as arguments passed to the mysql program. MySQL’s manual says client programs try an encrypted connection by default and quietly fall back to an unencrypted one if that fails. So wp db query "SHOW STATUS LIKE 'Ssl_cipher'" can show a cipher while your PHP connection runs in plain text.

Use wp eval-file instead, so the query goes through $wpdb, the connection built with your MYSQL_CLIENT_FLAGS:

<?php
/**
 * File: check-db-tls.php   Run: wp eval-file check-db-tls.php
 * Reports the cipher on WordPress's own database connection.
 */
global $wpdb;

$cipher  = $wpdb->get_row( "SHOW SESSION STATUS LIKE 'Ssl_cipher'", ARRAY_A );
$version = $wpdb->get_row( "SHOW SESSION STATUS LIKE 'Ssl_version'", ARRAY_A );

if ( empty( $cipher['Value'] ) ) {
	WP_CLI::error( 'WordPress connection is NOT encrypted.' );
}

WP_CLI::success( sprintf( 'Encrypted: %s (%s)', $cipher['Value'], $version['Value'] ?? 'unknown' ) );

MySQL’s manual says to check the session value of Ssl_cipher: an empty value means the connection is not encrypted, and anything else is the cipher in use. The script follows that rule and exits with an error when the value is empty, which makes it usable from a deploy check or a scheduled job. Keep one caveat in mind: WP-CLI boots WordPress as a separate PHP process, so this proves your configuration produces an encrypted connection, and it does not inspect web requests already running. If your web workers use a different PHP configuration from the command line, repeat the check through a temporary protected page on staging.

Common mistakes people report

These come up again and again in support threads and host guides. We checked each link on 16 November 2026.

  1. Importing a MySQL 8 dump into an older server or MariaDB. The target does not know utf8mb4_0900_ai_ci. See the migration thread above. Rewrite the collation in the dump, never the character set.
  2. Turning on require_secure_transport before the TLS flag. The site goes down with the connection error. Add the flag first. The 2017 thread is an unresolved example of the same message, and a Microsoft Q&A post about Azure App Service describes the same failure and the same flag.
  3. Leaving WP_ALLOW_REPAIR in wp-config.php. The page needs no login, as the WordPress documentation states. Remove the line when the repair is done.
  4. Trusting a TLS test run through wp db query. The command-line client tries encryption by default, so it can look secure when WordPress is not. Test through $wpdb, as shown above.
  5. Using the verification-off flag as a permanent fix. MYSQLI_CLIENT_SSL_DONT_VERIFY_SERVER_CERT stops an invalid certificate from failing the connection by also removing the check. A forum answer suggesting it as a fix is fine for diagnosing, but do not leave it in production without a private-network reason.
  6. Converting core tables and forgetting plugin tables. The core routine only converts its own tables. Re-run the collation count after every migration.

How do I read a database connection error?

Match the symptom to the layer first, then fix that layer. Read the PHP error log and the database server log side by side, because the WordPress page shows the same five words for every cause. If debug.log stays empty while you do that, work through why debug.log is not created or not updating first, and if the whole screen is blank instead, start with our white screen of death guide.

What you see

Likely layer

First check

Error establishing a database connection after adding the TLS flag

Server TLS setup or CA

Turn on WP_DEBUG and read the warning from the connect call

Same error after enabling the server’s secure-transport requirement

Missing client flag

Confirm MYSQL_CLIENT_FLAGS is defined above the “stop editing” line

Emoji or some characters missing after save

Column charset narrower than the data

Run the collation count and convert the table

A query fails with an illegal mix of collations

Tables with different collations in one join

Convert the odd table to match the rest

Import stops on an unknown collation

Dump from a newer server

Rewrite the collation name in the dump

On the emoji row: core’s wpdb checks the column character set for its insert, update and replace helpers and strips characters the column cannot store, so text can be cut short with no error in WordPress itself (strip_invalid_text() in the core source). That makes this problem easy to miss. A raw query in strict mode instead returns MySQL’s “incorrect string value” error. Our guide to performance problems PageSpeed never shows covers the slow-query side of the same database layer.

What does a clean database block look like?

This is the version we would put in front of a managed database on its own private network. Replace the host, name and user with yours and keep the password out of the file, as the first line of the comment says.

// Credentials: read the password from the environment, never commit it.
define( 'DB_NAME',     'wp_prod' );
define( 'DB_USER',     'wp_app' );
define( 'DB_PASSWORD', getenv( 'WP_DB_PASSWORD' ) );
define( 'DB_HOST',     'db.internal.example.com:3306' );

// Encoding: core upgrades utf8 to utf8mb4 anyway; say what you mean.
define( 'DB_CHARSET', 'utf8mb4' );
define( 'DB_COLLATE', '' );

// Encrypt the connection to a remote database server.
define( 'MYSQL_CLIENT_FLAGS', MYSQLI_CLIENT_SSL );

// WP_ALLOW_REPAIR is deliberately absent. Set it only during an incident.

The block only sets up the connection. For the broader file, our write-up of the database-versus-file snippet question explains where site-specific code belongs so a restore does not erase it. Keep the TLS check script in version control next to this block, and run it after any change to hosting or PHP.

Frequently asked questions

Should DB_CHARSET be utf8 or utf8mb4?

utf8mb4. MySQL’s utf8 is the deprecated three-byte utf8mb3 and cannot store 4-byte characters such as emoji. Core upgrades a utf8 setting to utf8mb4 at runtime when the server supports it, but writing the real value in the file keeps your intent clear.

Do I have to set DB_COLLATE?

No. Leave it empty and core resolves a collation for you: utf8mb4_unicode_520_ci on a current server. Set it only to pin a specific collation across servers.

Is WP_ALLOW_REPAIR a security risk?

Yes while it is on, because the repair page needs no login. Turn it on for the repair, then remove it. If you have shell access, use wp db check and wp db repair instead.

Does REPAIR TABLE work on InnoDB?

MySQL’s manual lists MyISAM, ARCHIVE and CSV as the supported engines. InnoDB recovers through its own crash recovery on restart.

Which database versions does WordPress recommend now?

The WordPress.org requirements page recommends PHP 8.3 or greater and either MariaDB 10.11 or greater or MySQL 8.4 or greater. The code’s own minimum is still MySQL 5.5.5 and PHP 7.4, but those are legacy floors, and the page warns that old versions are past end of life.

Can I turn on TLS without changing code?

You need the one constant in wp-config.php. There is no setting in the dashboard for it. After you add it, test with wp eval-file, not wp db query.

How do I move a site between MySQL 8 and MariaDB safely?

Export, rewrite any utf8mb4_0900_ai_ci to utf8mb4_unicode_520_ci, import on staging, and run the collation count. Keep the original dump untouched so you can redo the step if the replacement collation is not the one you want.

What to do next

If you have not reviewed the rest of the site’s exposure, our five-minute security audit is a quick next step.

Run the collation count today. If it returns more than one row, plan the conversion with a backup first. If your database sits on another host, add the TLS flag and run the check script. Remove WP_ALLOW_REPAIR from any config that still has it.

Part of the Wbcom Designs family

The all-in-one WordPress community stack

Also ours: wbcomdesigns.comvapvarun.combrndle.com