Functions
None	_async_create_issue_deprecated_version (HomeAssistant hass, AwesomeVersion server_version, str dialect_name, AwesomeVersion min_version)

None	_async_create_mariadb_range_index_regression_issue (HomeAssistant hass, AwesomeVersion version)

None	_async_delete_issue_deprecated_version (HomeAssistant hass, str dialect_name)

datetime\|None	_datetime_or_none (str value)

AwesomeVersion\|None	_extract_version_from_server_response (str server_response)

AwesomeVersion	_extract_version_from_server_response_or_raise (str server_response)

NoReturn	_fail_unsupported_dialect (str dialect_name)

bool	_is_retryable_error (Recorder instance, OperationalError err)

_FuncOrMethType[_P, bool]	_P (_FuncOrMethType[_P, bool] job, str description, bool method)

Callable[[_FuncType[_P, bool]], _FuncType[_P, bool]]	_P (str description)

_FuncOrMethType[_P, _R]	_R (_FuncOrMethType[_P, _R] job, str description, int attempts, bool method)

Callable[[_FuncType[_P, _R]], _FuncType[_P, _R]]	_R (str description, int attempts)

NoReturn	_raise_if_version_unsupported (str server_version, str dialect_name, str minimum_version)

AwesomeVersion	_simple_version (str version)

None	async_create_backup_failure_issue (HomeAssistant hass, datetime local_start_time)

bool	async_migration_in_progress (HomeAssistant hass)

bool	async_migration_is_live (HomeAssistant hass)

bool	basic_sanity_check (SQLiteCursor cursor)

dict	build_mysqldb_conv ()

str	dburl_to_path (str dburl)

None	end_incomplete_runs (Session session, datetime start_time)

list[Row]	execute (Query qry, bool to_native=False, bool validate_entity_ids=True)

None	execute_on_connection (DBAPIConnection dbapi_connection, str statement)

Sequence[Row]\|Result	execute_stmt_lambda_element (Session session, StatementLambdaElement stmt, datetime\|None start_time=None, datetime\|None end_time=None, int yield_per=DEFAULT_YIELD_STATES_ROWS, bool orm_rows=True)

Callable[[Exception], bool]	filter_unique_constraint_integrity_error (Recorder instance, str row_type)

str\|None	get_index_by_name (Session session, str table_name, str index_name)

bool	is_second_sunday (datetime date_time)

bool	last_run_was_recently_clean (SQLiteCursor cursor)

None	move_away_broken_database (str dbfile)

None	periodic_db_cleanups (Recorder instance)

Any	query_on_connection (DBAPIConnection dbapi_connection, str statement)

tuple[datetime\|None, datetime\|None]	resolve_period (StatisticPeriod period_def)

None	run_checks_on_open_db (str dbpath, SQLiteCursor cursor)

date	second_sunday (int year, int month)

DatabaseEngine\|None	setup_connection_for_dialect (Recorder instance, str dialect_name, DBAPIConnection dbapi_connection, bool first_connection)

bool	validate_or_move_away_sqlite_database (str dburl)

bool	validate_sqlite_database (str dbpath)

Generator[None]	write_lock_db_sqlite (Recorder instance)

Detailed Description

SQLAlchemy util functions.

Function Documentation

◆ _async_create_issue_deprecated_version()

None homeassistant.components.recorder.util._async_create_issue_deprecated_version	(	HomeAssistant	hass,
		AwesomeVersion	server_version,
		str	dialect_name,
		AwesomeVersion	min_version
	)

private

Warn about upcoming unsupported database version.

Definition at line 386 of file util.py.

◆ _async_create_mariadb_range_index_regression_issue()

None homeassistant.components.recorder.util._async_create_mariadb_range_index_regression_issue	(	HomeAssistant	hass,
		AwesomeVersion	version
	)

private

Create an issue for the index range regression in older MariaDB.

The range scan issue was fixed in MariaDB 10.5.17, 10.6.9, 10.7.5, 10.8.4 and later.

Definition at line 451 of file util.py.

◆ _async_delete_issue_deprecated_version()

None homeassistant.components.recorder.util._async_delete_issue_deprecated_version	(	HomeAssistant	hass,
		str	dialect_name
	)

private

Delete the issue about upcoming unsupported database version.

Definition at line 378 of file util.py.

◆ _datetime_or_none()

datetime | None homeassistant.components.recorder.util._datetime_or_none ( str value )

private

Fast version of mysqldb DateTime_or_None.

https://github.com/PyMySQL/mysqlclient/blob/v2.1.0/MySQLdb/times.py#L66

