Skip to main content

Sync

Warrant Sync is a service designed to cut down on the tight integration required between Warrant and customer applications by automatically creating and updating warrants based on changes in the underlying application database(s). Sync is powered by the Sync Agent, a small daemon that runs alongside an application database, listens to the changelog, and automatically creates, updates, and deletes warrants based on changes in the underlying data.

Sync is designed to handle many of the common Warrant integration points (creating and managing users, tenants, etc.) and removes the need for application-level API integration. For example, you can configure Sync to listen to changes to your user and tenant data and automatically create/update/delete the appropriate warrants. This removes the need to call SDK methods like createUser(), createTenant() etc. in your application code.

Sync Agent

The Sync Agent is an application that runs on your host, and sends database change events to Warrant to allow us to modify warrants on your behalf. The Sync Agent can be run via Docker or directly on Kubernetes. It currently supports MySQL application databases. We'll be adding support for more databases soon, but if there's a specific one that you'd like us to add, drop us a note.

Agent security

The Sync Agent is designed to operate with basic, read-only permissions on the application database and will never change any underlying data. In addition, all database change events are sent to Warrant over HTTPS and authenticated/siloed by your account API key.

Object Types Configuration

In order to enable Warrant Sync to process your application’s database events, additional configuration is required in the object type definition to map your database relations. The source object is used by Warrant Sync to understand your database table relations and how they map to your object types within Warrant.

{
“type”: “user”,
“source”: {
"dbType": “mysql”,
"dbName": "myStore",
“table”: “users”,
“primaryKey”: [“id”],
“foreignKeys”: [
{
“type”: “tenant”
“column”: “tenantId”,
“relation”: “member”,
“subject”: “self”
}
]
}
}

In this example above, we have a user object type with a source object defined to enable Warrant Sync. Within the source object, we configure five main properties: dbType, dbName, table, primaryKey, and foreignKeys:

  • dbType - used to specify your database technology (currently supports 'mysql')
  • dbName - the name of your application's database.
  • table - the name of the table in your database that should be linked to this object type.
  • primaryKey - an array of all table columns that make up the table's primary key. Currently only one column is supported.
  • foreignKeys - an array of foreign key objects that define all of your table's foreign key relationships. The foreign key object itself is made up of four properties: type, column, relation, and subject.
    • type - specifies the object type of the child table that the foreign key references.
    • column - the name of the column where the foreign key value is stored.
    • relation - the type of relation between the parent and child object types/tables.
    • subject - the object type that should be the subject of the warrants created by Warrant Sync. This should either be self referring to the object type where this is being defined or the object type of the foreign key.

Warrants generally follow the general format: [subject] has [relation] on [object].

In the example above, the following is specified: A users table in a MySQL database with a primary key made up of the id column. It has one foreign key defined by tenantId which is associated to the tenant object type.

With a member relation and subject of self referring to user, the following warrant would be created if a new user id 58 was created with a tenantId of 7: user 58 is a member of tenant 7.

If we instead had a parent relation and subject of tenant, the following warrant would be created instead: tenant 7 is a parent of user 58.

This object type mapping allows Warrant Sync to create the appropriate warrants for you even when records are updated or deleted. If a foreign key value is updated for an existing record, the existing warrant would be updated to reflect the new value. If the record is deleted, then all warrants involving the affected record would be deleted as well.

Error Handling

Currently, events that fail to be processed are skipped. We'll soon be adding support for event replay-ability so events that fail to be processed will get replayed correctly.

Check out the Sync quickstart guide to get started with Sync.