mysql.rds_set_external_master

Configures a MySQL DB instance to be a Read Replica of an instance of MySQL running external to Amazon RDS.

Syntax


CALL mysql.rds_set_external_master (
  host_name
  , host_port
  , replication_user_name
  , replication_user_password
  , mysql_binary_log_file_name
  , mysql_binary_log_file_location
  , ssl_encryption
);

Parameters

host_name: The host name or IP address of the MySQL instance running external to Amazon RDS to become the replication master.
host_port: The port used by the MySQL instance running external to Amazon RDS to be configured as the replication master. If your network configuration includes Secure Shell (SSH) port replication that converts the port number, specify the port number that is exposed by SSH.
replication_user_name: The ID of a user with REPLICATION CLIENT and REPLICATION SLAVE permissions on the MySQL instance running external to Amazon RDS. We recommend that you provide an account that is used solely for replication with the external instance.
replication_user_password: The password of the user ID specified in replication_user_name.
mysql_binary_log_file_name: The name of the binary log on the replication master that contains the replication information.
mysql_binary_log_file_location: The location in the mysql_binary_log_file_name binary log at which replication starts reading the replication information.
ssl_encryption: A value that specifies whether Secure Socket Layer (SSL) encryption is used on the replication connection. 1 specifies to use SSL encryption, 0 specifies to not use encryption. The default is 0.

Note

This parameter currently is only implemented for Amazon Aurora with MySQL compatibility. On MySQL DB instances, only the default is allowed.

Usage Notes

The mysql.rds_set_external_master procedure must be run by the master user. It must be run on the MySQL DB instance to be configured as the Read Replica of a MySQL instance running external to Amazon RDS.

Before you run mysql.rds_set_external_master, you must configure the instance of MySQL running external to Amazon RDS to be a replication master. To connect to the MySQL instance running external to Amazon RDS, you must specify replication_user_name and replication_user_password values that indicate a replication user that has REPLICATION CLIENT and REPLICATION SLAVE permissions on the external instance of MySQL.

To configure an external instance of MySQL as a replication master

Using the MySQL client of your choice, connect to the external instance of MySQL and create a user account to be used for replication. The following is an example.
```
CREATE USER 'repl_user'@'mydomain.com' IDENTIFIED BY 'password'
```
On the external instance of MySQL, grant REPLICATION CLIENT and REPLICATION SLAVE privileges to your replication user. The following example grants REPLICATION CLIENT and REPLICATION SLAVE privileges on all databases for the 'repl_user' user for your domain.
```
GRANT REPLICATION CLIENT, REPLICATION SLAVE ON *.* TO 'repl_user'@'mydomain.com' 
IDENTIFIED BY 'password'
```

For more information, see Replication with a MySQL or MariaDB Instance Running External to Amazon RDS.

To use encrypted replication, configure the master to use SSL connections. Also, import the certificate authority certificate, client certificate, and client key into the DB instance or DB cluster using the mysql.rds_import_binlog_ssl_material procedure.

Note

We recommend that you use Read Replicas to manage replication between two Amazon RDS DB instances when possible, and only use this and other replication-related stored procedures to enable more complex replication topologies between Amazon RDS DB instances. These stored procedures are primarily offered to enable replication with MySQL instances running external to Amazon RDS. For information about managing replication between Amazon RDS DB instances, see Working with Read Replicas of MariaDB, MySQL, and PostgreSQL DB Instances.

After calling mysql.rds_set_external_master to configure an Amazon RDS DB instance as a Read Replica, you can call mysql.rds_start_replication on the replica to start the replication process. You can call mysql.rds_reset_external_master to remove the Read Replica configuration.

When mysql.rds_set_external_master is called, Amazon RDS records the time, user, and an action of "set master" in the mysql.rds_history and mysql.rds_replication_status tables.

The mysql.rds_set_external_master procedure is available in these versions of Amazon RDS MySQL:

MySQL 5.5
MySQL 5.6
MySQL 5.7

Examples

When run on a MySQL DB instance, the following example configures the DB instance to be a Read Replica of an instance of MySQL running external to Amazon RDS.


call mysql.rds_set_external_master(
  'Externaldb.some.com',
  3306,
  'repl_user'@'mydomain.com',
  'password',
  'mysql-bin-changelog.0777',
  120,
  0);