Definition at line 429 of file util.py.

◆ _extract_version_from_server_response()

AwesomeVersion | None homeassistant.components.recorder.util._extract_version_from_server_response ( str server_response )

private

Attempt to extract version from server response.

Definition at line 419 of file util.py.

◆ _extract_version_from_server_response_or_raise()

AwesomeVersion homeassistant.components.recorder.util._extract_version_from_server_response_or_raise ( str server_response )

private

Extract version from server response.

Definition at line 408 of file util.py.

◆ _fail_unsupported_dialect()

NoReturn homeassistant.components.recorder.util._fail_unsupported_dialect ( str dialect_name )

private

Warn about unsupported database version.

Definition at line 346 of file util.py.

◆ _is_retryable_error()

bool homeassistant.components.recorder.util._is_retryable_error	(	Recorder	instance,
		OperationalError	err
	)

private

Return True if the error is retryable.

Definition at line 636 of file util.py.

◆ _P() [1/2]

_FuncOrMethType[_P, bool] homeassistant.components.recorder.util._P	(	_FuncOrMethType[_P, bool]	job,
		str	description,
		bool	method
	)

private

Definition at line 680 of file util.py.

◆ _P() [2/2]

Callable[[_FuncType[_P, bool]], _FuncType[_P, bool]] homeassistant.components.recorder.util._P ( str description )

private

Execute a database job repeatedly until it succeeds.

The job should return True if it finished, and False if it needs to be rescheduled.

Definition at line 652 of file util.py.

◆ _R() [1/2]

_FuncOrMethType[_P, _R] homeassistant.components.recorder.util._R	(	_FuncOrMethType[_P, _R]	job,
		str	description,
		int	attempts,
		bool	method
	)

private

Definition at line 750 of file util.py.

◆ _R() [2/2]

Callable[[_FuncType[_P, _R]], _FuncType[_P, _R]] homeassistant.components.recorder.util._R	(	str	description,
		int	attempts
	)

private

Execute a database job repeatedly until it succeeds, at most attempts times.

This wrapper handles InnoDB deadlocks and lock timeouts.

This is different from retryable_database_job in that it will retry the job
attempts number of times instead of returning False if the job fails.

Definition at line 708 of file util.py.

◆ _raise_if_version_unsupported()

NoReturn homeassistant.components.recorder.util._raise_if_version_unsupported	(	str	server_version,
		str	dialect_name,
		str	minimum_version
	)

private

Warn about unsupported database version.

Definition at line 360 of file util.py.

◆ _simple_version()

AwesomeVersion homeassistant.components.recorder.util._simple_version ( str version )

private

Return a simple version.

Definition at line 79 of file util.py.

◆ async_create_backup_failure_issue()

None homeassistant.components.recorder.util.async_create_backup_failure_issue	(	HomeAssistant	hass,
		datetime	local_start_time
	)

Create an issue when the backup fails because we run out of resources.

Definition at line 479 of file util.py.

◆ async_migration_in_progress()

bool homeassistant.components.recorder.util.async_migration_in_progress ( HomeAssistant hass )

Determine if a migration is in progress.

This is a thin wrapper that allows us to change
out the implementation later.

Definition at line 809 of file util.py.

◆ async_migration_is_live()

bool homeassistant.components.recorder.util.async_migration_is_live ( HomeAssistant hass )

Determine if a migration is live.

This is a thin wrapper that allows us to change
out the implementation later.

Definition at line 820 of file util.py.

◆ basic_sanity_check()

bool homeassistant.components.recorder.util.basic_sanity_check ( SQLiteCursor cursor )

Check tables to make sure select does not fail.

Definition at line 252 of file util.py.

◆ build_mysqldb_conv()

dict homeassistant.components.recorder.util.build_mysqldb_conv ( )

Build a MySQLDB conv dict that uses cisco8601 to parse datetimes.

Definition at line 440 of file util.py.

◆ dburl_to_path()

str homeassistant.components.recorder.util.dburl_to_path ( str dburl )

Convert the db url into a filesystem path.

Definition at line 226 of file util.py.

◆ end_incomplete_runs()

None homeassistant.components.recorder.util.end_incomplete_runs	(	Session	session,
		datetime	start_time
	)

End any incomplete recorder runs.

Definition at line 625 of file util.py.

◆ execute()

list[Row] homeassistant.components.recorder.util.execute	(	Query	qry,
		bool	to_native = `False`,
		bool	validate_entity_ids = `True`
	)

Query the database and convert the objects to HA native form.

This method also retries a few times in the case of stale connections.

