diff --git a/CHANGES.txt b/CHANGES.txt index cf5463bf..04889d1b 100644 --- a/CHANGES.txt +++ b/CHANGES.txt @@ -11,7 +11,7 @@ Unreleased - SQLAlchemy DDL: Allow setting ``server_default`` on columns to enable server-generated defaults. Thanks, @JanLikar. -- Allow handling "aware" datetime values with time zone info when inserting or updating. +- Allow handling datetime values tagged with time zone info when inserting or updating. 2023/04/18 0.31.1 diff --git a/docs/by-example/client.rst b/docs/by-example/client.rst index e32e4bbc..e053d73f 100644 --- a/docs/by-example/client.rst +++ b/docs/by-example/client.rst @@ -142,8 +142,9 @@ Refresh locations: Updating Data ============= -Both when inserting or updating data, values for ``TIMESTAMP`` columns can be obtained -in different formats. Both literal strings and datetime objects are supported. +Values for ``TIMESTAMP`` columns can be obtained as a string literal, ``date``, +or ``datetime`` object. If it contains timezone information, it is converted to +UTC, and the timezone information is discarded. >>> import datetime as dt >>> timestamp_full = "2023-06-26T09:24:00.123+02:00" diff --git a/docs/data-types.rst b/docs/data-types.rst index 1f1a10d3..acad570c 100644 --- a/docs/data-types.rst +++ b/docs/data-types.rst @@ -99,13 +99,14 @@ __ https://crate.io/docs/crate/reference/en/latest/general/ddl/data-types.html#c .. NOTE:: - Values of ``TIMESTAMP`` columns will always be stored using a ``LONG`` type, - representing the `Unix time`_ (epoch) timestamp, i.e. number of seconds which - have passed since 00:00:00 UTC on Thursday, 1 January 1970. + When using ``date`` or ``datetime`` objects with ``timezone`` information, + the value is implicitly converted to a `Unix time`_ (epoch) timestamp, i.e. + the number of seconds which have passed since 00:00:00 UTC on + Thursday, 1 January 1970. This means, when inserting or updating records using timezone-aware Python - ``datetime`` objects, timezone information will not be preserved. If you - need to store it, you will need to use a separate column. + ``date`` or ``datetime`` objects, timezone information will not be + preserved. If you need to store it, you will need to use a separate column. .. _data-types-sqlalchemy: