Repository navigation
Releases
HACS installs from the release zip again
What's Changed
Changed
- HACS installs from the release zip again. GitHub has shrunk the headers of its release-download redirect, so HACS can download the release zip again (see hacs/integration#5643). This undoes the workaround of 2.2.0.
Nothing changes for a connection or a sensor that is already set up.
Diagnostics for easier troubleshooting & HACS download workaround
What's Changed
New
- Diagnostics: Download diagnostics from the menu of the connection to make troubleshooting easier. The file holds the connection settings, the configuration and the queries of every sensor, the figures of the last run of each sensor and the size of the connection pool. The host, port, username, password and database name are masked, as are the title and the unique ID of the connection. No row of the database and no entity ID is included. The queries are, so read them before sharing the file.
Changed
- HACS installs file by file for now. GitHub currently answers release downloads with a redirect whose headers are too large for Home Assistant's HTTP client, so HACS fails with
Got more than 8190 bytes when readingfor every integration that installs from a release zip (see hacs/integration#5643). As a workaround,zip_releaseis removed fromhacs.jsonuntil this is solved. The zip is still attached to the release for a manual install.
Nothing changes for a connection or a sensor that is already set up.
Probatio and strict typing
Home Assistant 2026.9.0 or newer is now required, and the integration is fully type checked. Nothing changes for a connection or a sensor that is already set up.
Before you update
- Home Assistant 2026.9.0 or newer is required (previously 2026.3.0). Home Assistant replaced voluptuous with probatio in that release, and the forms and actions of this integration now use probatio directly. HACS keeps a Home Assistant older than 2026.9.0 on version 2.0.0.
Changed
- The forms and actions are validated with probatio, the library Home Assistant itself switched to.
- The whole integration passes
mypy --strictand ships apy.typedmarker. This is checked in CI from now on.
See the CHANGELOG for the full details.
Read only sessions and no more YAML
Every connection is now opened read only, the YAML configuration is gone, and a value passed to set_query is exactly what reaches the database. This is a major release because the last two change behaviour. A connection and its sensors set up through the user interface, or imported from YAML by an earlier release, keep working with the same entity IDs and history.
Requires Home Assistant 2026.3.0 or newer.
Before you update
- Remove the YAML. The
ha_mysql:section and the sensors withplatform: ha_mysqlinconfiguration.yamlare no longer read. Home Assistant reports them for as long as they are there. Remove them; nothing is lost. - Check your sensors under Configure. The stored sensors are the ones imported the last time Home Assistant started with an earlier release. A change made in
configuration.yamlafter that is not in them. - A YAML configuration that was never imported is not picked up. Add the connection and its sensors through the user interface.
- There is no way back without a backup. Config entries move to version 2, and Home Assistant refuses to load them with 1.7.0 or older.
Changed
- Every database session is opened read only. The driver runs
SET SESSION TRANSACTION READ ONLYafter each login: for the pool, for the connection made again after the server dropped an idle one, and for the check made while setting up. Tested against MariaDB 10.11: anINSERT, anUPDATE, aDELETEand a temporary table are refused with error 1792, aSELECTworks. It sits behind the check on the query text, which still refuses anything but a single reading statement,SETincluded, so a query cannot lift it. A user with onlySELECTrights keeps working. The rights of the database user remain the real boundary: aSELECTcan still write a file throughINTO OUTFILEif the user has theFILEprivilege. set_querybindsvaluesexactly as given. Home Assistant already renders the templates of an automation or a script before an action runs, and the integration used to render the result a second time. A value that still reads{{ ... }}when it arrives, as it can through the REST API, is now bound as that text. Automations and scripts are not affected.
Removed
- The YAML configuration, deprecated in 1.7.0.
- The Repairs issue 1.7.0 raised for it, on the first start.
- The
sourcemarker the YAML import left on sensors, which the migration to version 2 drops.
Full details: CHANGELOG
Connection pool fix, sign in again and Reconfigure
Error handling, the configuration screens and the translations are brought in line with mysql_query, and a leak in the connection pool is fixed. Automations, scripts and dashboards keep working as they are.
Versions 1.6.0 and 1.6.1 were never released and are part of this one.
Requires Home Assistant 2026.3.0 or newer. HACS refuses to download this version on an older Home Assistant, which stays on the previous release.
What's new
- Sign in again when the database refuses the credentials. Home Assistant now asks for a new username and password and updates the existing connection, at startup and when a sensor's query is refused because the password was changed on the server.
- Reconfigure, in the ⋮ menu of the connection, changes the host, port, credentials, database and TLS. The new settings are tested before they are saved. The password field starts empty; leave it empty to keep the current password.
- Repairs warns about the YAML configuration, which is deprecated (see below).
- Translated messages (English and Dutch) for every failure you get to see: why a connection does not start, why a sensor stopped updating, and why
set_queryrefused a call.
Fixed
- A failed query no longer takes a connection out of the pool for good. After ten failed or timed-out queries on one database connection, for instance a sensor with a mistake in its query polled every 30 seconds, every sensor of that connection stopped updating until the integration was reloaded.
- Reloading, disabling or removing a database connection no longer hangs after such a failure.
- The password is no longer sent to the browser. The form to change the connection used to be filled in with the stored password.
- Changing the host or database of a connection kept its old identity, so the old combination could not be added again and the new one could end up identical to another connection.
- A connection with TLS on no longer builds its TLS context on the event loop, which Home Assistant reported as a blocking call.
- A query that timed out was reported without a reason; it now says after how many seconds.
Changed
- The connection is changed under Reconfigure, no longer under Configure. Configure is for the sensors.
- A failed connection is told apart by its cause, at startup and in the forms alike. A server that cannot be reached, is full or is shutting down is retried by Home Assistant. Refused credentials ask for new ones. An unknown database and other refusals (a host the account may not connect from, a locked account, an expired password) fail with the reason from the server.
- The bulky attributes are left out of the recorder:
json_result,json_result_truncated,executed_sql_query,query_dateandquery_time. They are still in the current state. The README no longer advises excluding the whole sensor from the recorder. - The actions
set_queryandselect_recordstay listed while no connection is loaded. - The database field is now labelled "Database name".
Deprecated
- The YAML configuration (the
ha_mysql:section and sensors withplatform: ha_mysql) still works in this release and is removed in 2.0.0. It was imported and is stored in Home Assistant, so removing it fromconfiguration.yamlloses nothing; Repairs shows what to do.
Full details: CHANGELOG
Add a persist option to set_query
Added
ha_mysql.set_querygained apersistoption. When set, the replacement query (and itsvalues) survives a restart: the sensor's normal polling re-runs it automatically instead of falling back to the query configured for the sensor. Useful for a sensor built purely to display the result of a runtime lookup. Off by default.
Full details: CHANGELOG.md
Async database driver (aiomysql) + optional TLS
Highlights
The database driver has been replaced with aiomysql, the same async driver mysql_query already uses. This closes a gap where a query that stopped getting answers after connecting could hold onto its pooled connection forever, eventually exhausting the whole pool.
Added
- Encrypt the connection (TLS) — a new connection option (off by default) in both the initial setup and Change the database connection. When enabled, the integration verifies the session was actually encrypted instead of trusting the driver's silent fallback to plain text.
Changed
- Replaced
mysql-connector-pythonwithaiomysqlas the database driver. All database calls are now natively asynchronous instead of running in an executor thread. - The manual retry-with-pool-rebuild logic is gone; a dropped connection is now recovered the same way
mysql_querydoes it (a ping-based reconnect, backed by the coordinator's own poll interval). - A single timeout now covers a whole query end to end — acquiring a pooled connection, reconnecting it if needed, and running the statement — instead of only bounding the initial handshake.
No action needed for existing installations: the new TLS option defaults to off and every other setting stays the same.
Full details: CHANGELOG.md
Security Fix, Reconfigurable Connections and Brand Images
1.3.0 - 2026-09-25
This release closes a SQL injection gap in ha_mysql.set_query, makes it
possible to change a connection's host, port, username, password and database
without removing and re-adding the integration, and gives the integration its
own icon and logo in the Home Assistant UI.
Added
- Configure → Change the database connection, to edit the host, port,
username, password and database of an existing connection from the
integration card. The new connection is tested before it replaces the old
one; the sensors are left untouched. valuesonha_mysql.set_query, to bind values to%splaceholders in the
query separately from its text. The driver quotes and escapes each value
according to its type, so a quote, a semicolon or a stray backslash in the
value can no longer change what the statement does. Templates invalues
are rendered with their native type, so a number or a boolean is bound as
such instead of as text.- Brand images shipped with the integration, in
custom_components/ha_mysql/brand/:icon.png(256x256),icon@2x.png
(512x512),logo.png(256x64) andlogo@2x.png(512x128). Home Assistant
2026.3.0 and later read these directly and give them priority over the
brands CDN, so the integration now shows its own icon and logo in the UI.
Older Home Assistant versions ignore the folder and are unaffected. scripts/build_brands.py, which generates those images from the raw
artwork. It keys out the background with a flood fill from the image
border, so dark elements inside the artwork are preserved, and typesets
the wordmark.- Releases ship a
homeassistant-ha_mysql.zipasset again, built and
attached automatically by.github/workflows/release.yamlwhen a release
is published. HACS installs from it instead of fetching every file
separately through the GitHub API, and the downloads badge counts again.
Changed
- Only a single, read-only statement is now accepted everywhere a query
enters the integration: the user interface,configuration.yamland
ha_mysql.set_query. A query with more than one statement, or one that is
notSELECT-style, is refused before it ever reaches the database.
Previously, testing a sensor query when adding or editing it would run a
write for real if the query happened to contain one. - A newly added sensor's entity ID and friendly name now include the
connection's device name, for example
sensor.mydatabase_192_168_1_10_employeesand "mydatabase @ 192.168.1.10
Employees", the same way Home Assistant names every other entity that
belongs to a device. Sensors that already existed keep the entity ID and
history they already had; this only applies to sensors added from now on.
v1.1.0 - Config Flow, Value Options and Device Grouping
🚀 Added
- Config Flow Support: Full UI configuration via Home Assistant's integration menu, with automatic YAML migration on setup.
- Value Customization: Added support for
value_columnandvalue_templateto easily extract and format sensor values. - Statistics & Entity Classes: Added support for
state_classanddevice_class. - Device Grouping: Entities are now properly grouped under a single Device in Home Assistant using
DeviceInfo. - Localization: Added full English and Dutch translations (
strings.json,en.json,nl.json).
🛠️ Fixed & Improved
- DataUpdateCoordinator Integration: Refactored the core engine to use
DataUpdateCoordinatorfor reliable state updates and availability handling. - MySQL Connection Handling: Fixed
autocommitbehavior to prevent stale data snapshots on InnoDB engines, and added automatic reconnect handling. - Bug Fixes: Resolved all edge-case key errors, handling of missing configuration parameters, and service call exceptions.
- Type Safety & Testing: Tightened typing across the codebase and achieved 100% test coverage suite (22 tests passing).
🔄 Changed
- Every release now ships a
homeassistant-ha_mysql.zip, which is what HACS installs and what a manual installation can be unpacked from.
Adjusted component name for HACS since it was wrong
Adjusted component name for HACS since it was wrong
Full Changelog: v1.0.2...v1.0.3