Explain why certain tables can be skipped in search-replace

[Copilot]

Tables without a primary key are silently skipped during wp search-replace, leaving users with no indication of why or how to fix it.

Changes

• src/Search_Replace_Command.php: Added a paragraph to the command's docblock description noting that tables without a primary key are skipped, and how to diagnose the issue via wp db query 'DESCRIBE <table>' (look for PRI in the Key column).
• README.md: Reflected the same addition in the generated documentation.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Explain why certain tables can be skipped</issue_title>
<issue_description>We should have a more concise version of this in the command description:

One of the keys in each database table has to be marked as the primary key, or else WP-CLI will skip over it and output ‘skipped’ as shown above. To see if that’s your problem, use DESCRIBE to view the index data for one of the skipped tables, like this:

$ wp db query 'DESCRIBE wp_17_comments'

+----------------------+---------------------+------+-----+---------------------+-------+
| Field                | Type                | Null | Key | Default             | Extra |
+----------------------+---------------------+------+-----+---------------------+-------+
| comment_ID           | bigint(20) unsigned | NO   |     | NULL                |       |
| comment_post_ID      | bigint(20) unsigned | NO   |     | 0                   |       |
| comment_author       | tinytext            | NO   |     | NULL                |       |
| comment_author_email | varchar(100)        | NO   |     |                     |       |
| comment_author_url   | varchar(200)        | NO   |     |                     |       |
| comment_author_IP    | varchar(100)        | NO   |     |                     |       |
| comment_date         | datetime            | NO   |     | 0000-00-00 00:00:00 |       |
| comment_date_gmt     | datetime            | NO   |     | 0000-00-00 00:00:00 |       |
| comment_content      | text                | NO   |     | NULL                |       |
| comment_karma        | int(11)             | NO   |     | 0                   |       |
| comment_approved     | varchar(20)         | NO   |     | 1                   |       |
| comment_agent        | varchar(255)        | NO   |     |                     |       |
| comment_type         | varchar(20)         | NO   |     |                     |       |
| comment_parent       | bigint(20) unsigned | NO   |     | 0                   |       |
| user_id              | bigint(20) unsigned | NO   |     | 0                   |       |
+----------------------+---------------------+------+-----+---------------------+-------+

‘PRI’ should be listed in the Key column somewhere, but since it isn’t, WP-CLI doesn’t know which is the primary key and is consequently skipping the table. Since the example above is a WordPress comments table, comment_ID should have ‘PRI’ in the Key column. By looking at the table index data above (and thanks to help from @JPry), I was able to see that my table was missing much more than just the primary key and that an error had occurred when the database was exported/imported. So to fix the issue, I needed to get another copy of it and try the search-replace again.

From https://kellenmace.com/wp-cli-search-replace-tables-skipped/

Related https://wordpress.org/support/topic/wp-search-replace-skipped-tables/</issue_description>

Comments on the Issue (you are @copilot in this section)

@schlessera Maybe this is a good first use case for the error message redirection discussed in https://github.com/wp-cli/wp-cli/issues/4158 ? @danielbachhuber > Was the idea to just have a footer on the output linking to a KB article or this github issue about why tables are skipped

See the first line of the issue:

We should have a more concise version of this in the command description:

The goal is to have a concise version of the explanation in the command description.</comment_new>

• Fixes Explain why certain tables can be skipped #10

---

📍 Connect Copilot coding agent with Jira, Azure Boards or Linear to delegate work to Copilot in one click without leaving your project management tool.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[Copilot]

Pull request overview

Updates the wp search-replace command documentation to explain why some tables are skipped (missing primary key) and how users can diagnose this, improving UX for a common “skipped tables” confusion case.

Changes:

• Added a concise note to the search-replace command description explaining that tables without a primary key are skipped.
• Documented a quick diagnostic command (wp db query 'DESCRIBE <table>') and what to look for (PRI in the Key column).
• Reflected the same note in the generated README.md.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated no comments.

File	Description
src/Search_Replace_Command.php	Adds primary-key skip explanation + diagnosis tip to the command docblock.
README.md	Mirrors the same explanation in generated package documentation.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.