diff --git a/Documentation/Filters/BinlogFilter.md b/Documentation/Filters/BinlogFilter.md
index 5cad9f057..f2f553f90 100644
--- a/Documentation/Filters/BinlogFilter.md
+++ b/Documentation/Filters/BinlogFilter.md
@@ -37,32 +37,27 @@ in the statements. If any of the tables matches the *match* pattern, the event
 is replicated. If any of the tables matches the *exclude* pattern, the event is
 not replicated.
 
-### `rewrite_src`
+### `rewrite_src` and `rewrite_dest`
 
-The old database name to a rewritten statement. When database name rewriting is
-enabled, all occurrences of the old database name (`rewrite_src`) are replaced
-with the new replacement database name (`rewrite_dest`). Both `rewrite_src` and
-`rewrite_dest` must be defined if database rewriting is to be enabled.
+These two parameters control the statement rewriting of the binlogfilter. The
+`rewrite_src` parameter is a PCRE2 regular expression that is matched against
+the default database and the SQL of statement based replication events (query
+events). `rewrite_dest` is the replacement string which supports the normal
+PCRE2 backreferences (e.g the first capture group is `$1`, the second is `$2`,
+etc.).
 
-The name replacement is done with simple string replacement. This means that the
-database name (`rewrite_src`) **must not** appear as a table name, a field name
-or any other identifier, as a part of a constant value and must not conflict
-with SQL keywords. If the name does appear as a non-database identifier,
-replication will either break or behave in an undefined manner.
+Both `rewrite_src` and `rewrite_dest` must be defined to enable statement rewriting.
 
-We highly recommend using
+When statement rewriting is enabled
 [GTID-based replication](https://mariadb.com/kb/en/library/gtid/#setting-up-a-new-slave-server-with-global-transaction-id)
-when using statement rewriting. If `rewrite_dest` is longer than `rewrite_src`,
-the replication must use GTID coordinates. Otherwise, the replication can break
-down when a slave server is disconnected. The filter will disallow replication
-for all slaves that attempt to replicate with traditional file-and-position
-based replication when the new database name is longer than the old name.
+must be used. The filter will disallow replication for all slaves that attempt
+to replicate with traditional file-and-position based replication.
 
-### `rewrite_dest`
-
-The new database name of a rewritten statement.  Both `rewrite_src` and
-`rewrite_dest` must be defined if database rewriting is to be enabled. See
-[`rewrite_src`](#rewrite_src) for details on how this feature works.
+The replacement is done both on the default database as well as the SQL
+statement in the query event. This means that great care must be taken when
+defining the rewriting rules. To prevent accidental modification of the SQL into
+a form that is no longer valid, use database and table names that never occur in
+the inserted data and is never used as a constant value.
 
 ## Example Configuration