mysqlbinlog Options

MariaDB starting with 10.4.6

From MariaDB 10.4.6, mariadb-binlog is a symlink to mysqlbinlog.

MariaDB starting with 10.5.2

From MariaDB 10.5.2, mariadb-binlog is the name of the tool, with mysqlbinlog a symlink .

mysqlbinlog is a utility included with MariaDB for processing binary log and relay log files.

Options

The following options are supported by mysqlbinlog. They can be specified on the command line or in option files:

Option default value Description Introduced
-?, --help Display a help statement.
--base64-output=name (>= MariaDB 10.6.1, MariaDB 10.5.11) auto Determine when the output statements should be base64-encoded BINLOG statements. Options (case-insensitive) include auto, unspec, never and decode-rows. never neither prints base64 encodings nor verbose event data, and will exit on error if a row-based event is found. This option is useful for binlogs that are entirely statement based. decode-rows decodes row events into commented SQL statements if the --verbose option is also given. It can enhance the debugging experience with large binary log files, as the raw data will be omitted. Unlike never, mysqlbinlog will not exit with an error if a row event is found. auto (synonymous with unspec) outputs base64 encoded entries for row-based and format description events; it should be used when ROW-format events are processed for re-executing on the MariaDB server. This behavior is presumed, such that auto is the default value when no option specification is provided. The other option values are intended only for debugging or testing purposes because they may produce output that does not include all events in executable form.
--base64-output[=name] (<= MariaDB 10.6.0, MariaDB 10.5.10) (No default Value) Determine when the output statements should be base64-encoded BINLOG statements. Options (case-insensitive) include auto, unspec, always (deprecated), never and decode-rows. never disables it and works only for binlogs without row-based events; decode-rows decodes row events into commented SQL statements if the --verbose option is also given; Unlike never, mysqlbinlog does not exit with an error if a row event is found auto or unspec, the default, prints base64 only when necessary (i.e., for row-based events and format description events), and is the only safe behavior if you intend to use the output of mysqlbinlog to re-execute binary log file contents. The other option values are intended only for debugging or testing purposes because they may produce output that does not include all events in executable form.; always prints base64 whenever possible, and is for debugging only and should not be used in a production system. If this option is not given, the default is auto; if it is given with no argument, always is used.
--binlog-row-event-max-size=val 4294967040 (4GB) The maximum size in bytes of a row-based binary log event. Should be a multiple of 256. Minimum 256, maximum 18446744073709547520.
--character-sets-dir=name (No default value) Directory where the character sets are.
-d, --database=name (No default value) Output entries from the binary log (local log only) that occur while name has been selected as the default database by USE. Only one database can be specified. The effects depend on whether the statement-based or row-based logging format is in use. For statement-based logging, the server will only log statements where the default database is name. The default database is set with the USE statement. For row-based logging, the server will log any updates to any tables in the named database, irrespective of the current database. Ignored in --raw mode.
-# [options], --debug[=options] d:t:o,/tmp/mysqlbinlog.trace In a debug build, write a debugging log. A typical debug options string is d:t:o,file_name.
--debug-check FALSE Print some debug info at exit..
--debug-info FALSE Print some debug info and memory and CPU info at exit.
--default-auth=name Default authentication client-side plugin to use.
--defaults-extra-file=name Read the file name, which can be the full path, or the path relative to the current directory, after the global files are read.
--defaults-file=name Only read default options from the given file
name
, which can be the full path, or the path relative to the current directory.
--defaults-group-suffix=str Also read groups with a suffix of str. For example, since mysqlbinlog normally reads the [client] and [mysqlbinlog] groups, --defaults-group-suffix=x would cause it to also read the groups [mysqlbinlog_x] and [client_x].
-D, --disable-log-bin FALSE Disable binary log. This is useful, if you enabled --to-last-log and are sending the output to the same MariaDB server. This way you could avoid an endless loop. You would also like to use it when restoring after a crash to avoid duplication of the statements you already have. NOTE: you will need a SUPER privilege to use this option.
-F, --force-if-open TRUE Force if binlog was not closed properly. Defaults to ON; use --skip-force-if-open to disable.
-B, --flashback FALSE Support flashback mode. MariaDB 10.2.4
-f, --force-read FALSE If mysqlbinlog reads a binary log event that it does not recognize, it prints a warning, ignores the event, and continues. Without this option, mysqlbinlog stops if it reads such an event.
-H, --hexdump FALSE Augment output with hexadecimal and ASCII event dump.
-h, --host=name (No default value) Get the binlog from the MariaDB server on the given host.
-l path, --local-load=path (No default value) Prepare local temporary files for LOAD DATA INFILE in the specified directory. The temporary files are not automatically removed.
--no-defaults Don't read default options from any option file
-o value, --offset=value 0 Skip the first value entries in the log.
--open_files_limit=# 64 Reserve file descriptors for usage by mysqlbinlog.
-p[passwd], --password[=passwd] (No default value) Password to connect to the remote server. The password can be omitted allow it be entered from the prompt, or an option file can be used to avoid the security risk of passing a password on the commandline.
--plugin-dir=dir_name, Directory for client-side plugins.
-P num, --port=num 0 Port number to use for connection or 0 for default to, in order of preference, my.cnf, $MYSQL_TCP_PORT, /etc/services, built-in default (3306).
--position=# 4 Removed in MariaDB 5.5. Use --start-position instead.
--print-defaults Print the program argument list from all option files and exit.
print-table-metadata Print metadata stored in Table_map_log_event. MariaDB 10.5.0
--protocol=name (No default value) The protocol of the connection (tcp,socket,pipe,memory).
--raw Requires -R. Output raw binlog data instead of SQL statements. Output files named after server logs. MariaDB 10.2.0
-R, --read-from-remote-server FALSE Read binary logs from a remote MariaDB server rather than reading a local log file. Any connection parameter options are ignored unless this option is given as well. These options are --host, --password, --port, --protocol, --socket, and --user. This option requires that the remote server be running. It works only for binary log files on the remote server, not relay log files.
-r name, --result-file=name (No default value) Direct output to a given file. With --raw this is a prefix for the file names.
--rewrite-db=name (No default value) Updates to a database with a different name than the original. Example: rewrite-db='from->to'

