Home Assistant Unofficial Reference 2024.12.1
homeassistant.components.recorder.migration Namespace Reference

Classes

class  _ColumnTypesForDialect
 
class  _SchemaVersion10Migrator
 
class  _SchemaVersion11Migrator
 
class  _SchemaVersion12Migrator
 
class  _SchemaVersion13Migrator
 
class  _SchemaVersion14Migrator
 
class  _SchemaVersion15Migrator
 
class  _SchemaVersion16Migrator
 
class  _SchemaVersion17Migrator
 
class  _SchemaVersion18Migrator
 
class  _SchemaVersion19Migrator
 
class  _SchemaVersion1Migrator
 
class  _SchemaVersion20Migrator
 
class  _SchemaVersion21Migrator
 
class  _SchemaVersion22Migrator
 
class  _SchemaVersion23Migrator
 
class  _SchemaVersion24Migrator
 
class  _SchemaVersion25Migrator
 
class  _SchemaVersion26Migrator
 
class  _SchemaVersion27Migrator
 
class  _SchemaVersion28Migrator
 
class  _SchemaVersion29Migrator
 
class  _SchemaVersion2Migrator
 
class  _SchemaVersion30Migrator
 
class  _SchemaVersion31Migrator
 
class  _SchemaVersion32Migrator
 
class  _SchemaVersion33Migrator
 
class  _SchemaVersion34Migrator
 
class  _SchemaVersion35Migrator
 
class  _SchemaVersion36Migrator
 
class  _SchemaVersion37Migrator
 
class  _SchemaVersion38Migrator
 
class  _SchemaVersion39Migrator
 
class  _SchemaVersion3Migrator
 
class  _SchemaVersion40Migrator
 
class  _SchemaVersion41Migrator
 
class  _SchemaVersion42Migrator
 
class  _SchemaVersion43Migrator
 
class  _SchemaVersion44Migrator
 
class  _SchemaVersion45Migrator
 
class  _SchemaVersion46Migrator
 
class  _SchemaVersion47Migrator
 
class  _SchemaVersion4Migrator
 
class  _SchemaVersion5Migrator
 
class  _SchemaVersion6Migrator
 
class  _SchemaVersion7Migrator
 
class  _SchemaVersion8Migrator
 
class  _SchemaVersion9Migrator
 
class  _SchemaVersionMigrator
 
class  BaseMigration
 
class  BaseMigrationWithQuery
 
class  BaseOffLineMigration
 
class  BaseRunTimeMigration
 
class  CommitBeforeMigrationTask
 
class  DataMigrationStatus
 
class  EntityIDMigration
 
class  EntityIDPostMigration
 
class  EventIDPostMigration
 
class  EventsContextIDMigration
 
class  EventTypeIDMigration
 
class  MigrationTask
 
class  SchemaValidationStatus
 
class  StatesContextIDMigration
 

Functions

None _add_columns (Callable[[], Session] session_maker, str table_name, list[str] columns_def)
 
None _add_constraint (Callable[[], Session] session_maker, AddConstraint add_constraint, str table, str column)
 
None _apply_update (Recorder instance, HomeAssistant hass, Engine engine, Callable[[], Session] session_maker, int new_version, int old_version)
 
bytes|None _context_id_to_bytes (str|None context_id)
 
None _correct_table_character_set_and_collation (str table, Callable[[], Session] session_maker)
 
None _create_index (Callable[[], Session] session_maker, str table_name, str index_name)
 
None _delete_foreign_key_violations (Callable[[], Session] session_maker, Engine engine, str table, str column, str foreign_table, str foreign_column)
 
None _drop_foreign_key_constraints (Callable[[], Session] session_maker, Engine engine, str table, str column)
 
None _drop_index (Callable[[], Session] session_maker, str table_name, str index_name, bool|None quiet=None)
 
bool _execute_or_collect_error (Callable[[], Session] session_maker, str query, list[str] errors)
 
set[str] _find_schema_errors (HomeAssistant hass, Recorder instance, Callable[[], Session] session_maker)
 
bytes _generate_ulid_bytes_at_time (float|None timestamp)
 
dict[str, int] _get_migration_changes (Session session)
 
int|None _get_schema_version (Session session)
 
bool _initialize_database (Session session)
 
None _mark_migration_done (Session session, type[BaseMigration] migration)
 
None _migrate_columns_to_timestamp (Recorder instance, Callable[[], Session] session_maker, Engine engine)
 
SchemaValidationStatus _migrate_schema (Recorder instance, HomeAssistant hass, Engine engine, Callable[[], Session] session_maker, SchemaValidationStatus schema_status, int end_version)
 
None _migrate_statistics_columns_to_timestamp (Recorder instance, Callable[[], Session] session_maker, Engine engine)
 
None _migrate_statistics_columns_to_timestamp_one_by_one (Recorder instance, Callable[[], Session] session_maker)
 
None _migrate_statistics_columns_to_timestamp_removing_duplicates (HomeAssistant hass, Recorder instance, Callable[[], Session] session_maker, Engine engine)
 
None _modify_columns (Callable[[], Session] session_maker, Engine engine, str table_name, list[str] columns_def)
 
None _restore_foreign_key_constraints (Callable[[], Session] session_maker, Engine engine, list[tuple[str, str, str|None, str|None]] foreign_columns)
 
bool _schema_is_current (int current_version)
 
None _update_states_table_with_foreign_key_options (Callable[[], Session] session_maker, Engine engine)
 
None _wipe_old_string_time_columns (Recorder instance, Engine engine, Session session)
 
int|None get_schema_version (Callable[[], Session] session_maker)
 
bool initialize_database (Callable[[], Session] session_maker)
 
bool live_migration (SchemaValidationStatus schema_status)
 
None migrate_data_live (Recorder instance, Callable[[], Session] session_maker, SchemaValidationStatus schema_status)
 
None migrate_data_non_live (Recorder instance, Callable[[], Session] session_maker, SchemaValidationStatus schema_status)
 
SchemaValidationStatus migrate_schema_live (Recorder instance, HomeAssistant hass, Engine engine, Callable[[], Session] session_maker, SchemaValidationStatus schema_status)
 
SchemaValidationStatus migrate_schema_non_live (Recorder instance, HomeAssistant hass, Engine engine, Callable[[], Session] session_maker, SchemaValidationStatus schema_status)
 
bool non_live_data_migration_needed (Recorder instance, Callable[[], Session] session_maker, int schema_version)
 
bool post_migrate_entity_ids (Recorder instance)
 
None pre_migrate_schema (Engine engine)
 
None raise_if_exception_missing_str (Exception ex, Iterable[str] match_substrs)
 
bool rebuild_sqlite_table (Callable[[], Session] session_maker, Engine engine, type[Base] table)
 
SchemaValidationStatus|None validate_db_schema (HomeAssistant hass, Recorder instance, Callable[[], Session] session_maker)
 

Variables

string _EMPTY_ENTITY_ID = "missing.entity_id"
 
string _EMPTY_EVENT_TYPE = "missing_event_type"
 
 _LOGGER = logging.getLogger(__name__)
 
 _MYSQL_COLUMN_TYPES
 
 _POSTGRESQL_COLUMN_TYPES
 
 _SQLITE_COLUMN_TYPES
 
tuple FOREIGN_COLUMNS
 
tuple LIVE_DATA_MIGRATORS
 
int LIVE_MIGRATION_MIN_SCHEMA_VERSION = 42
 
tuple MIGRATION_NOTE_MINUTES
 
tuple MIGRATION_NOTE_OFFLINE
 
string MIGRATION_NOTE_WHILE = "This will take a while; please be patient!"
 
tuple NON_LIVE_DATA_MIGRATORS
 

Detailed Description

Schema migration helpers.

Function Documentation

◆ _add_columns()

None homeassistant.components.recorder.migration._add_columns ( Callable[[], Session]  session_maker,
str  table_name,
list[str]   columns_def 
)
private
Add columns to a table.

Definition at line 540 of file migration.py.

◆ _add_constraint()

None homeassistant.components.recorder.migration._add_constraint ( Callable[[], Session]  session_maker,
AddConstraint  add_constraint,
str  table,
str  column 
)
private
Add a foreign key constraint.

