BREAKING CHANGE: Nanosecond timestamp support

[kafka1991]

Overview

This PR introduces nanosecond support.

Whenever protocol version 2 is enabled (explicitly, or as automatically as possible over the HTTP protocol) the sender will respect the timestamp precision as specified via the API.

Nanosecond precision is available for QuestDB 9.1.0 and newer.

What remains the same.

• There are no API changes.
• The protocol_version=1 behaviour remains unchanged.

What's changed

New protocol_version=2 behaviour

If protocol_version>=2, for both all timestamp columns:

• If you add a TimestampMicros timestamp, it will be sent to the server as micros.
• If you add a TimestampNanos timestamp, it will be sent to the server as nanos.
• If you add a datetime.datetime object it will be sent down as microseconds (since this is the maximum precision supported by the Python library).
• If you use Pandas dataframes with datetime64[ns] timestamp columns, these will be sent to the server as nanos.

When writing to QuestDB 9.1.1 or newer and no schema already exists, the server will auto-create any missing timestamp columns using the TIMESTAMP (micros) or TIMESTAMP_NS (nanos) column type matching the client's sent precision.

QuestDB 9.1.0 instead will always auto-create TIMESTAMP (micros) columns, unless you explicitly configure line.timestamp.default.column.type=TIMESTAMP_NS in server.conf.

Retained protocol_version=1 behaviour

The protocol_version==1 behaviour is retained as before this release:

• Both micros and nanos APIs send as nanos to the server when adding the designated timestamp.
  • By default, for backwards-compatibility, the server will continue to store the data as micros, unless the table was pre-created via SQL.
• Both micros and nanos APIs send as micros to the server when adding any other column timestamps.

Existing schema continues to override

Just as always, if you create a table's schema via a SQL CREATE TABLE command, the server will convert the timestamps to the schema-specified precision. This will happen regardless of the protocol version used by the client.

Practical upgrading advice

• When upgrading the sender, there are no API changes.
• This is a breaking change only if you rely on table or column auto-creation. We encourage you to review your own API usage if you rely on this feature and double-check you're happy with the resulting timestamp precisions.
• The TIMESTAMP_NS datatype and nanosecond precision timestamps are available from QuestDB 9.1.0, with improved handling in QuestDB 9.1.1 and later.
• Older QuestDB versions which do not support the TIMESTAMP_NS column type will continue to use the TIMESTAMP column type. This change does not break compatibility with these older releases.

[amunra]

Tandem PRs:

• feat: nanosecond timestamp support c-questdb-client#118
• BREAKING CHANGE: designated and non-designated timestamp feature parity for micros and nanos c-questdb-client#121