MySQL Setup Guide

This guide covers the following deployments:

• MySQL (including AWS RDS)
• PlanetScale
• Self-hosted Vitess

Follow the step for your deployment, then continue to the Complete Setup in Matia section.

Deployment	Follow
MySQL / AWS RDS	Step 1
PlanetScale	Step 2
Self-hosted Vitess	Step 3

Prerequisites

• Matia connects from the following IPs: 23.21.86.124/32, 52.20.96.22/32 and 44.219.180.239/32. If your database restricts inbound traffic, allow these IPs. (For PlanetScale, see IP restrictions below.)

Step 1: MySQL

• MySQL version 8.0 or above

• (Optional) A dedicated MySQL database user with replication permissions. Creating a dedicated user is recommended for better permission control and auditing:

  CREATE USER <matia_user>@'%' IDENTIFIED WITH mysql_password BY 'password'

• Grant replication privileges to your database user. The user must also be granted SELECT privileges for all columns you wish to sync:

  GRANT SELECT, REPLICATION CLIENT, REPLICATION SLAVE ON *.* TO <matia_user>@'%';

• Make sure that your database is configured as follows:

  [mysqld] binlog-format=ROW log-bin=mysql-binlog server-id=123456789 expire-logs-days=7 log-slave-updates=1

  • Enables ROW format binary log replication, which is required to perform incremental updates.
  • Name the binary log (for example, mysql-binlog).
  • If your configuration already has a log-bin entry, you don't need to change it.
  • If your configuration already has a server-id entry, you don't need to change it. Otherwise, choose any number between 1 and 4294967295 as the server-id.
  • Set the log expiration to a minimum of one day. We recommend seven days.
  • Restart your MySQL server to effect these changes.

AWS RDS

• Grant read access to the mysql.rds_heartbeat2 system table:

  GRANT SELECT ON mysql.rds_heartbeat2 TO <matia_user>@'%';

• Grant read access to the mysql.rds_configuration system table:

  GRANT SELECT ON mysql.rds_configuration TO <matia_user>@'%';

• Grant execute permission on the mysql.rds_kill stored procedure:

  GRANT EXECUTE ON PROCEDURE mysql.rds_kill TO <matia_user>@'%';

• Set the binlog_format to ROW in your DB parameter group.
• Enable automatic backups for your DB instance.
• If you connected Matia to a read replica, check the value of the slave_parallel_workers parameter in your DB parameter group. If it's set to 0, the following changes are not required. Otherwise, update the DB parameter group with:
  • slave_preserve_commit_order = 1
  • slave_parallel_type = LOGICAL_CLOCK
  • binlog_order_commits = 1
• If you modified any of the settings above, reboot the instance to apply the changes.
• We recommend setting your binlog retention period to seven days (168 hours):

  CALL mysql.rds_set_configuration('binlog retention hours', 168);

Step 2: PlanetScale

Matia reads changes from PlanetScale through the Vitess VStream API. Everything is configured in the PlanetScale console.

You don't need to configure the binlog, run GRANT statements, or change any server settings. The MySQL steps above don't apply to PlanetScale.

Create a password

1. In the PlanetScale console, open your database and go to Settings > Passwords.
2. Click New password.
3. Enter a name (for example, matia).
4. Select the branch you want to sync. This is usually your production branch (for example, main).
5. Under Role, select Read-only. This covers both the initial sync and incremental changes.
6. Click Create password.
7. Copy the Host, Username, and Password. PlanetScale shows the password only once.

Find your keyspace

The keyspace has the same name as your PlanetScale database. If your database has more than one keyspace (for example, a sharded database), you can find them on the branch's overview page. Each Matia connector syncs one keyspace.

Connection values

Use these values in the Complete Setup in Matia section:

Field	Value
Hostname	Host from the password page (for example, aws.connect.psdb.cloud)
Port	3306
Username	Username from the password page
Password	Password from the password page
Server Type	Vitess
VStream RPC Port	443 (default)
Keyspace	Your PlanetScale database name

Step 3: Self-hosted Vitess

These settings apply only to Vitess you run yourself. PlanetScale manages them for you.

• Matia's IPs can reach both VTGate ports: the MySQL port and the gRPC port used for VStream (set by --grpc_port).
• A Vitess user with read access to the keyspace you want to sync.
• Partial row features are turned off:
  • Don't enable the noblob bit in the tablets' --vreplication-experimental-flags.
  • Don't set binlog_row_value_options=PARTIAL_JSON.
• Full row images are set on the underlying MySQL tablets: binlog_format=ROW and binlog_row_image=FULL (the Vitess defaults).

Complete Setup in Matia

1. Under Authentication Method, select:
   • Direct to connect directly to your database.
   • SSH to connect through an SSH tunnel on a server in your network. SSH is available for MySQL only. It isn't available yet for PlanetScale or Vitess.
2. Enter the Username and Password for your database user. For PlanetScale, use the values from the password page.
3. Enter the Hostname for your database.
4. Enter the Port for your database.
5. (Optional) If you are connecting through SSH, enter your SSH Hostname, Port, and Username. Make sure to add the Public Key we've generated for your organization to your server's authorized keys.
6. Under Server Type, select:
   • MySQL for MySQL connections. Then, optionally, enter the Database to replicate.
   • Vitess for PlanetScale and self-hosted Vitess. Then enter:
     • VStream RPC Port (Required): keep the default 443 for PlanetScale. For self-hosted Vitess, enter your VTGate gRPC port (set by --grpc_port).
     • Keyspace (Required): the keyspace to sync. For PlanetScale, this is your database name.

     Note: Each Vitess connection can have one keyspace only.

7. Enter a Name for the connector.
8. (Optional) Enter a Description for the connector.
9. Select the Owner of the connector.
10. (Optional) Verify that your database is successfully connected by clicking Test Connection.
11. Click Connect.