Skip to main content

Setting up Sync

Warrant Sync is a service that automatically manages warrants for your application by mapping its database tables to object types in Warrant. This automatic syncing is done by the Sync Agent, a lightweight service that captures changes to your data and sends them to Warrant. Learn more about Warrant Sync here.

This guide will walk you through the steps to get Warrant Sync running with a Sync Agent.

Configure your Database

Before setting up a Sync Agent to capture changes to your data, you must configure your database to track these changes. We also recommend creating a new database user with only the privileges necessary to capture changes to your data. This user will be used by the Sync Agent. Currently only MySQL is supported, with support for more databases coming soon. If you have a database you'd like us to support, drop us a note.

1. Start by creating a MySQL user

CREATE USER 'user'@'dbhostname' IDENTIFIED WITH mysql_native_password BY 'password';

2. Grant the user the required permissions


The LOCK TABLES permission is also required if you have a hosted database such as Amazon RDS or Amazon Aurora

3. Finalize the user's permissions


4. Enable binary logging and GTIDs in the database by adding the following to your MySQL configuration file

log_bin                  = ON
binlog_format = ROW
binlog_row_image = FULL
expire_logs_days = 10
gtid_mode = ON
enforce_gtid_consistency = ON

You may have to restart MySQL for the changes to take effect.

5. Confirm the changes by checking your configuration


Setup the Sync Agent

The Sync Agent can currently be deployed on Docker or Kubernetes, with support for more platforms coming soon. If there's a platform you'd like us to support, drop us a note.

1. Pull Docker image

docker pull warrantdev/sync-agent

2. Create a file to configure your properties, i.e., and add the following properties with your own values

  • The list of tables in DATABASE_WATCHED_TABLES should be comma separated in the format db_name.table_name, i.e. my_db.users,my_db.tenants.

  • Use your local timezone for DATABASE_CONNECTION_TIMEZONE. For example, common timezones in the continental U.S. include America/Los_Angeles, America/New_York, America/Chicago, and America/Denver. You can also check this complete list of timezones.

  • If running on MacOS, use host.docker.internal as the value for DATABASE_HOSTNAME.

For more information on the properties, take a look at our reference.

3. Start the docker container

From the directory where you created, start the docker container with the following command, using the --env-file flag to pass in the properties file:

docker run --name warrant-sync-agent --env-file warrantdev/sync-agent

Local Testing

To run the agent image locally, set DATABASE_HOSTNAME in your properties file to host.docker.internal.

If you are running the agent on your local machine, include the --network host flag:

docker run --name warrant-sync-agent --env-file --network host warrantdev/sync-agent

If you are running the agent on Apple Silicon, include the --platform linux/amd64 flag:

docker run --name warrant-agent --env-file --platform linux/amd64 warrantdev/sync-agent

4. Confirm status in Warrant dashboard

After successfully starting a Sync Agent, you should see a new agent in your dashboard with the status indicating that Warrant is receiving events from the agent.

Configure your Object Types

Warrant Sync uses the events sent by a Sync Agent to automatically create, update, and delete warrants. In order to do this, Warrant Sync must understand how each of your object types relates to the data in your database. To specify this, you must add a source to each object type you want to sync via Warrant Sync. You can add a source to your object types via API or in the Dashboard.

Source Reference

dbTypeDatabase type (Ex: mysql)
dbNameName of the database where the table exists
tableName of the table to associate object type with
primaryKeyArray of comma-separated strings that make up the primary id of the table
foreignKeysArray of foreign key objects that describe the foreign key object relations for this table

Foreign Key Reference

typeThe object type that this foreign key points to
columnForeign key column name in the table
subjectSubject of the warrant that should be created between the two object types (This should be self or the name of the object type where this is defined)
relationThe relation between the two object types for the warrant to be created

Example Object Type Config

"type": "user",
"source": {
"dbType": "mysql",
"dbName": "ninecap",
"table": "user",
"primaryKey": ["id"],
"foreignKeys": [
"type": "tenant",
"column": "accountId",
"subject": "self"
"relation": "member",
"relations": {
"parent": {}

This object type defines a source for the user object type. The source is a table named user in a mysql database named ninecap. The primary key for the user table is the id column. The user table also has a foreign key column accountId that references the tenant object type. The subject of a foreignKey specifies what the subject should be for warrants created by Warrant Sync for this object type. We specify the subject as self indicating that the tenant should be the subject of the created warrant with a member relation.

If we had a user id 7 created with an accountId of 10, then this is the following warrant that would be created by the Sync Service:

Object TypeObject IdRelationUser

Properties Reference

API_KEYYesWarrant API key used to link your agent to your Warrant account
AGENT_NAMEYesSync agent name used to identify your agent
DATABASE_HOSTNAMEYesIP address or host name of the MySQL database server
DATABASE_DBNAMEYesName of the MySQL database
DATABASE_PORTYesInteger port number of the MySQL database server
DATABASE_USERYesName of the MySQL user to use when connecting to the MySQL database server
DATABASE_PASSWORDYesPassword to use when connecting to the MySQL database server
DATABASE_CONNECTION_TIMEZONEYesTimezone used for the timestamps of database events.
DATABASE_WATCHED_TABLESYesAn optional, comma-separated list of regular expressions that match fully-qualified table identifiers of tables whose changes you want to capture. The connector does not capture changes in any table not included in DATABASE_WATCHED_TABLES. Each identifier is of the form databaseName.tableName. By default, the connector captures changes in every non-system table in each database whose changes are being captured.