Quick answer
These are two completely different operations, and people reach for the wrong one all the time.
Replacing a file changes what gets served from an address that already exists. A database search-and-replace changes stored text that points somewhere.
If https://example.com/wp-content/uploads/2026/01/handbook.pdf is already the address you want people to use, replacing the file behind it needs no URL rewriting at all. If the address itself has to change — old-domain.com becoming new-domain.com — then rewriting stored references is exactly right.
Using a search-and-replace to solve a file problem touches far more of your database than the job needs. Using a file replacement to solve a genuine URL migration will not update the references that have to change. Pick the one that matches what is actually changing.
Two layers
A media item in WordPress involves at least two things: the file itself, and all the places in the database that refer to it.
A search-and-replace works on the second. A replacement works on the first, while deliberately leaving the second alone.
Confusing the two is how a one-document update becomes a site-wide database change.
What wp search-replace actually does
The WP-CLI documentation describes it as searching rows in the database tables you select and replacing one string with another. It understands PHP serialized data and has a --dry-run mode.
That is the right tool for a domain migration, a changed URL prefix, a repeated stored string, or a controlled database migration.
It is not a tool that looks at a folder of PDFs and decides which document on your site each one replaces. It has no opinion about that, because it has never seen your folder.
Example: a revised handbook at the same address
The current URL is:
/wp-content/uploads/2026/01/employee-handbook.pdf
HR sends a revised handbook and wants that link to serve it.
If the replacement keeps the file where it is, there is no old string that needs to become a new string anywhere. A database search-and-replace would be answering a question nobody asked.
Example: the URL really did change
A migration moves documents from:
https://old.example.com/files/
to:
https://www.example.com/resources/
and your content genuinely contains the old prefix.
That is a rewriting job. A carefully scoped search-and-replace — with a backup and a dry run first — is exactly right.
Replacing files cannot make stored old URLs point somewhere new. Nothing about the file changes what your posts say.
Example: 80 revised PDFs with inconsistent names
The folder has:
policy-hr-final.pdfpolicy-it-2026.pdfsafety-west-rev2.pdfbenefits-salaried-clean.pdf
and the site has documents with entirely different historical filenames and titles.
There is no old string and new string here. There are eighty separate decisions with exceptions in them.
That needs matching, checking and a controlled replacement — not a global text substitution, which has no way to express “this one is uncertain”.
Why a broad search-and-replace is worth respecting
Your search string may appear in places you had not thought about: post content, options, widget or builder data, custom fields, plugin tables, serialized values, and depending on scope, logs and historical data.
WP-CLI offers table scoping and a dry run precisely because the operation is broad.
That does not make it unsafe. It makes scope the question that matters.
File replacement needs checking too
Replacing a file is narrower than rewriting database strings, and it still carries risk.
A wrong match puts the wrong document behind a perfectly valid URL.
That is arguably worse than a broken link, because the link works, the page looks right, and nobody finds out until somebody reads the document.
For a batch, check which document you are replacing — not just whether the filenames look alike.
Which to reach for
| Situation | Start here |
|---|---|
| Same URL, new file contents | Replace the file |
| Domain migration | Database search-and-replace |
| A known URL prefix changed | Scoped search-and-replace |
| 100 incoming files to map to 100 documents | A batch replacement workflow |
| One file has a corrected PDF | Single-file replacement |
| You need to find where a string occurs before changing it | Search first, write nothing yet |
Using both in one project
That happens, and it works — as long as the phases stay separate.
A migration might mean: move or replace the files, verify the addresses, rewrite only the references that genuinely changed, clear the relevant caches, and check a sample of pages and downloads.
Do not collapse those into one enormous “replace everything” action. When something goes wrong you will have no idea which part did it.
What WP Bulk Replace is for
Replacing media, particularly when a folder of incoming files has to be matched to existing documents as one reviewed batch.
It is not a general-purpose database tool. If what you actually need is “change this domain everywhere”, use something built for that.
FAQ
Will replacing a file update every URL in my database?
No, and it is not trying to. A replacement keeps the existing address so nothing needs rewriting.
Is wp search-replace safe?
It is a powerful administrative tool with scoping and a dry run. How safe it is depends on your search string, which tables you select, your backup, and whether you tested the exact command first. Do test it first.
Should I search-and-replace a PDF filename after uploading a new PDF?
Only if the address genuinely has to change and you understand every stored reference that needs rewriting. If you just want the new document at the existing address, replacing the file is much narrower.
Summary
Use the smallest operation that matches what is changing:
- contents changed, address stays → replace the file
- the address changed → rewrite the references, carefully
- many files need decisions → use a batch you can review.
It is a technical distinction, and it prevents a whole class of unnecessary database changes.
Related: File replacement vs FTP · File replacement vs a script · Check where a file is used · Replace a PDF without breaking links