For events that are binlogged as statements, rewriting the database constitutes changing a statement's default database from db1 to db2.

There is no statement analysis or rewrite of any kind, that is, if one specifies "db1.tbl" in the statement explicitly, that occurrence won't be changed to "db2.tbl".

Row-based events are rewritten correctly to use the new database name.

Filtering (e.g. with --database=name ) happens after the database rewrites have been performed.

If you use this option on the command line and ">" has a special meaning to your command interpreter, quote the value (e.g. --rewrite-db="oldname->newname").
--server-id=idnum 0 Extract only binlog entries created by the server having the given id.
--set-charset=character_set (No default value) Add 'SET NAMES character_set' to the output to specify the character set to be used for processing log files.
--shared-memory-base-name=name MYSQL Shared-memory name to use for Windows connections using shared memory to a local server (started with the --shared-memory option). Case-sensitive.
-s, --short-form FALSE Just show regular queries: no extra info and no row-based events. This is for testing only, and should not be used in production systems. If you want to suppress base64-output, consider using --base64-output=never instead.
--skip-annotate-rows-events Skip all Annotate_rows events in the mysqlbinlog output (by default, mysqlbinlog prints Annotate_rows events, if the binary log does contain them).
-S, --socket=name (No default value) For connections to localhost, the Unix socket file to use, or, on Windows, the name of the named pipe to use.
--ssl FALSE Enables TLS. TLS is also enabled even without setting this option when certain other TLS options are set. Starting with MariaDB 10.2, the --ssl option will not enable verifying the server certificate by default. In order to verify the server certificate, the user must specify the --ssl-verify-server-cert option.
--ssl-ca=name Defines a path to a PEM file that should contain one or more X509 certificates for trusted Certificate Authorities (CAs) to use for TLS. This option requires that you use the absolute path, not a relative path. See Secure Connections Overview: Certificate Authorities (CAs) for more information. This option implies the --ssl option.
--ssl-capath=name Defines a path to a directory that contains one or more PEM files that should each contain one X509 certificate for a trusted Certificate Authority (CA) to use for TLS. This option requires that you use the absolute path, not a relative path. The directory specified by this option needs to be run through the openssl rehash command. See Secure Connections Overview: Certificate Authorities (CAs) for more information. This option is only supported if the client was built with OpenSSL or yaSSL. If the client was built with GnuTLS or Schannel, then this option is not supported. See TLS and Cryptography Libraries Used by MariaDB for more information about which libraries are used on which platforms. This option implies the --ssl option.
--ssl-cert=name Defines a path to the X509 certificate file to use for TLS. This option requires that you use the absolute path, not a relative path. This option implies the --ssl option.
--ssl-cipher=name List of permitted ciphers or cipher suites to use for TLS. This option implies the --ssl option.
--ssl-crl=name Defines a path to a PEM file that should contain one or more revoked X509 certificates to use for TLS. This option requires that you use the absolute path, not a relative path. See Secure Connections Overview: Certificate Revocation Lists (CRLs) for more information. This option is only supported if the client was built with OpenSSL or Schannel. If the client was built with yaSSL or GnuTLS, then this option is not supported. See TLS and Cryptography Libraries Used by MariaDB for more information about which libraries are used on which platforms.
--ssl-crlpath=name Defines a path to a directory that contains one or more PEM files that should each contain one revoked X509 certificate to use for TLS. This option requires that you use the absolute path, not a relative path. The directory specified by this option needs to be run through the openssl rehash command. See Secure Connections Overview: Certificate Revocation Lists (CRLs) for more information. This option is only supported if the client was built with OpenSSL. If the client was built with yaSSL, GnuTLS, or Schannel, then this option is not supported. See TLS and Cryptography Libraries Used by MariaDB for more information about which libraries are used on which platforms.
--ssl-key=name Defines a path to a private key file to use for TLS. This option requires that you use the absolute path, not a relative path. This option implies the --ssl option.
--ssl-verify-server-cert FALSE Enables server certificate verification. This option is disabled by default.
--start-datetime=datetime (No default value) Start reading the binlog at first event having a datetime equal to or later than the argument; the argument must be a date and time in the local time zone, in any format accepted by the MariaDB server for DATETIME and TIMESTAMP types, for example: 2014-12-25 11:25:56 (you should probably use quotes for your shell to set it properly). This option is useful for point-in-time recovery.
-j pos, --start-position=pos 4 Start reading the binlog at position pos. Applies to the first binlog passed on the command line.
--stop-datetime=name (No default value) Stop reading the binlog at first event having a datetime equal or posterior to the argument; the argument must be a date and time in the local time zone, in any format accepted by the MariaDB server for DATETIME and TIMESTAMP types, for example: 2014-12-25 11:25:56 (you should probably use quotes for your shell to set it properly). Ignored in --raw mode.
--stop-never Wait for more data from the server instead of stopping at the end of the last log. Implies --to-last-log. MariaDB 10.2.0
--stop-never-slave-server-id The slave server_id used for --read-from-remote-server --stop-never. MariaDB 10.2.0
--stop-position=pos 18446744073709551615 Stop reading the binlog at position pos. Applies to the last binlog passed on the command line. Ignored in --raw mode.
-T, --table List entries for just this table (local log only). MariaDB 10.2.4
--tls-version=name TLSv1.1,TLSv1.2,TLSv1.3 This option accepts a comma-separated list of TLS protocol versions. A TLS protocol version will only be enabled if it is present in this list. All other TLS protocol versions will not be permitted. See Secure Connections Overview: TLS Protocol Versions for more information. MariaDB 10.4.6
-t, --to-last-log FALSE Requires -R or --read-from-remote-server . Will not stop at the end of the requested binlog but rather continue printing until the end of the last binlog of the MariaDB server. If you send the output to the same MariaDB server, that may lead to an endless loop.
-u, --user=username (No default value) Connect to the remote server as username.
-v, --verbose Reconstruct SQL statements out of row events. -v -v adds comments on column data types
-V, --version Print version and exit.
--verify-binlog-checksum Verify binlog event checksums when reading a binlog file.

