Stream Configuration
Configure persistent binlog reading and change indexing
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
A stream is the bintrail stream command. It requires three things: a DSN for the change index database, a DSN for the source MySQL server, and a unique replication server ID:
bintrail stream \
--index-dsn "bintrail:password@tcp(index-mysql:3306)/bintrail_index" \
--source-dsn "bintrail:password@tcp(source-mysql:3306)/" \
--server-id 1234In production, run it under systemd so it survives crashes and host reboots. The deployment guide ships a ready-made bintrail-stream.service unit with Restart=always, journald logging (journalctl -u bintrail-stream -f), and credentials loaded from an EnvironmentFile. For the full streaming reference — start positions, gap handling, Prometheus metrics — see docs/streaming.md.
dbtrail Cloud
In dbtrail Cloud, the control plane manages stream lifecycle for you: each registered server gets its own supervised systemd unit (bintrail-stream-{server_id}) on the agent host, started and stopped from the dashboard or API. See Server Management.
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. The checkpoint takes priority over --start-file/--start-gtid, so re-running the same command resumes rather than re-reads. On a first run with no checkpoint and no start flags, the stream auto-discovers the source's current binlog position.
To clear the checkpoint and force re-reading from an explicit start position, pass --reset:
bintrail stream --reset --start-file mysql-bin.000042 ...dbtrail Cloud
--reset is not exposed through the Cloud API. Resetting stream state on a Cloud-managed server is a manual operation performed directly on the host.
Stream parameters
| Flag | 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 | 10 | Seconds between checkpoint writes |
--ssl-mode | preferred | TLS mode for the source MySQL connection |
The Cloud API accepts the same parameters as snake_case JSON fields: schemas, tables, batch_size, checkpoint_interval, ssl_mode.
SSL options
| Flag | Description |
|---|---|
--ssl-mode | disabled, preferred, required, verify-ca, verify-identity |
--ssl-ca | Path to CA certificate (system CAs are used when omitted) |
--ssl-cert | Path to client certificate for mutual TLS |
--ssl-key | Path to client private key for mutual TLS |
--ssl-cert and --ssl-key must be specified together. In the Cloud API these are the ssl_ca, ssl_cert, and ssl_key fields.
Monitoring stream status
Run bintrail status against the index DSN — the report includes a Stream section read from stream_state, alongside indexed files, partitions, and coverage. For continuous monitoring, the web console (bintrail-console, default 127.0.0.1:8090) shows live stream state, and --metrics-addr exposes a Prometheus endpoint.
dbtrail Cloud
Cloud users can check stream status from the dashboard or the Status API — no direct index access needed.
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 resource usage:
bintrail stream ... \
--schemas "production,staging" \
--tables "production.orders,production.users"If no filters are specified, the stream monitors all schemas and tables. Through the Cloud API, pass the same filters as the schemas and tables fields of the stream request body.