12.7.1 Dumping Binary Logs

This section describes util.dumpBinlogs. This utility dumps binary logs generated since a specific point in time to the given local or remote directory. The starting point can be automatically determined from a previous dump, either by reusing the same output directory or by using the since option, or as a explicitly specified binlog file and position in the startFrom option.

The utility's syntax is:

        util.dumpBinlogs(outputUrl[, options])

outputUrl: A local file path or cloud storage. If the location specified exists and contains a dump created by this utility, the snapshot information in that dump is used as the starting point for the binary log dump.

See Options.

Requirements and Restrictions

The source instance must have binary logging enabled.
gtid_mode must be set to a value other than OFF or OFF_PERMISSIVE.
If the source instance was started with either --binlog-do-db or --binlog-ignore-db, a note shall be printed.

If another dump is used as the starting point for the binary log dump, an exception is thrown if any of the following are true:

The dump is incomplete.
The dump was created for an instance different from the current source instance and either are not part of the same InnoDB cluster or the current source instance is not an ONLINE member of that InnoDB cluster.
The dump's snapshot information is newer than the current source instance.
The first binlog file to be dumped does not exist or gtid_purged contains transactions that would be dumped.
The dump was created for an instance with different major.minor version than the current source instance.

Options

since: (string) path or URL to a local or remote directory containing a dump created by util.dumpInstance() or util.dumpBinlogs(). The dump must be complete, created by MySQL Shell 9.2.0 or higher, and consistent. If ocimds:true, or any of the compatibility options were used, an exception is thrown.
Note
This option cannot be used with startFrom.
startFrom: (string) the position of the binary log file to start dumping from. This value uses the format binary-log-file[:binary-log-file-position]. Where binary-log-file is the name of the binary log and binary-log-file-position is an unsigned integer specifying a position in that file.
Note
This option cannot be used with since.
ignoreDdlChanges: (boolean) prints a warning instead of an exception if ocimds:true, or any of the compatibility options were used in the dump.
Default value is false.
threads: (int) the number of additional threads to use when dumping the binary logs.
Default value is 4.
dryRun:(boolean) Prints information about what would be dumped, but does not dump anything.
Default value is false.
compression: "string;level=n" The compression type and level of compression to use when creating the dump files. The following compression options are available:
- none: No compression is applied.
- gzip: Uses the gzip compression library. Compression level can be set from 0 to 9. Default compression level is 1.
- zstd: Default. Uses the zstd compression library. Compression level can be set from 1 to 22. Default compression level is 1.
showProgress: Display (true) or hide (false) progress information for the dump. The default is true if stdout is a terminal (tty), such as when MySQL Shell is in interactive mode, and false otherwise.

Options for HeatWave Service and Oracle Cloud Infrastructure

osBucketName: "string"

The name of the Oracle Cloud Infrastructure Object Storage bucket to which the dump is to be written. By default, the [DEFAULT] profile in the Oracle Cloud Infrastructure CLI configuration file located at ~/.oci/config is used to establish a connection to the bucket. You can substitute an alternative profile to be used for the connection with the ociConfigFile and ociProfile options. For instructions to set up a CLI configuration file, see SDK and CLI Configuration File.

osNamespace: "string"

The Oracle Cloud Infrastructure namespace where the Object Storage bucket named by osBucketName is located. The namespace for an Object Storage bucket is displayed in the Bucket Information tab of the bucket details page in the Oracle Cloud Infrastructure console, or can be obtained using the Oracle Cloud Infrastructure command line interface.

ociConfigFile: "string"

An Oracle Cloud Infrastructure CLI configuration file that contains the profile to use for the connection, instead of the one in the default location ~/.oci/config.

ociProfile: "string"

The profile name of the Oracle Cloud Infrastructure profile to use for the connection, instead of the [DEFAULT] profile in the Oracle Cloud Infrastructure CLI configuration file used for the connection.

ociAuth: "string"

The authentication method to use when connecting to Oracle Cloud Infrastructure. This option requires osBucketName is configured with a valid value.

The following options are available:

api_key: OCI connections use the OCI configuration file. See Section 4.7.1, “Oracle Cloud Infrastructure Object Storage”.
If osBucketName is defined with a valid value, but ociAuth is not defined, api_key is the default value used.
instance_principal: OCI connections use instance principal authentication. See Instance Principal Authentication.
This option can not be used if ociConfigFile or ociProfile are defined.
resource_principal: OCI connections use resource principal authentication. See Resource Principal Authentication.
This option can not be used if ociConfigFile or ociProfile are defined.
security_token: OCI connections use a temporary, generated session token. See Session Token-Based Authentication.

Options for S3-compatible Services

MySQL Shell supports dumping MySQL data to S3-compatible buckets, such as Amazon Web Services (AWS) S3.

Note

MySQL Shell supports AWS S3 configuration in command line options, environment variables, and configuration files. Command line options override environment variables, configuration files, and default options.

For information on configuration requirements, see Section 4.7, “Cloud Service Configuration”.

s3BucketName: "string"

The name of the S3 bucket to which the dump is to be written. By default, the default profile of the config and credentials files located at ~/.aws/ are used to establish a connection to the S3 bucket. You can substitute alternative configurations and credentials for the connection with the s3ConfigFile and s3CredentialsFile options. For instructions on installing and configuring the AWS CLI, see Getting started with the AWS CLI.

s3CredentialsFile:"string"

A credentials file that contains the user's credentials to use for the connection, instead of the one in the default location, ~/.aws/credentials. Typically, the credentials file contains the aws_access_key_id and aws_secret_access_key to use for the connection.

s3ConfigFile: "string"

A configuration file that contains the profile to use for the connection, instead of the one in the default location, such as ~/.aws/config. Typically, the config file contains the region and output type to use for the connection.

s3Profile: "string"

The profile name of the s3 CLI profile to use for the connection, instead of the default profile.

s3Region: "string"

The name of the region to use for the connection.

s3EndpointOverride: "string"

The URL of the endpoint to use instead of the default.

When connecting to the Oracle Cloud Infrastructure S3 compatibility API, the endpoint takes the following format: https://namespace.compat.objectstorage.region.oraclecloud.com. Replace namespace with the Object Storage namespace and region with your region identifier. For example, the region identifier for the US East (Ashburn) region is us-ashburn-1.

For a namespace named axaxnpcrorw5 in the US East (Ashburn) region:

https://axaxnpcrorw5.compat.objectstorage.us-ashburn-1.oraclecloud.com.

Options for Microsoft Azure Blob Storage

MySQL Shell supports dumping to Microsoft Azure Blob Storage.

Note

MySQL Shell supports Microsoft Azure Blob Storage configuration in command line options, environment variables, and configuration files. Command line options override environment variables, and configuration files.

For information on configuration requirements and the order of precedence of the configuration types, see Section 4.7, “Cloud Service Configuration”.

azureContainerName: "string"

Mandatory. The name of the Azure container to which the dump is to be written. The container must exist.

azureConfigFile: "string"

Optional. A configuration file that contains the storage connection parameters, instead of the one in the default location, such as ~/.azure/config. If this is not defined, the default configuration file is used.

azureContainerName must be defined, and not be empty.

azureStorageAccount: "string"

Optional. The name of the Azure storage account to use for the operation.

azureStorageSasToken: "string"

Optional. Azure Shared Access Signature (SAS) token to be used for the authentication of the operation, instead of a key.