mysqlkill

README

mysql-kill

Kill a MySQL query/connection by process ID with pt-kill-inspired flags.

Features

• Subcommands: kill and list
• pt-kill-inspired kill flags: --kill / --kill-query
• Auto-detect Amazon RDS / Aurora MySQL and use mysql.rds_kill* procedures
• Config file > env vars > flags
• Optional SSH tunnel (bastion) with strict host key checking by default

Usage

# List running queries
mysql-kill list

# List with regex match
mysql-kill list --match "SELECT"

# List Redash queries (match query comment regex)
mysql-kill list --match "/\\* redash"

# Kill a specific Redash query by ID
mysql-kill kill 123 --kill-query

# Allow writer/primary (default is reader-only)
mysql-kill list --allow-writer

# Show the SQL/CALL to be executed
mysql-kill kill 123 --kill-query --dry-run

# Kill only the running query (standard MySQL or RDS/Aurora detected)
mysql-kill kill 123 --kill-query

# Kill the entire connection
mysql-kill kill 123 --kill

# Allow writer/primary (default is reader-only)
mysql-kill kill 123 --allow-writer --kill-query

# Explicitly enable dry-run
mysql-kill kill 123 --kill --dry-run

Install (Go)

go install github.com/shmokmt/mysql-kill/cmd/mysql-kill@latest

Connection configuration

Configuration file search order:

1. $XDG_CONFIG_HOME/mysql-kill/config.toml
2. os.UserConfigDir()/mysql-kill/config.toml
3. ~/.config/mysql-kill/config.toml

Configuration precedence is:

1. Config file (first found by the search order above)
2. Environment variables
3. CLI flags

If MYSQL_DSN is set, it takes precedence and other MySQL settings are ignored.

Supported environment variables:

• MYSQL_DSN
• MYSQL_HOST (default: 127.0.0.1)
• MYSQL_PORT (default: 3306)
• MYSQL_USER (default: root)
• MYSQL_PASSWORD
• MYSQL_DB
• MYSQL_SOCKET
• MYSQL_TLS

Flag equivalents are also available (see --help).

config.toml example

[mysql-kill]
allow_writer = false

[mysql]
host = "127.0.0.1"
port = 3306
user = "root"
password = "secret"
db = "testdb"
tls = "custom"

[ssh]
host = "bastion.example.com"
port = 22
user = "ec2-user"
key = "~/.ssh/id_rsa"
known_hosts = "~/.ssh/known_hosts"
no_strict_host_key = false

Auto-detect RDS/Aurora

The tool connects to the database and determines whether it is Amazon RDS or Aurora MySQL. If it is, it will use:

• CALL mysql.rds_kill(<id>)
• CALL mysql.rds_kill_query(<id>)

Otherwise it will use standard MySQL statements:

• KILL <id>
• KILL QUERY <id>

If auto-detection fails, the command exits with an error instead of falling back to standard KILL.

SSH tunnel (bastion)

If SSH_HOST (or --ssh-host) is provided, the tool opens a local SSH tunnel and connects to the target DB host/port through it. Strict host key checking is enabled by default.

Supported environment variables:

• SSH_HOST
• SSH_PORT (default: 22)
• SSH_USER (default: $USER)
• SSH_KEY (private key path)
• SSH_KNOWN_HOSTS (default: ~/.ssh/known_hosts)
• SSH_NO_STRICT_HOST_KEY (set to true to disable strict checking)

Example:

export SSH_HOST=bastion.example.com
export SSH_USER=ec2-user
export MYSQL_HOST=internal-db.example.com
export MYSQL_PORT=3306

mysql-kill kill 123 --kill-query

Notes:

• The DB host/port are still configured via MYSQL_HOST/MYSQL_PORT (or flags), even when tunneling.
• --dry-run still connects in order to auto-detect RDS/Aurora, so the SSH tunnel will be used.

Notes

• --kill and --kill-query are mutually exclusive.
• --kill or --kill-query is required for the kill command.
• By default, the tool requires the target to be a reader (read-only). Use --allow-writer to allow writer/primary connections.

Integration tests (Docker)

