dbtrail Documentation

A stream is a persistent process that connects to your MySQL server as a replication client, reads binary log events in real-time, and indexes row-level changes (INSERT, UPDATE, DELETE) into the change index.

How streams work

Each stream runs as a systemd service (bintrail-stream-{server_id}) on the agent EC2 instance. The stream process and all its parameters are features of the open-source bintrail CLI — see the bintrail repo for advanced options beyond what the SaaS API exposes. The systemd service provides:

Auto-restart on crash — Restart=on-failure in the systemd unit
Log management — via journald (journalctl -u bintrail-stream-{id})
Process lifecycle — start, stop, status via systemctl

Checkpoint and resume

The stream stores its position in the binlog via a stream_state table — recording the current binlog file and position (or GTID set). On restart, it resumes from the saved checkpoint automatically.

Reset behavior

The --reset flag (which clears the checkpoint and forces re-reading from a start position) is not exposed through the SaaS API. Resetting stream state is a manual operation performed directly on the server.

Stream parameters

Parameter	Default	Description
`schemas`	all	Comma-separated list of schemas to monitor
`tables`	all	Comma-separated list of tables (e.g., `mydb.orders`)
`batch_size`	`1000`	Number of events to process per batch
`checkpoint_interval`	`10`	Seconds between checkpoint writes
`ssl_mode`	`preferred`	SSL mode for the MySQL connection

SSL options

Parameter	Description
`ssl_mode`	`disabled`, `preferred`, `required`, `verify-ca`, `verify-full`
`ssl_ca`	Path to CA certificate
`ssl_cert`	Path to client certificate
`ssl_key`	Path to client private key

Monitoring stream status

Check the status of a stream via the dashboard or the API. See the Status API reference for endpoint details.

Filtering

You can scope streams to specific schemas and tables. This is useful when you only need to track changes in certain databases or tables, reducing index size and agent resource usage.

{
  "schemas": "production,staging",
  "tables": "production.orders,production.users"
}

If no filters are specified, the stream monitors all schemas and tables.

Stream Configuration