moritzheiber/apprentice

Apprentice is a small health-check tool for MariaDB and MySQL databases. It tells your load balancer whether a specific database server is actually ready to handle live traffic, so you never accidentally send users to a database that's broken or falling behind. Here's the problem it solves: when you run multiple database servers, a load balancer usually just checks whether the server responds at all. But a database that's "alive" might still be unhealthy. It might be lagging behind the primary server by several minutes, serving stale data. Or in a cluster setup, it might have disconnected from the other nodes. Apprentice connects to the database and runs actual integrity checks, then exposes a simple HTTP endpoint: a 200 response means the server is healthy and ready, a 503 means stay away. The tool checks different things depending on your setup. For a standard MySQL/MariaDB replica, it verifies that replication is actively running and measures how many seconds behind the primary server the replica has fallen, with a configurable threshold (defaulting to 120 seconds). For a Galera cluster, it checks that the cluster has enough members, that replication is turned on, and that the node isn't in a bad state. You can optionally allow a "donor" state, where a node is sharing data with another cluster member, to still count as healthy. The typical user is someone running a multi-server database setup behind a load balancer like HAProxy. For example, if you have five read replicas handling user queries and one starts lagging behind by five minutes, Apprentice detects that and tells HAProxy to stop sending traffic to it until it catches up. This prevents users from seeing outdated data without you having to manually intervene. The project is notably minimal, weighing in at under 300 lines of Ruby code, and does one thing well. It doesn't load-balance connections itself or relay client traffic. It's purely a signal provider that helps your existing infrastructure make smarter routing decisions. The README notes that PostgreSQL support has been requested but not yet built.