Definition at line 119 of file util.py.

◆ execute_on_connection()

None homeassistant.components.recorder.util.execute_on_connection	(	DBAPIConnection	dbapi_connection,
		str	statement
	)

Execute a single statement with a dbapi connection.

Definition at line 330 of file util.py.

◆ execute_stmt_lambda_element()

Sequence[Row] \| Result homeassistant.components.recorder.util.execute_stmt_lambda_element	(	Session	session,
		StatementLambdaElement	stmt,
		datetime \| None	start_time = `None`,
		datetime \| None	end_time = `None`,
		int	yield_per = `DEFAULT_YIELD_STATES_ROWS`,
		bool	orm_rows = `True`
	)

Execute a StatementLambdaElement.

If the time window passed is greater than one day
the execution method will switch to yield_per to
reduce memory pressure.

It is not recommended to pass a time window
when selecting non-ranged rows (ie selecting
specific entities) since they are usually faster
with .all().

Definition at line 172 of file util.py.

◆ filter_unique_constraint_integrity_error()

Callable[[Exception], bool] homeassistant.components.recorder.util.filter_unique_constraint_integrity_error	(	Recorder	instance,
		str	row_type
	)

Create a filter for unique constraint integrity errors.

Definition at line 946 of file util.py.

◆ get_index_by_name()

str \| None homeassistant.components.recorder.util.get_index_by_name	(	Session	session,
		str	table_name,
		str	index_name
	)

Get an index by name.

Definition at line 927 of file util.py.

◆ is_second_sunday()

bool homeassistant.components.recorder.util.is_second_sunday ( datetime date_time )

Check if a time is the second sunday of the month.

Definition at line 842 of file util.py.

◆ last_run_was_recently_clean()

bool homeassistant.components.recorder.util.last_run_was_recently_clean ( SQLiteCursor cursor )

Verify the last recorder run was recently clean.

Definition at line 231 of file util.py.

◆ move_away_broken_database()

None homeassistant.components.recorder.util.move_away_broken_database ( str dbfile )

Move away a broken sqlite3 database.

Definition at line 308 of file util.py.

◆ periodic_db_cleanups()

None homeassistant.components.recorder.util.periodic_db_cleanups ( Recorder instance )

Run any database cleanups that need to happen periodically.

These cleanups will happen nightly or after any purge.

Definition at line 777 of file util.py.

◆ query_on_connection()

Any homeassistant.components.recorder.util.query_on_connection	(	DBAPIConnection	dbapi_connection,
		str	statement
	)

Execute a single statement with a dbapi connection and return the result.

Definition at line 337 of file util.py.

◆ resolve_period()

tuple[datetime | None, datetime | None] homeassistant.components.recorder.util.resolve_period ( StatisticPeriod period_def )

Return start and end datetimes for a statistic period definition.

Definition at line 871 of file util.py.

◆ run_checks_on_open_db()

None homeassistant.components.recorder.util.run_checks_on_open_db	(	str	dbpath,
		SQLiteCursor	cursor
	)

Run checks that will generate a sqlite3 exception if there is corruption.

Definition at line 281 of file util.py.

◆ second_sunday()

date homeassistant.components.recorder.util.second_sunday	(	int	year,
		int	month
	)

Return the datetime.date for the second sunday of a month.

Definition at line 831 of file util.py.

◆ setup_connection_for_dialect()

DatabaseEngine \| None homeassistant.components.recorder.util.setup_connection_for_dialect	(	Recorder	instance,
		str	dialect_name,
		DBAPIConnection	dbapi_connection,
		bool	first_connection
	)

Execute statements needed for dialect connection.

Definition at line 496 of file util.py.

◆ validate_or_move_away_sqlite_database()

bool homeassistant.components.recorder.util.validate_or_move_away_sqlite_database ( str dburl )

Ensure that the database is valid or move it away.

Definition at line 211 of file util.py.

◆ validate_sqlite_database()

bool homeassistant.components.recorder.util.validate_sqlite_database ( str dbpath )

Run a quick check on an sqlite database to see if it is corrupt.

Definition at line 266 of file util.py.

◆ write_lock_db_sqlite()

Generator[None] homeassistant.components.recorder.util.write_lock_db_sqlite ( Recorder instance )

Lock database for writes.

Definition at line 792 of file util.py.

Variable Documentation

◆ _LOGGER

homeassistant.components.recorder.util._LOGGER

private

Definition at line 66 of file util.py.

◆ DAYS_IN_WEEK

homeassistant.components.recorder.util.DAYS_IN_WEEK

Definition at line 116 of file util.py.