Definition at line 790 of file migration.py.

◆ _apply_update()

None homeassistant.components.recorder.migration._apply_update ( Recorder  instance,
HomeAssistant  hass,
Engine  engine,
Callable[[], Session]  session_maker,
int  new_version,
int  old_version 
)
private
Perform operations to bring schema up to date.

Definition at line 927 of file migration.py.

◆ _context_id_to_bytes()

bytes | None homeassistant.components.recorder.migration._context_id_to_bytes ( str | None  context_id)
private
Convert a context_id to bytes.

Definition at line 2166 of file migration.py.

◆ _correct_table_character_set_and_collation()

None homeassistant.components.recorder.migration._correct_table_character_set_and_collation ( str  table,
Callable[[], Session]  session_maker 
)
private
Correct issues detected by validate_db_schema.

Definition at line 1873 of file migration.py.

◆ _create_index()

None homeassistant.components.recorder.migration._create_index ( Callable[[], Session]  session_maker,
str  table_name,
str   index_name 
)
private
Create an index for the specified table.

The index name should match the name given for the index
within the table definition described in the models

Definition at line 430 of file migration.py.

◆ _delete_foreign_key_violations()

None homeassistant.components.recorder.migration._delete_foreign_key_violations ( Callable[[], Session]  session_maker,
Engine  engine,
str  table,
str  column,
str  foreign_table,
str  foreign_column 
)
private
Remove rows which violate the constraints.

Definition at line 813 of file migration.py.

◆ _drop_foreign_key_constraints()

None homeassistant.components.recorder.migration._drop_foreign_key_constraints ( Callable[[], Session]  session_maker,
Engine  engine,
str  table,
str   column 
)
private
Drop foreign key constraints for a table on specific columns.

This is not supported for SQLite because it does not support
dropping constraints.

Definition at line 699 of file migration.py.

◆ _drop_index()

None homeassistant.components.recorder.migration._drop_index ( Callable[[], Session]  session_maker,
str  table_name,
str  index_name,
bool | None   quiet = None 
)
private
Drop an index from a specified table.

There is no universal way to do something like `DROP INDEX IF EXISTS`
so we will simply execute the DROP command and ignore any exceptions

WARNING: Due to some engines (MySQL at least) being unable to use bind
parameters in a DROP INDEX statement (at least via SQLAlchemy), the query
string here is generated from the method parameters without sanitizing.
DO NOT USE THIS FUNCTION IN ANY OPERATION THAT TAKES USER INPUT.

Definition at line 479 of file migration.py.

◆ _execute_or_collect_error()

bool homeassistant.components.recorder.migration._execute_or_collect_error ( Callable[[], Session]  session_maker,
str  query,
list[str]   errors 
)
private
Execute a query or collect an error.

Definition at line 466 of file migration.py.

◆ _find_schema_errors()

set[str] homeassistant.components.recorder.migration._find_schema_errors ( HomeAssistant  hass,
Recorder  instance,
Callable[[], Session]   session_maker 
)
private
Find schema errors.

Definition at line 253 of file migration.py.

◆ _generate_ulid_bytes_at_time()

bytes homeassistant.components.recorder.migration._generate_ulid_bytes_at_time ( float | None  timestamp)
private
Generate a ulid with a specific timestamp.

Definition at line 2182 of file migration.py.

◆ _get_migration_changes()

dict[str, int] homeassistant.components.recorder.migration._get_migration_changes ( Session  session)
private
Return migration changes as a dict.

Definition at line 368 of file migration.py.

◆ _get_schema_version()

int | None homeassistant.components.recorder.migration._get_schema_version ( Session  session)
private
Get the schema version.

Definition at line 183 of file migration.py.

◆ _initialize_database()

bool homeassistant.components.recorder.migration._initialize_database ( Session  session)
private
Initialize a new database.

The function determines the schema version by inspecting the db structure.

When the schema version is not present in the db, either db was just
created with the correct schema, or this is a db created before schema
versions were tracked. For now, we'll test if the changes for schema
version 1 are present to make the determination. Eventually this logic
can be removed and we can assume a new db is being created.

Definition at line 2205 of file migration.py.

