Bump version: 1.2.0 → 2.0.0 (#65)

questdb · Mar 19, 2024 · 8e4b407 · 8e4b407
1 parent d26da90
commit 8e4b407
Show file tree

Hide file tree

Showing 13 changed files with 297 additions and 53 deletions.
diff --git a/.bumpversion.cfg b/.bumpversion.cfg
@@ -1,5 +1,5 @@
 [bumpversion]
-current_version = 1.2.0
+current_version = 2.0.0
 commit = True
 tag = False
 

diff --git a/CHANGELOG.rst b/CHANGELOG.rst
@@ -2,6 +2,171 @@
 Changelog
 =========
 
+2.0.0 (2024-03-19)
+------------------
+
+This is a major release with new features and breaking changes.
+
+Features
+~~~~~~~~
+
+* Support for ILP over HTTP. The sender can now send data to QuestDB via HTTP
+  instead of TCP. This provides error feedback from the server and new features.
+
+  .. code-block:: python
+
+    conf = 'http::addr=localhost:9000;'
+    with Sender.from_conf(conf) as sender:
+        sender.row(...)
+        sender.dataframe(...)
+
+        # Will raise `IngressError` if there is an error from the server.
+        sender.flush()
+
+* New configuration string construction. The sender can now be also constructed
+  from a :ref:`configuration string <sender_conf>` in addition to the
+  constructor arguments.
+  This allows for more flexible configuration and is the recommended way to
+  construct a sender.
+  The same string can also be loaded from the ``QDB_CLIENT_CONF`` environment
+  variable.
+  The constructor arguments have been updated and some options have changed.
+
+* Explicit transaction support over HTTP. A set of rows for a single table can
+  now be committed via the sender transactionally. You can do this using a
+  ``with sender.transaction('table_name') as txn:`` block.
+
+  .. code-block:: python
+
+    conf = 'http::addr=localhost:9000;'
+    with Sender.from_conf(conf) as sender:
+        with sender.transaction('test_table') as txn:
+            # Same arguments as the sender methods, minus the table name.
+            txn.row(...)
+            txn.dataframe(...)
+
+* A number of documentation improvements.
+
+
+Breaking Changes
+~~~~~~~~~~~~~~~~
+
+* New ``protocol`` parameter in the
+  :ref:`Sender <sender_programmatic_construction>` constructor.
+
+  In previous version the protocol was always TCP.
+  In this new version you must specify the protocol explicitly.
+
+* New auto-flush defaults. In previous versions
+  :ref:`auto-flushing <sender_auto_flush>` was enabled by
+  default and triggered by a maximum buffer size. In this new version
+  auto-flushing is enabled by row count (600 rows by default) and interval
+  (1 second by default), while auto-flushing by buffer size is disabled by
+  default.
+
+  The old behaviour can be still be achieved by tweaking the auto-flush
+  settings.
+
+  .. list-table::
+    :header-rows: 1
+
+    * - Setting
+      - Old default
+      - New default
+    * - **auto_flush_rows**
+      - off
+      - 600
+    * - **auto_flush_interval**
+      - off
+      - 1000
+    * - **auto_flush_bytes**
+      - 64512
+      - off
+
+* The ``at=..`` argument of :func:`row <questdb.ingress.Sender.row>` and
+  :func:`dataframe <questdb.ingress.Sender.dataframe>` methods is now mandatory.
+  Omitting it would previously use a server-generated timestamp for the row.
+  Now if you want a server generated timestamp, you can pass the :ref:`ServerTimestamp <sender_server_timestamp>`
+  singleton to this parameter. _The ``ServerTimestamp`` behaviour is considered legacy._
+
+* The ``auth=(u, t, x, y)`` argument of the ``Sender`` constructor has now been
+  broken up into multiple arguments: ``username``, ``token``, ``token_x``, ``token_y``.
+
+* The ``tls`` argument of the ``Sender`` constructor has been removed and
+  replaced with the ``protocol`` argument. Use ``Protocol.Tcps``
+  (or ``Protocol.Https``) to enable TLS.
+  The ``tls`` values have been moved to new ``tls_ca`` and ``tls_roots``
+  :ref:`configuration settings <sender_conf_tls>`.
+
+* The ``net_interface`` argument of the ``Sender`` constructor has been renamed
+  to ``bind_interface`` and is now only available for TCP connections.
+
+The following example shows how to migrate to the new API.
+
+**Old questdb 1.x code**
+
+.. code-block:: python
+
+    from questdb.ingress import Sender
+
+    auth = (
+        'testUser1', 
+        '5UjEMuA0Pj5pjK8a-fa24dyIf-Es5mYny3oE_Wmus48',
+        'token_x=fLKYEaoEb9lrn3nkwLDA-M_xnuFOdSt9y0Z7_vWSHLU',
+        'token_y=Dt5tbS1dEDMSYfym3fgMv0B99szno-dFc1rYF9t0aac')
+    with Sender('localhost', 9009, auth=auth, tls=True) as sender:
+        sender.row(
+            'test_table',
+            symbols={'sym': 'AAPL'},
+            columns={'price': 100.0})  # `at=None` was defaulted for server time
+
+**Equivalent questdb 2.x code**
+
+.. code-block:: python
+
+    from questdb.ingress import Sender, Protocol, ServerTimestamp
+
+    sender = Sender(
+        Protocol.Tcps,
+        'localhost',
+        9009,
+        username='testUser1',
+        token='5UjEMuA0Pj5pjK8a-fa24dyIf-Es5mYny3oE_Wmus48',
+        token_x='token_x=fLKYEaoEb9lrn3nkwLDA-M_xnuFOdSt9y0Z7_vWSHLU',
+        token_y='token_y=Dt5tbS1dEDMSYfym3fgMv0B99szno-dFc1rYF9t0aac',
+        auto_flush_rows='off',
+        auto_flush_interval='off',
+        auto_flush_bytes=64512)
+    with sender:
+        sender.row(
+            'test_table',
+            symbols={'sym': 'AAPL'},
+            columns={'price': 100.0},
+            at=ServerTimestamp)  
+
+**Equivalent questdb 2.x code with configuration string**
+
+.. code-block:: python
+
+    from questdb.ingress import Sender
+
+    conf = (
+        'tcp::addr=localhost:9009;' +
+        'username=testUser1;' +
+        'token=5UjEMuA0Pj5pjK8a-fa24dyIf-Es5mYny3oE_Wmus48;' +
+        'token_x=token_x=fLKYEaoEb9lrn3nkwLDA-M_xnuFOdSt9y0Z7_vWSHLU;' +
+        'token_y=token_y=Dt5tbS1dEDMSYfym3fgMv0B99szno-dFc1rYF9t0aac;' +
+        'auto_flush_rows=off;' +
+        'auto_flush_interval=off;' +
+        'auto_flush_bytes=64512')
+    with Sender.from_conf(conf) as sender:
+        sender.row(
+            'test_table',
+            symbols={'sym': 'AAPL'},
+            columns={'price': 100.0},
+            at=ServerTimestamp)
+
+
 1.2.0 (2023-11-23)
 ------------------
 

diff --git a/README.rst b/README.rst
@@ -2,27 +2,30 @@
 QuestDB Client Library for Python
 =================================
 
-This library makes it easy to insert data into `QuestDB <https://questdb.io>`_.
+This is the official Python client library for `QuestDB <https://questdb.io>`_.
 
 This client library implements QuestDB's variant of the
 `InfluxDB Line Protocol <https://questdb.io/docs/reference/api/ilp/overview/>`_
-(ILP) over TCP.
+(ILP) over HTTP and TCP.
 
 ILP provides the fastest way to insert data into QuestDB.
 
 This implementation supports `authentication
-<https://questdb.io/docs/reference/api/ilp/authenticate/>`_ and full-connection
-encryption with TLS.
+<https://py-questdb-client.readthedocs.io/en/latest/conf.html#authentication>`_
+and full-connection encryption with
+`TLS <https://py-questdb-client.readthedocs.io/en/latest/conf.html#tls>`_.
 
 Quickstart
 ==========
 
-The latest version of the library is 1.2.0.
+The latest version of the library is 2.0.0.
 
 ::
 
     python3 -m pip install -U questdb
 
+Please start by `setting up QuestDB <https://questdb.io/docs/quick-start/>`_ . Once set up, you can use this library to insert data.
+
 .. code-block:: python
 
     from questdb.ingress import Sender, TimestampNanos
@@ -68,29 +71,25 @@ You can continue by reading the
 `Sending Data Over ILP <https://py-questdb-client.readthedocs.io/en/latest/sender.html>`_
 guide.
 
-Docs
-====
-
-https://py-questdb-client.readthedocs.io/
-
+Links
+=====
 
-Code
-====
+* `Core database documentation <https://questdb.io/docs/>`_
 
-https://github.com/questdb/py-questdb-client
+* `Python library documentation <https://py-questdb-client.readthedocs.io/>`_
 
+* `GitHub repository <https://github.com/questdb/py-questdb-client>`_
 
-Package on PyPI
-===============
-
-https://pypi.org/project/questdb/
-
+* `Package on PyPI <https://pypi.org/project/questdb/>`_
 
 Community
 =========
 
-If you need help, have additional questions or want to provide feedback, you
-may find us on `Slack <https://slack.questdb.io>`_.
+If you need help, you can ask on `Stack Overflow
+<https://stackoverflow.com/questions/ask?tags=questdb&tags=py-questdb-client>`_:
+We monitor the ``#questdb`` and ``#py-questdb-client`` tags.
+
+Alternatively, you may find us on `Slack <https://slack.questdb.io>`_.
 
 You can also `sign up to our mailing list <https://questdb.io/community/>`_
 to get notified of new releases.

diff --git a/docs/conf.py b/docs/conf.py
@@ -17,10 +17,10 @@
 source_suffix = '.rst'
 master_doc = 'index'
 project = 'questdb'
-year = '2023'
+year = '2024'
 author = 'QuestDB'
 copyright = '{0}, {1}'.format(year, author)
-version = release = '1.2.0'
+version = release = '2.0.0'
 
 github_repo_url = 'https://github.com/questdb/py-questdb-client'
 

diff --git a/docs/conf.rst b/docs/conf.rst
@@ -36,6 +36,21 @@ If you're unsure which protocol to use, see :ref:`sender_which_protocol`.
 Only the ``addr=host:port`` key is mandatory. It specifies the hostname and port
 of the QuestDB server.
 
+The same configuration string can also be loaded from the ``QDB_CLIENT_CONF``
+environment variable. This is useful for keeping sensitive information out of
+your code.
+
+.. code-block:: bash
+
+    export QDB_CLIENT_CONF="http::addr=localhost:9009;username=admin;password=quest;"
+
+.. code-block:: python
+
+    from questdb.ingress import Sender
+
+    with Sender.from_env() as sender:
+        ...
+
 Connection
 ==========
 

diff --git a/docs/examples.rst b/docs/examples.rst
@@ -5,22 +5,23 @@ Examples
 Basics
 ======
 
-Row-by-row Insertion
+HTTP with Token Auth
 --------------------
 
 The following example connects to the database and sends two rows (lines).
 
-The connection is unauthenticated and the data is sent at the end of the
-``with`` block.
+The connection is made via HTTPS and uses token based authentication.
 
-.. literalinclude:: ../examples/basic.py
+The data is sent at the end of the ``with`` block.
+
+.. literalinclude:: ../examples/http.py
    :language: python
 
 
 .. _auth_and_tls_example:
 
-Authentication and TLS
-----------------------
+TCP Authentication and TLS
+--------------------------
 
 Continuing from the previous example, the connection is authenticated
 and also uses TLS.
@@ -44,13 +45,13 @@ Note that this bypasses :ref:`auto-flushing <sender_auto_flush>`.
    :language: python
 
 
-Ticking Random Data and Timer-based Flush
------------------------------------------
+Ticking Data and Auto-Flush
+---------------------------
 
 The following example somewhat mimics the behavior of a loop in an application.
 
-It creates random ticking data at a random interval and flushes it explicitly
-based on a timer if the auto-flushing logic was not triggered recently.
+It creates random ticking data at a random interval and uses non-default
+auto-flush settings.
 
 .. literalinclude:: ../examples/random_data.py
    :language: python

diff --git a/docs/sender.rst b/docs/sender.rst
@@ -168,6 +168,8 @@ Note that all timestamps in QuestDB are stored as microseconds since the epoch,
 without timezone information. Any timezone information is dropped when the data
 is appended to the ILP buffer.
 
+.. _sender_server_timestamp:
+
 Set by server
 ~~~~~~~~~~~~~
 
@@ -591,15 +593,15 @@ Python type mappings:
 
 * Parameters that require numbers can also take an ``int``.
 
-* Millisecond durations can take an ``int`` or a ```datetime.timedelta``.
+* Millisecond durations can take an ``int`` or a ``datetime.timedelta``.
 
 * Any ``'on'`` / ``'off'`` / ``'unsafe_off'`` parameters can also be specified
   as a ``bool``.
 
 * Paths can also be specified as a ``pathlib.Path``.
 
-Customising `.from_conf()` and `.from_env()`
---------------------------------------------
+Customising ``.from_conf()`` and ``.from_env()``
+------------------------------------------------
 
 If you want to further customise the behaviour of the ``.from_conf()`` or
 ``.from_env()`` methods, you can pass additional parameters to these methods.