diff --git a/docs/migrations.md b/docs/migrations.md index 5a39e065..db1b5217 100644 --- a/docs/migrations.md +++ b/docs/migrations.md @@ -217,6 +217,34 @@ Redis OM includes a built-in migration for datetime field indexing improvements. For detailed information about this migration, see the **[0.x to 1.0 Migration Guide](migration_guide_0x_to_1x.md#datetime-migration-details)**. +### Datetime Timezone Normalization in 1.1.0 + +Redis OM Python 1.1.0 tightens timestamp handling for both `datetime.datetime` and `datetime.date` fields: + +- `datetime.datetime` values are read back as **UTC-aware** `datetime` values. +- `datetime.date` values are stored as **midnight UTC** instead of local-midnight timestamps. + +This is usually what you want, but it matters if you already have data written by versions before 1.1.0: + +- Older `datetime.datetime` records still represent the same instant in time, but code that expected naive `datetime` values may need to handle UTC-aware values. +- Older `datetime.date` records written in a **non-UTC** environment may load as a different calendar day after upgrading, and equality queries may stop matching those records. + +If you have existing `datetime.date` data from a release before 1.1.0 and your application was not running in UTC, plan to migrate or re-save that data after upgrading. + +Example symptom after upgrade: + +- Stored before 1.1.0 in `Asia/Karachi`: `date(2023, 1, 1)` -> `1672513200` (local midnight) +- Stored in 1.1.0+: `date(2023, 1, 1)` -> `1672531200` (midnight UTC) + +If your application relies on date equality queries, verify old records after upgrading: + +```bash +# Spot-check records after upgrading +om migrate-data status +``` + +If needed, create a custom data migration to normalize affected `datetime.date` fields by re-saving them with Redis OM 1.1.0+. + ## Advanced Usage ### Module-Based Migrations diff --git a/docs/release_notes_1.1.md b/docs/release_notes_1.1.md new file mode 100644 index 00000000..11f17c04 --- /dev/null +++ b/docs/release_notes_1.1.md @@ -0,0 +1,19 @@ +# Redis OM Python 1.1 Release Notes + +Redis OM Python 1.1 focuses on compatibility updates and timestamp normalization fixes. + +## Notable Changes + +- RedisVL dependency updated to allow newer Python versions +- `datetime.datetime` values now round-trip as UTC-aware `datetime` values +- `datetime.date` values now store as midnight UTC instead of local-midnight timestamps + +## Timestamp Upgrade Note + +The timestamp normalization change is important if you already have data written by earlier releases: + +- Existing `datetime.datetime` records still represent the same instant in time, but code that expected naive `datetime` values may need to handle UTC-aware values. +- Existing `datetime.date` records written in a non-UTC environment may load as a different calendar day after upgrading. +- Date equality queries may stop matching those older records until the data is re-saved or migrated. + +For migration guidance, see [Migrations: Datetime Timezone Normalization in 1.1.0](migrations.md#datetime-timezone-normalization-in-110). diff --git a/mkdocs.yml b/mkdocs.yml index 8ce85fa2..1a2f355b 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -72,6 +72,7 @@ nav: - Reference: - Errors: errors.md - Release Notes 1.0: release_notes_1.0.md + - Release Notes 1.1: release_notes_1.1.md - Upgrade Guide (0.x → 1.x): migration_guide_0x_to_1x.md plugins: @@ -105,4 +106,3 @@ extra_css: copyright: | © 2024 Redis -