Server Configuration

A server represents a MySQL instance that dbtrail monitors. Registering a server tells dbtrail where to connect, how to authenticate, and which connection method to use. This page covers everything from initial setup to ongoing management.

Prerequisites

Before registering a server, make sure your MySQL instance is ready for dbtrail:

1. Binary logging is enabled and uses row format:

   SHOW VARIABLES LIKE 'log_bin';        -- Must be ON
   SHOW VARIABLES LIKE 'binlog_format';  -- Must be ROW
   SHOW VARIABLES LIKE 'binlog_row_image';  -- Must be FULL

2. Every table you want to track uses InnoDB and has a primary key:

   -- Find non-InnoDB tables
   SELECT TABLE_SCHEMA, TABLE_NAME, ENGINE
   FROM information_schema.TABLES
   WHERE TABLE_SCHEMA NOT IN ('mysql','information_schema','performance_schema','sys')
     AND ENGINE != 'InnoDB';
   
   -- Find tables without a primary key
   SELECT t.TABLE_SCHEMA, t.TABLE_NAME
   FROM information_schema.TABLES t
   LEFT JOIN information_schema.TABLE_CONSTRAINTS c
     ON t.TABLE_SCHEMA = c.TABLE_SCHEMA
     AND t.TABLE_NAME = c.TABLE_NAME
     AND c.CONSTRAINT_TYPE = 'PRIMARY KEY'
   WHERE t.TABLE_SCHEMA NOT IN ('mysql','information_schema','performance_schema','sys')
     AND t.TABLE_TYPE = 'BASE TABLE'
     AND c.CONSTRAINT_NAME IS NULL;

   Both queries should return empty results. If not, convert tables to InnoDB (ALTER TABLE t ENGINE=InnoDB) and add primary keys (ALTER TABLE t ADD PRIMARY KEY (column)) before proceeding. Caution: ALTER TABLE on large tables can lock the table and take significant time — use pt-online-schema-change or gh-ost for production databases.

3. A dedicated MySQL user exists with the required privileges:

   CREATE USER 'bintrail'@'%' IDENTIFIED BY 'strong_password_here';
   GRANT REPLICATION SLAVE, REPLICATION CLIENT ON *.* TO 'bintrail'@'%';
   GRANT SELECT ON *.* TO 'bintrail'@'%';  -- needed for schema snapshots
   FLUSH PRIVILEGES;

Connection methods

dbtrail supports three connection methods:

SSH tunnel (jumphost)

This is the recommended method. dbtrail connects to your database through an SSH bastion host, so the database never needs to be exposed to the internet.

SSH tunnel prerequisites

In addition to the MySQL prerequisites above, you need:

• Jumphost hostname or IP — the public address of your SSH bastion
• SSH user — a user on the jumphost that can forward connections (e.g., tunnel)
• SSH private key — the private key for the SSH user (PEM or PPK format)
• Network path — the jumphost must be able to reach the MySQL host on port 3306

Step 1: Verify SSH access

From your local machine, confirm you can SSH into the jumphost and reach the MySQL host:

# Test SSH connectivity to the jumphost
ssh -i ~/.ssh/bastion_key tunnel@bastion.example.com echo "SSH OK"

# Test that the jumphost can reach MySQL
ssh -i ~/.ssh/bastion_key tunnel@bastion.example.com \
  nc -zv db.internal.example.com 3306

chmod 600 ~/.ssh/bastion_key

Step 2: Register the server

DashboardAPI

1. Go to Dashboard → Servers → Register Server
2. Fill in the connection details:

Field	Value	Notes
Name	production-main	Human-readable label
Host	db.internal.example.com	The internal hostname that the jumphost can reach
Port	3306	MySQL port
Connection method	SSH tunnel	Select the radio option
MySQL user	bintrail	The dedicated user you created
MySQL password	••••••	Stored securely in vault

3. Fill in the SSH tunnel configuration:

Field	Value	Notes
SSH host	bastion.example.com	Public address of the jumphost
SSH port	22	Default SSH port
SSH user	tunnel	User on the jumphost
SSH key	(upload key file)	PEM or PPK format, max 16 KB

4. Click Register