◆ DEFAULT_YIELD_STATES_ROWS

homeassistant.components.recorder.util.DEFAULT_YIELD_STATES_ROWS

Definition at line 71 of file util.py.

◆ FIRST_POSSIBLE_SUNDAY

homeassistant.components.recorder.util.FIRST_POSSIBLE_SUNDAY

Definition at line 114 of file util.py.

◆ MARIA_DB_106

homeassistant.components.recorder.util.MARIA_DB_106

Definition at line 87 of file util.py.

◆ MARIA_DB_107

homeassistant.components.recorder.util.MARIA_DB_107

Definition at line 90 of file util.py.

◆ MARIA_DB_108

homeassistant.components.recorder.util.MARIA_DB_108

Definition at line 93 of file util.py.

◆ MARIADB_WITH_FIXED_IN_QUERIES_105

homeassistant.components.recorder.util.MARIADB_WITH_FIXED_IN_QUERIES_105

Definition at line 86 of file util.py.

◆ MARIADB_WITH_FIXED_IN_QUERIES_106

homeassistant.components.recorder.util.MARIADB_WITH_FIXED_IN_QUERIES_106

Definition at line 88 of file util.py.

◆ MARIADB_WITH_FIXED_IN_QUERIES_107

homeassistant.components.recorder.util.MARIADB_WITH_FIXED_IN_QUERIES_107

Definition at line 92 of file util.py.

◆ MARIADB_WITH_FIXED_IN_QUERIES_108

homeassistant.components.recorder.util.MARIADB_WITH_FIXED_IN_QUERIES_108

Definition at line 95 of file util.py.

◆ MAX_RESTART_TIME

homeassistant.components.recorder.util.MAX_RESTART_TIME

Definition at line 106 of file util.py.

◆ MIN_VERSION_MARIA_DB

homeassistant.components.recorder.util.MIN_VERSION_MARIA_DB

Definition at line 84 of file util.py.

◆ MIN_VERSION_MYSQL

homeassistant.components.recorder.util.MIN_VERSION_MYSQL

Definition at line 96 of file util.py.

◆ MIN_VERSION_PGSQL

homeassistant.components.recorder.util.MIN_VERSION_PGSQL

Definition at line 97 of file util.py.

◆ MIN_VERSION_SQLITE

homeassistant.components.recorder.util.MIN_VERSION_SQLITE

Definition at line 98 of file util.py.

◆ MIN_VERSION_SQLITE_MODERN_BIND_VARS

homeassistant.components.recorder.util.MIN_VERSION_SQLITE_MODERN_BIND_VARS

Definition at line 100 of file util.py.

◆ minutes

homeassistant.components.recorder.util.minutes

Definition at line 106 of file util.py.

◆ PERIOD_SCHEMA

homeassistant.components.recorder.util.PERIOD_SCHEMA

Definition at line 847 of file util.py.

◆ QUERY_RETRY_WAIT

homeassistant.components.recorder.util.QUERY_RETRY_WAIT

Definition at line 69 of file util.py.

◆ RECOMMENDED_MIN_VERSION_MARIA_DB

homeassistant.components.recorder.util.RECOMMENDED_MIN_VERSION_MARIA_DB

Definition at line 85 of file util.py.

◆ RECOMMENDED_MIN_VERSION_MARIA_DB_106

homeassistant.components.recorder.util.RECOMMENDED_MIN_VERSION_MARIA_DB_106

Definition at line 89 of file util.py.

◆ RECOMMENDED_MIN_VERSION_MARIA_DB_107

homeassistant.components.recorder.util.RECOMMENDED_MIN_VERSION_MARIA_DB_107

Definition at line 91 of file util.py.

◆ RECOMMENDED_MIN_VERSION_MARIA_DB_108

homeassistant.components.recorder.util.RECOMMENDED_MIN_VERSION_MARIA_DB_108

Definition at line 94 of file util.py.

◆ RETRIES

homeassistant.components.recorder.util.RETRIES

Definition at line 68 of file util.py.

◆ RETRYABLE_MYSQL_ERRORS

homeassistant.components.recorder.util.RETRYABLE_MYSQL_ERRORS

Definition at line 109 of file util.py.

◆ SQLITE3_POSTFIXES

homeassistant.components.recorder.util.SQLITE3_POSTFIXES

Definition at line 70 of file util.py.

◆ SUNDAY_WEEKDAY

homeassistant.components.recorder.util.SUNDAY_WEEKDAY

Definition at line 115 of file util.py.

◆ UPCOMING_MIN_VERSION_SQLITE