◆ _mark_migration_done()

None homeassistant.components.recorder.migration._mark_migration_done ( Session  session,
type[BaseMigration migration 
)
private
Mark a migration as done in the database.

Definition at line 2773 of file migration.py.

◆ _migrate_columns_to_timestamp()

None homeassistant.components.recorder.migration._migrate_columns_to_timestamp ( Recorder  instance,
Callable[[], Session]  session_maker,
Engine   engine 
)
private
Migrate columns to use timestamp.

Definition at line 1956 of file migration.py.

◆ _migrate_schema()

SchemaValidationStatus homeassistant.components.recorder.migration._migrate_schema ( Recorder  instance,
HomeAssistant  hass,
Engine  engine,
Callable[[], Session]  session_maker,
SchemaValidationStatus  schema_status,
int  end_version 
)
private
Check if the schema needs to be upgraded.

Definition at line 289 of file migration.py.

◆ _migrate_statistics_columns_to_timestamp()

None homeassistant.components.recorder.migration._migrate_statistics_columns_to_timestamp ( Recorder  instance,
Callable[[], Session]  session_maker,
Engine   engine 
)
private
Migrate statistics columns to use timestamp.

Definition at line 2098 of file migration.py.

◆ _migrate_statistics_columns_to_timestamp_one_by_one()

None homeassistant.components.recorder.migration._migrate_statistics_columns_to_timestamp_one_by_one ( Recorder  instance,
Callable[[], Session]   session_maker 
)
private
Migrate statistics columns to use timestamp on by one.

If something manually inserted data into the statistics table
in the past it may have inserted duplicate rows.

Before we had the unique index on (statistic_id, start) this
the data could have been inserted without any errors and we
could end up with duplicate rows that go undetected (even by
our current duplicate cleanup code) until we try to migrate the
data to use timestamps.

This will migrate the data one by one to ensure we do not hit any
duplicate rows, and remove the duplicate rows as they are found.

Definition at line 2045 of file migration.py.

◆ _migrate_statistics_columns_to_timestamp_removing_duplicates()

None homeassistant.components.recorder.migration._migrate_statistics_columns_to_timestamp_removing_duplicates ( HomeAssistant  hass,
Recorder  instance,
Callable[[], Session]  session_maker,
Engine  engine 
)
private
Migrate statistics columns to timestamp or cleanup duplicates.

Definition at line 1838 of file migration.py.

◆ _modify_columns()

None homeassistant.components.recorder.migration._modify_columns ( Callable[[], Session]  session_maker,
Engine  engine,
str  table_name,
list[str]  columns_def 
)
private
Modify columns in a table.

Definition at line 580 of file migration.py.

◆ _restore_foreign_key_constraints()

None homeassistant.components.recorder.migration._restore_foreign_key_constraints ( Callable[[], Session]  session_maker,
Engine  engine,
list[tuple[str, str, str | None, str | None]]  foreign_columns 
)
private
Restore foreign key constraints.

Definition at line 737 of file migration.py.

◆ _schema_is_current()

bool homeassistant.components.recorder.migration._schema_is_current ( int  current_version)
private
Check if the schema is current.

Definition at line 214 of file migration.py.

◆ _update_states_table_with_foreign_key_options()

None homeassistant.components.recorder.migration._update_states_table_with_foreign_key_options ( Callable[[], Session]  session_maker,
Engine   engine 
)
private
Add the options to foreign key constraints.

This is not supported for SQLite because it does not support
dropping constraints.

Definition at line 639 of file migration.py.

◆ _wipe_old_string_time_columns()

None homeassistant.components.recorder.migration._wipe_old_string_time_columns ( Recorder  instance,
Engine  engine,
Session   session 
)
private
Wipe old string time columns to save space.

Definition at line 1901 of file migration.py.

◆ get_schema_version()

int | None homeassistant.components.recorder.migration.get_schema_version ( Callable[[], Session]  session_maker)
Get the schema version.

Definition at line 193 of file migration.py.

◆ initialize_database()

bool homeassistant.components.recorder.migration.initialize_database ( Callable[[], Session]  session_maker)
Initialize a new database.

Definition at line 2232 of file migration.py.

◆ live_migration()

bool homeassistant.components.recorder.migration.live_migration ( SchemaValidationStatus  schema_status)
Check if live migration is possible.

Definition at line 264 of file migration.py.

◆ migrate_data_live()

None homeassistant.components.recorder.migration.migrate_data_live ( Recorder  instance,
Callable[[], Session]  session_maker,
SchemaValidationStatus  schema_status 
)
Queue live schema migration tasks.

This must be called after live schema migration is completed.

Definition at line 413 of file migration.py.

◆ migrate_data_non_live()

None homeassistant.components.recorder.migration.migrate_data_non_live ( Recorder  instance,
Callable[[], Session]  session_maker,
SchemaValidationStatus  schema_status 
)
Do non-live data migration.

This must be called after non-live schema migration is completed.

Definition at line 396 of file migration.py.

◆ migrate_schema_live()

SchemaValidationStatus homeassistant.components.recorder.migration.migrate_schema_live ( Recorder  instance,
HomeAssistant  hass,
Engine  engine,
Callable[[], Session]  session_maker,
SchemaValidationStatus  schema_status 
)
Check if the schema needs to be upgraded.

Definition at line 342 of file migration.py.

◆ migrate_schema_non_live()

SchemaValidationStatus homeassistant.components.recorder.migration.migrate_schema_non_live ( Recorder  instance,
HomeAssistant  hass,
Engine  engine,
Callable[[], Session]  session_maker,
SchemaValidationStatus  schema_status 
)
Check if the schema needs to be upgraded.

Definition at line 328 of file migration.py.

◆ non_live_data_migration_needed()

bool homeassistant.components.recorder.migration.non_live_data_migration_needed ( Recorder  instance,
Callable[[], Session]  session_maker,
int  schema_version 
)
Return True if non-live data migration is needed.

This must only be called if database schema is current.

Definition at line 377 of file migration.py.

◆ post_migrate_entity_ids()

bool homeassistant.components.recorder.migration.post_migrate_entity_ids ( Recorder  instance)
Remove old entity_id strings from states.

We cannot do this in migrate_entity_ids since the history queries
still need to work while the migration is in progress.

Definition at line 2187 of file migration.py.

◆ pre_migrate_schema()

None homeassistant.components.recorder.migration.pre_migrate_schema ( Engine  engine)
Prepare for migration.

This function is called before calling Base.metadata.create_all.

Definition at line 272 of file migration.py.

◆ raise_if_exception_missing_str()

None homeassistant.components.recorder.migration.raise_if_exception_missing_str ( Exception  ex,
Iterable[str]  match_substrs 
)
Raise if the exception and cause do not contain the match substrs.

Definition at line 172 of file migration.py.

◆ rebuild_sqlite_table()

bool homeassistant.components.recorder.migration.rebuild_sqlite_table ( Callable[[], Session]  session_maker,
Engine  engine,
type[Base]   table 
)
Rebuild an SQLite table.

This must only be called after all migrations are complete
and the database is in a consistent state.

If the table is not migrated to the current schema this
will likely fail.

Definition at line 2782 of file migration.py.

◆ validate_db_schema()

SchemaValidationStatus | None homeassistant.components.recorder.migration.validate_db_schema ( HomeAssistant  hass,
Recorder  instance,
Callable[[], Session]   session_maker 
)
Check if the schema is valid.

This checks that the schema is the current version as well as for some common schema
errors caused by manual migration between database engines, for example importing an
SQLite database to MariaDB.

Definition at line 219 of file migration.py.

Variable Documentation

◆ _EMPTY_ENTITY_ID

string homeassistant.components.recorder.migration._EMPTY_ENTITY_ID = "missing.entity_id"
private

Definition at line 134 of file migration.py.

◆ _EMPTY_EVENT_TYPE

string homeassistant.components.recorder.migration._EMPTY_EVENT_TYPE = "missing_event_type"
private

Definition at line 135 of file migration.py.

◆ _LOGGER

homeassistant.components.recorder.migration._LOGGER = logging.getLogger(__name__)
private

Definition at line 137 of file migration.py.

◆ _MYSQL_COLUMN_TYPES

homeassistant.components.recorder.migration._MYSQL_COLUMN_TYPES
private
Initial value:
1 = _ColumnTypesForDialect(
2  big_int_type="INTEGER(20)",
3  timestamp_type=DOUBLE_PRECISION_TYPE_SQL,
4  context_bin_type=f"BLOB({CONTEXT_ID_BIN_MAX_LENGTH})",
5 )

Definition at line 147 of file migration.py.

◆ _POSTGRESQL_COLUMN_TYPES

homeassistant.components.recorder.migration._POSTGRESQL_COLUMN_TYPES
private
Initial value:
1 = _ColumnTypesForDialect(
2  big_int_type="INTEGER",
3  timestamp_type=DOUBLE_PRECISION_TYPE_SQL,
4  context_bin_type="BYTEA",
5 )

Definition at line 153 of file migration.py.

◆ _SQLITE_COLUMN_TYPES

homeassistant.components.recorder.migration._SQLITE_COLUMN_TYPES
private
Initial value:
1 = _ColumnTypesForDialect(
2  big_int_type="INTEGER",
3  timestamp_type="FLOAT",
4  context_bin_type="BLOB",
5 )

Definition at line 159 of file migration.py.

◆ FOREIGN_COLUMNS

tuple homeassistant.components.recorder.migration.FOREIGN_COLUMNS
Initial value:
1 = (
2  (
3  "events",
4  ("data_id", "event_type_id"),
5  (
6  ("data_id", "event_data", "data_id"),
7  ("event_type_id", "event_types", "event_type_id"),
8  ),
9  ),
10  (
11  "states",
12  ("event_id", "old_state_id", "attributes_id", "metadata_id"),
13  (
14  ("event_id", None, None),
15  ("old_state_id", "states", "state_id"),
16  ("attributes_id", "state_attributes", "attributes_id"),
17  ("metadata_id", "states_meta", "metadata_id"),
18  ),
19  ),
20  (
21  "statistics",
22  ("metadata_id",),
23  (("metadata_id", "statistics_meta", "id"),),
24  ),
25  (
26  "statistics_short_term",
27  ("metadata_id",),
28  (("metadata_id", "statistics_meta", "id"),),
29  ),
30 )

Definition at line 1736 of file migration.py.

◆ LIVE_DATA_MIGRATORS

tuple homeassistant.components.recorder.migration.LIVE_DATA_MIGRATORS
Initial value:
1 = (
2  EventTypeIDMigration,
3  EntityIDMigration,
4  EventIDPostMigration,
5 )

Definition at line 2766 of file migration.py.

◆ LIVE_MIGRATION_MIN_SCHEMA_VERSION

int homeassistant.components.recorder.migration.LIVE_MIGRATION_MIN_SCHEMA_VERSION = 42

Definition at line 121 of file migration.py.

◆ MIGRATION_NOTE_MINUTES

tuple homeassistant.components.recorder.migration.MIGRATION_NOTE_MINUTES
Initial value:
1 = (
2  "Note: this may take several minutes on large databases and slow machines. "
3  "Please be patient!"
4 )

Definition at line 128 of file migration.py.

◆ MIGRATION_NOTE_OFFLINE

tuple homeassistant.components.recorder.migration.MIGRATION_NOTE_OFFLINE
Initial value:
1 = (
2  "Note: this may take several hours on large databases and slow machines. "
3  "Home Assistant will not start until the upgrade is completed. Please be patient "
4  "and do not turn off or restart Home Assistant while the upgrade is in progress!"
5 )

Definition at line 123 of file migration.py.

◆ MIGRATION_NOTE_WHILE

string homeassistant.components.recorder.migration.MIGRATION_NOTE_WHILE = "This will take a while; please be patient!"

Definition at line 132 of file migration.py.

◆ NON_LIVE_DATA_MIGRATORS

tuple homeassistant.components.recorder.migration.NON_LIVE_DATA_MIGRATORS
Initial value:
1 = (
2  StatesContextIDMigration, # Introduced in HA Core 2023.4
3  EventsContextIDMigration, # Introduced in HA Core 2023.4
4 )

Definition at line 2761 of file migration.py.