This project uses real MySQL via Docker for integration tests (no mocks).

# Start MySQL
docker compose up -d

# Run integration tests
go test -tags=integration ./...

Default test connection values (override with env vars if needed):

• MYSQL_TEST_HOST=127.0.0.1
• MYSQL_TEST_PORT=3307
• MYSQL_TEST_USER=root
• MYSQL_TEST_PASSWORD=testpass
• MYSQL_TEST_DB=testdb

Documentation

Index

• func Run(ctx context.Context, cli *CLI, command string) error
• type AppConfig
• type CLI
• type Execer
• type KillCmd
• type ListCmd
• type MySQLConfig
• type SSHConfig
  • func (c SSHConfig) Enabled() bool

Functions

func Run

func Run(ctx context.Context, cli *CLI, command string) error

Run executes the selected subcommand.

Types

type AppConfig

type AppConfig struct {
	MySQL       MySQLConfig
	SSH         SSHConfig
	AllowWriter bool
}

AppConfig holds the resolved settings for the application.

type CLI

type CLI struct {
	DSN      string `help:"MySQL DSN (env: MYSQL_DSN)."`
	Host     string `name:"mysql-host" help:"MySQL host (env: MYSQL_HOST)."`
	Port     int    `help:"MySQL port (env: MYSQL_PORT)."`
	User     string `name:"mysql-user" help:"MySQL user (env: MYSQL_USER)."`
	Password string `help:"MySQL password (env: MYSQL_PASSWORD)."`
	DB       string `name:"mysql-db" help:"MySQL database (env: MYSQL_DB)."`
	Socket   string `help:"MySQL unix socket (env: MYSQL_SOCKET)."`
	TLS      string `help:"MySQL TLS config name (env: MYSQL_TLS)."`

	SSHHost            string `help:"SSH bastion host (env: SSH_HOST)."`
	SSHPort            int    `help:"SSH bastion port (env: SSH_PORT)."`
	SSHUser            string `help:"SSH bastion user (env: SSH_USER)."`
	SSHKey             string `help:"SSH private key file path (env: SSH_KEY)."`
	SSHKnownHosts      string `help:"known_hosts path for strict checking (env: SSH_KNOWN_HOSTS)."`
	SSHNoStrictHostKey bool   `help:"Disable strict host key checking (env: SSH_NO_STRICT_HOST_KEY)."`

	AllowWriter bool `help:"Allow connecting to writer/primary (default: reader only)."`

	Version kong.VersionFlag `name:"version" help:"Print version information and quit."`

	Kill *KillCmd `cmd:"" help:"Kill a query or connection by process ID."`
	List *ListCmd `cmd:"" help:"List running queries (from processlist)."`
}

CLI defines the top-level command structure for mysql-kill.

type Execer

type Execer interface {
	ExecContext(ctx context.Context, query string, args ...any) (sql.Result, error)
}

Execer executes SQL statements.

type KillCmd

type KillCmd struct {
	QueryID   int64 `arg:"" name:"id" help:"MySQL process (query) ID to target."`
	Kill      bool  `help:"Kill the connection (pt-kill-inspired --kill)."`
	KillQuery bool  `help:"Kill only the running query (pt-kill-inspired --kill-query)."`
	DryRun    bool  `help:"Print the SQL/CALL without executing."`
}

KillCmd represents the kill subcommand.

type ListCmd

type ListCmd struct {
	Match string `help:"Filter by SQL regex (INFO)."`
}

ListCmd represents the list subcommand.

type MySQLConfig

type MySQLConfig struct {
	DSN      string
	Host     string
	Port     int
	User     string
	Password string
	DB       string
	Socket   string
	TLS      string
}

MySQLConfig holds MySQL connection settings.

type SSHConfig

type SSHConfig struct {
	Host            string
	Port            int
	User            string
	KeyPath         string
	KnownHostsPath  string
	NoStrictHostKey bool
	Timeout         time.Duration
}

SSHConfig holds SSH tunneling settings.

func (SSHConfig) Enabled

func (c SSHConfig) Enabled() bool

Enabled reports whether SSH tunneling is requested.