homeassistant.components.recorder.util.UPCOMING_MIN_VERSION_SQLITE

Definition at line 99 of file util.py.

Variables
	_LOGGER

	DAYS_IN_WEEK

	DEFAULT_YIELD_STATES_ROWS

	FIRST_POSSIBLE_SUNDAY

	MARIA_DB_106

	MARIA_DB_107

	MARIA_DB_108

	MARIADB_WITH_FIXED_IN_QUERIES_105

	MARIADB_WITH_FIXED_IN_QUERIES_106

	MARIADB_WITH_FIXED_IN_QUERIES_107

	MARIADB_WITH_FIXED_IN_QUERIES_108

	MAX_RESTART_TIME

	MIN_VERSION_MARIA_DB

	MIN_VERSION_MYSQL

	MIN_VERSION_PGSQL

	MIN_VERSION_SQLITE

	MIN_VERSION_SQLITE_MODERN_BIND_VARS

	minutes

	PERIOD_SCHEMA

	QUERY_RETRY_WAIT

	RECOMMENDED_MIN_VERSION_MARIA_DB

	RECOMMENDED_MIN_VERSION_MARIA_DB_106

	RECOMMENDED_MIN_VERSION_MARIA_DB_107

	RECOMMENDED_MIN_VERSION_MARIA_DB_108

	RETRIES

	RETRYABLE_MYSQL_ERRORS

	SQLITE3_POSTFIXES

	SUNDAY_WEEKDAY

	UPCOMING_MIN_VERSION_SQLITE

Home Assistant Unofficial Reference 2024.12.1

Functions

Variables

Detailed Description

Function Documentation

◆ _async_create_issue_deprecated_version()

◆ _async_create_mariadb_range_index_regression_issue()

◆ _async_delete_issue_deprecated_version()

◆ _datetime_or_none()

◆ _extract_version_from_server_response()

◆ _extract_version_from_server_response_or_raise()

◆ _fail_unsupported_dialect()

◆ _is_retryable_error()

◆ _P() [1/2]

◆ _P() [2/2]

◆ _R() [1/2]

◆ _R() [2/2]

◆ _raise_if_version_unsupported()

◆ _simple_version()

◆ async_create_backup_failure_issue()

◆ async_migration_in_progress()

◆ async_migration_is_live()

◆ basic_sanity_check()

◆ build_mysqldb_conv()

◆ dburl_to_path()

◆ end_incomplete_runs()

◆ execute()

◆ execute_on_connection()

◆ execute_stmt_lambda_element()

◆ filter_unique_constraint_integrity_error()

◆ get_index_by_name()

◆ is_second_sunday()

◆ last_run_was_recently_clean()

◆ move_away_broken_database()

◆ periodic_db_cleanups()

◆ query_on_connection()

◆ resolve_period()

◆ run_checks_on_open_db()

◆ second_sunday()

◆ setup_connection_for_dialect()

◆ validate_or_move_away_sqlite_database()

◆ validate_sqlite_database()

◆ write_lock_db_sqlite()

Variable Documentation

◆ _LOGGER

◆ DAYS_IN_WEEK

◆ DEFAULT_YIELD_STATES_ROWS

◆ FIRST_POSSIBLE_SUNDAY

◆ MARIA_DB_106

◆ MARIA_DB_107

◆ MARIA_DB_108

◆ MARIADB_WITH_FIXED_IN_QUERIES_105

◆ MARIADB_WITH_FIXED_IN_QUERIES_106

◆ MARIADB_WITH_FIXED_IN_QUERIES_107

◆ MARIADB_WITH_FIXED_IN_QUERIES_108

◆ MAX_RESTART_TIME

◆ MIN_VERSION_MARIA_DB

◆ MIN_VERSION_MYSQL

◆ MIN_VERSION_PGSQL

◆ MIN_VERSION_SQLITE

◆ MIN_VERSION_SQLITE_MODERN_BIND_VARS

◆ minutes

◆ PERIOD_SCHEMA

◆ QUERY_RETRY_WAIT

◆ RECOMMENDED_MIN_VERSION_MARIA_DB

◆ RECOMMENDED_MIN_VERSION_MARIA_DB_106

◆ RECOMMENDED_MIN_VERSION_MARIA_DB_107

◆ RECOMMENDED_MIN_VERSION_MARIA_DB_108

◆ RETRIES

◆ RETRYABLE_MYSQL_ERRORS

◆ SQLITE3_POSTFIXES

◆ SUNDAY_WEEKDAY

◆ UPCOMING_MIN_VERSION_SQLITE