curl -X POST https://api.dbtrail.com/api/v1/servers \
  -H "Authorization: Bearer bt_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "production-main",
    "host": "db.internal.example.com",
    "port": 3306,
    "connection_method": "ssh_tunnel",
    "mysql_user": "bintrail",
    "mysql_password": "your_password",
    "ssh_config": {
      "host": "bastion.example.com",
      "port": 22,
      "user": "tunnel",
      "key": "-----BEGIN OPENSSH PRIVATE KEY-----\n...\n-----END OPENSSH PRIVATE KEY-----"
    }
  }'

See the Servers API reference for full request/response details.

SSH tunnel troubleshooting

Direct access

With direct access, the dbtrail agent connects to MySQL without an intermediary. This is simpler to set up but requires the database port to be reachable from the dbtrail agent.

Direct access prerequisites

In addition to the MySQL prerequisites above, you need:

• MySQL host — a hostname or IP reachable from the dbtrail agent
• Network/firewall rules — inbound traffic allowed on the MySQL port (default 3306)

Step 1: Configure network access

Ensure your MySQL server accepts connections from the dbtrail agent:

1. Cloud-hosted databases (AWS RDS, GCP Cloud SQL, Azure, etc.):

   • Add dbtrail's outbound IP (44.237.184.31) to the security group or authorized networks
   • For RDS: edit the VPC security group to allow inbound on port 3306 from 44.237.184.31/32
   • For Cloud SQL: add 44.237.184.31 as an authorized network entry

2. Self-hosted databases:

   • Configure your firewall to allow inbound TCP on port 3306 from 44.237.184.31/32
   • Verify MySQL's bind-address is not set to 127.0.0.1 (use 0.0.0.0 or the specific interface)

Step 2: Register the server

curl -X POST https://api.dbtrail.com/api/v1/servers \
  -H "Authorization: Bearer bt_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "production-main",
    "host": "db.example.com",
    "port": 3306,
    "connection_method": "direct",
    "mysql_user": "bintrail",
    "mysql_password": "your_password"
  }'

Security hardening

If you must use direct access, apply these hardening measures:

Direct access troubleshooting

Onboarding process

After registering a server (via either connection method), it goes through the onboarding process automatically.

1. Go to Dashboard → Servers — your new server will show Pending Approval status:

2. Click the server name to open the detail page. You'll see the current status, connection method, and registration time:

3. Once approved, the Onboarding Progress panel appears and steps begin completing automatically:

4. Watch the onboarding steps complete:
   • Provisioning EC2 — assigning compute resources
   • Waiting for Agent — agent is starting up
   • Initializing Index — creating index tables
   • Schema Snapshot — capturing current schema structure
   • Starting Stream — binlog streaming has started

5. When all steps are complete, the server status changes to Active:

6. You can verify the stream is running from the Infrastructure page:

Connection failures (SSH tunnel)

If your jumphost's firewall is not configured to allow dbtrail's outbound IP, the SSH tunnel connection will fail and the server status will change to error. The dashboard will automatically show a Connection Failed modal with dbtrail's outbound IP and a Retry button.

dbtrail outbound IP: 44.237.184.31

To resolve:

1. Add an inbound rule on your jumphost's security group allowing SSH (port 22) from 44.237.184.31/32
2. Click Retry in the Connection Failed modal

Onboarding will restart the failed step automatically.

Rotate Daemon (optional)

The Rotate Daemon manages automatic binary log rotation on the agent to prevent disk usage from growing unbounded. You can find it on the server detail page:

Click Start to configure the rotation schedule:

Registration fields

Required fields

Optional fields

Server status lifecycle

pending → provisioning → awaiting_firewall* → active → decommissioned
                  ↓              ↓                 ↓
                error          error          disconnected → active

* This is an internal state that auto-completes. If the SSH tunnel connection fails, the server transitions to error and a Connection Failed modal appears.

Updating a server

You can update name, connection_method, and ssh_config via a PATCH request. The host, port, and MySQL credentials cannot be changed after registration. You cannot update a decommissioned server. See the Servers API reference for the update and other endpoints.

Decommissioning a server

Decommissioning is a soft-delete. The server's status is set to decommissioned, streams are stopped, and it no longer appears in list queries. See the Servers API reference for the delete endpoint.

Next steps

Once your server is active and streaming changes:

• Query your changes — search by schema, table, time range, or event type
• Configure streams — filtering, checkpoint intervals, SSL
• Connect Claude — query your database changes from Claude or other AI apps