Safely Replace Text with MariaDB's replace Utility

You will finish with a repeatable way to replace literal text in a stream, test several replacements together, and edit a file in place only after making a recoverable copy. This guide uses the replace utility installed by mariadb-client, not MariaDB's SQL REPLACE statement.

Allow about fifteen minutes. You need a shell and a small disposable text file. The installed package here is mariadb-client 1:10.11.14-0ubuntu0.24.04.1; the binary reports version 1.4. No command in the first part needs elevated privileges. Use sudo only if the real file is unreadable or needs root ownership, and check the result before changing it.

1. Confirm which replace you have

There are several tools and database features called replace. Check the path, package and utility version before relying on examples:

$ command -v replace
/usr/bin/replace
$ dpkg-query -W -f='${Package} ${Version}\n' mariadb-client
mariadb-client 1:10.11.14-0ubuntu0.24.04.1
$ replace -V
replace  Ver 1.4 for debian-linux-gnu at x86_64

Checkpoint: if command -v finds a different program, stop and read that program's manual page. This guide assumes the MariaDB utility with the syntax above.

2. Test through standard input first

Without --, replace reads standard input and writes the transformed text to standard output. The basic form is a pair of words, from and to:

$ printf 'alpha old\nbeta old\n' | replace old new
alpha new
beta new

The input is not modified by this form. Redirect the output to a new file when you need a result to keep:

$ printf 'alpha old\nbeta old\n' > input.txt
$ replace old new < input.txt > output.txt
$ diff -u input.txt output.txt
--- input.txt
+++ output.txt
@@ -1,2 +1,2 @@
-alpha old
-beta old
+alpha new
+beta new

Checkpoint: inspect output.txt before replacing the original. An empty output can be a valid result, so also check the exit status and file size when the input matters:

$ test -s output.txt && echo 'output is non-empty'
output is non-empty

3. Apply several pairs in one pass

Put each from string immediately before its to string. This is useful for a controlled vocabulary change:

$ printf 'old beta old\n' | replace old new beta BETA
new BETA new

Matching is not a regular expression exercise. The utility uses its own string matcher, and the MariaDB documentation also describes special markers in a from-string: ^ for the start of a line, $ for the end, and \b for a space, line start or line end. If those markers are meant literally, test them with a small fixture first. Quote arguments so the shell does not expand spaces or special characters before replace sees them.

Longer matches are selected first. That permits a swap without the first replacement destroying the second match:

$ printf 'a b ab ba\n' | replace a b b a
b a ba ab

Do not infer from this that replacements are a general parser. Test overlapping strings, line boundaries and non-ASCII data with representative input before using them in a migration.

4. Edit a file in place, with a rollback copy

Passing file names changes those files. The -- marker ends the replacement-pair list and begins the file list; it is not optional in this mode. The command reports files it converts:

$ cp --preserve=mode,timestamps config.txt config.txt.before-replace
$ replace old-name new-name -- config.txt
config.txt converted
$ diff -u config.txt.before-replace config.txt
--- config.txt.before-replace
+++ config.txt
@@ -1 +1 @@
-name=old-name
+name=new-name

This is the first state-changing step. The copy protects the original contents, but it does not make the operation transactional: a power failure or filesystem problem can still leave a partial or damaged file. For a critical configuration, work on a copy, validate it with the consuming program, then install it during an appropriate maintenance window.

Recovery is straightforward while the backup remains intact:

$ cp --preserve=mode,timestamps config.txt.before-replace config.txt
$ diff -u config.txt.before-replace config.txt
$ echo 'restored original content'
restored original content

Do not run this as root merely to avoid checking permissions. If the file belongs to a service, replacing it may alter live behaviour even though replace itself does not restart the service. Confirm the service's configuration before and after the change.

5. Use diagnostics without confusing them with validation

-s suppresses most messages, while -v prints more information. These options affect reporting, not the replacement rules:

$ printf 'old\n' > sample.txt
$ replace -s old new -- sample.txt
$ grep -Fx 'new' sample.txt
new
$ printf 'old\n' > sample.txt
$ replace -v old new -- sample.txt
User time 0.00, System time 0.00
Maximum resident set size 2048, Integral resident set size 0
...
sample.txt converted

The exact verbose statistics vary by build and system, so verify the file contents separately. With no matching text, standard-input mode emits the original input. In file mode, do not treat the absence of a conversion message as proof that the intended pattern was present or absent; compare the file with a known baseline or search for the old and new forms.

6. Avoid the common traps

• Forgetting -- means file names are not selected. The command reads standard input instead, which can look like a hang while it waits for input.
• Supplying an odd number of replacement arguments fails because every from-string needs a to-string. Keep pairs visually grouped and test the command on standard input first.
• Shell quoting still applies. Use single quotes for fixed text containing spaces, and use double quotes only when you intentionally need a shell variable.
• In-place replacement is not undoable by replace. Make a backup before the command and keep it until a downstream validation has passed.
• A file called replace in the current directory is not used by command -v unless the current directory is in PATH. Do not run an unverified binary by habit.