DBTrail

From the terminal

Set DBTrail up and run it with the dbtrail command. Connect your MySQL, take the first copy and open the MySQL port without opening a browser.

Everything the web interface does to get you started, as commands. Two of them take you from an installed DBTrail to a query answered on port 3309.

Needs DBTrail 0.131.0 or newer. On 0.128.1 to 0.130.0, turn the port on after the first copy with dbtrail port on.

Where the command is

The installer leaves dbtrail in the folder it created, beside docker-compose.yml. Run it from there:

cd dbtrail
./dbtrail server list

To type dbtrail from any folder, link it once:

sudo ln -s "$PWD/dbtrail" /usr/local/bin/dbtrail

Installed before 0.128.1? Get the command with one download, from that same folder, after upgrading:

curl -fsSL -o dbtrail https://raw.githubusercontent.com/dbtrail/dbtrail/main/dbtrail.sh && chmod +x dbtrail

The package installs it. It reads a file only the service's account can read, so run it with sudo:

sudo dbtrail server list

Set it up

Create DBTrail's user

your MySQL

Once, with a login that can create users:

CREATE USER 'dbtrail'@'%' IDENTIFIED BY <a password>;
GRANT REPLICATION SLAVE, REPLICATION CLIENT, SELECT ON *.* TO 'dbtrail'@'%';
GRANT RELOAD, BACKUP_ADMIN, PROCESS, SHOW VIEW ON *.* TO 'dbtrail'@'%';

MariaDB has no BACKUP_ADMIN: leave that word out. Amazon RDS and Aurora take other grants for the last line: read this first.

And the forwarding user: what DBTrail's MySQL port runs a statement as when the copy cannot answer it. Your application's grants, and no more:

CREATE USER 'shop_fwd'@'%' IDENTIFIED BY <another password>;
GRANT SELECT ON shop.* TO 'shop_fwd'@'%';

Connect your MySQL

terminal

The options are the ones of the mysql client. -p asks for the password.

dbtrail server add -h db1.example.com -u dbtrail -p --name shop

DBTrail runs its checks and starts recording changes when they pass. The first server also turns the MySQL port on: the command prints its password, once, and asks for the forwarding user (Enter skips it).

Each command ends by naming the next one. Without a terminal, put the forwarding user in the option file instead (--defaults-file, under [dbtrail-forward]).

Take the first copy

terminal
dbtrail snapshot run shop
dbtrail snapshot schedule shop --every 1h

The first command reads every table once, with a short lock so they are all read at one moment: pick a quiet time. It waits until the copy is ready. The second keeps the copy current from the recorded changes, without reading your MySQL again.

Query it

any MySQL client

The user is your server's name, and the password is the one server add printed. Lost it? dbtrail port new-password makes another.

You should see

The rows. That query ran on DBTrail's copy, not on your MySQL. A lookup by key or a write would have run on your MySQL, as shop_fwd.

What each command is for

I want toRun
See my serversdbtrail server list
Add a server from a .my.cnfdbtrail server add --defaults-file ~/.my.cnf
Change DBTrail's password on a serverdbtrail server edit shop -p
Point at a database that moveddbtrail server edit shop -h db2.example.com
Rename a serverdbtrail server edit shop --name store
Record some schemas onlydbtrail server edit shop --schemas shop,billing
Pause and resume recordingdbtrail server stop shop, dbtrail server start shop
Remove a serverdbtrail server remove shop
Take a copy nowdbtrail snapshot run shop
See how the last copy endeddbtrail snapshot status shop
Send copies to S3 toodbtrail snapshot location shop --s3 s3://bucket/snapshots/
See whether the port is ondbtrail port status
Get a new port passworddbtrail port new-password
Set or change a server's forwarding userdbtrail server forward-user shop -u shop_fwd -p
Answer everything from the copydbtrail port routing off
Answer a server from the last copy only, or with its latest changesdbtrail port mode shop fast, dbtrail port mode shop fresh
Have MySQL answer when a server's copy is more than 5 minutes behind its sourcedbtrail port max-behind shop 5m (off removes it)
Check /etc/dbtrail/dbtrail.cnfdbtrail config check
Turn the port on or offdbtrail port on, dbtrail port off
Reset the web interface's logindbtrail user set-password

dbtrail <command> --help lists every option of a command.

See what it is doing

Once a minute each service writes one line per server to its own log.

docker compose logs -f router bintrail | grep msg=status
journalctl -u bintrail-router -u bintrail-console -f | grep msg=status

Each line is one line in the log; it is broken up here to name its numbers. They count the minute, not everything since the start, and a quiet minute still writes a line. Errors are in the same logs:

docker compose logs -f router bintrail | grep -E 'level=(ERROR|WARN)'

STATUS_LOG_INTERVAL=30s in .env (Docker), or BINTRAIL_STATUS_LOG_INTERVAL=30s in /etc/bintrail/bintrail-console.env (Linux packages), changes how often. off writes none.

Next

On this page