Option Files

In addition to reading options from the command-line, mysqlbinlog can also read options from option files. If an unknown option is provided to mysqlbinlog in an option file, then it is ignored.

The following options relate to how MariaDB command-line tools handles option files. They must be given as the first argument on the command-line:

Option Description
--print-defaults Print the program argument list and exit.
--no-defaults Don't read default options from any option file.
--defaults-file=# Only read default options from the given file #.
--defaults-extra-file=# Read this file after the global files are read.
--defaults-group-suffix=# In addition to the default option groups, also read option groups with this suffix.

In MariaDB 10.2 and later, mysqlbinlog is linked with MariaDB Connector/C. However, MariaDB Connector/C does not yet handle the parsing of option files for this client. That is still performed by the server option file parsing code. See MDEV-19035 for more information.

Option Groups

mysqlbinlog reads options from the following option groups from option files:

Group Description
[mysqlbinlog] Options read by mysqlbinlog, which includes both MariaDB Server and MySQL Server.
[mariadb-binlog] Options read by mysqlbinlog. Available starting with MariaDB 10.4.6.
[client] Options read by all MariaDB and MySQL client programs, which includes both MariaDB and MySQL clients. For example, mysqldump.
[client-server] Options read by all MariaDB client programs and the MariaDB Server. This is useful for options like socket and port, which is common between the server and the clients.
[client-mariadb] Options read by all MariaDB client programs.

In MariaDB 10.2 and later, mysqlbinlog is linked with MariaDB Connector/C. However, MariaDB Connector/C does not yet handle the parsing of option files for this client. That is still performed by the server option file parsing code. See MDEV-19035 for more information.

See Also

Content reproduced on this site is the property of its respective owners, and this content is not reviewed in advance by MariaDB. The views, information and opinions expressed by this content do not necessarily represent those of MariaDB or any other party.

© 2021 MariaDB
Licensed under the Creative Commons Attribution 3.0 Unported License and the GNU Free Documentation License.
https://mariadb.com/kb/en/mysqlbinlog-options/