.. _version_3.1.0:

=============
Version 3.1.0
=============

Released on 2018/08/28.

.. NOTE::

    If you are upgrading a cluster, you must be running CrateDB 2.0.4 or higher
    before you upgrade to 3.1.0.

    We recommend that you upgrade to the latest 3.0 release before moving to
    3.1.0.

    You cannot perform a `rolling upgrade`_ to this version. Any upgrade to
    this version will require a `full restart upgrade`_.

    When restarting, CrateDB will migrate indexes to a newer format. Depending
    on the amount of data, this may delay node start-up time.

.. WARNING::

    Tables that were created prior to upgrading to CrateDB 2.x will not
    function with 3.1 and must be recreated before moving to 3.1.x.

    You can recreate tables using ``COPY TO`` and ``COPY FROM`` while running a
    2.x release into a new table, or by `inserting the data into a new table`_.

    Before upgrading, you should `back up your data`_.

.. _rolling upgrade: https://crate.io/docs/crate/howtos/en/latest/admin/rolling-upgrade.html
.. _full restart upgrade: https://crate.io/docs/crate/howtos/en/latest/admin/full-restart-upgrade.html
.. _back up your data: https://crate.io/docs/crate/reference/en/latest/admin/snapshots.html
.. _inserting the data into a new table: https://crate.io/docs/crate/reference/en/latest/admin/system-information.html#tables-need-to-be-recreated

.. rubric:: Table of contents

.. contents::
   :local:


Changelog
=========


Breaking Changes
----------------

- `Crash`_ is no longer bundled with the ``CrateDB`` tarball distribution.


Changes
-------

- Improved performance and memory utilisation for queries against the ``sys``
  tables.

- Improved performance and memory utilisation for unsorted distributed ``GROUP
  BY`` and aggregations statements by executing the reduce operation in an
  incremental way.

- Improved performance and memory utilisation of ``GROUP BY`` statements when
  the key column is a single ``string``, ``byte``, ``short``, ``int`` or
  ``long``.

- Added a new ``CircuitBreakers`` MXBean for JMX which exposes statistics of
  all available circuit breakers.

- Exposed the cluster state version in the ``sys.nodes`` table under the
  ``cluster_state_version`` column and under the ``NodeInfo`` MXBean in JMX.

- Added a new ``ThreadPools`` MXBean for JMX which exposes statistics of all
  used thread pools.

- Changed the PostgreSQL wire protocol binary encoding format for ``timestamp``
  columns to use the newer ``int64`` format. This will enable compatibility
  with clients like ``pgx``.

- Added support for multi line SQL comments, e.g. ``/* multi line */``.

- Improved performance of queries using an array access inside the ``WHERE``
  clause. E.g.::

      SELECT * FROM t
      WHERE int_array_col[1] = 123

- Added the full PostgreSQL syntax of the ``BEGIN`` statement and the
  ``COMMIT`` statement. This improves the support for clients that are based on
  the PostgreSQL wire protocol, such as the Golang ``lib/pg`` and ``pgx``
  clients. The ``BEGIN`` and ``COMMIT`` statements and any of their parameters
  are simply ignored.

- Added a new :ref:`scalar function <scalar-functions>` ``ignore3vl`` which
  eliminates the 3-valued logic of null handling for every logical
  :ref:`expression <gloss-expression>` beneath it. If 3-valued logic is not
  required, the use of this :ref:`function <gloss-function>` in the ``WHERE``
  clause beneath a ``NOT`` :ref:`operator <gloss-operator>` can boost the query
  performance significantly. E.g.::

      SELECT * FROM t
      WHERE NOT IGNORE3VL(5 = ANY(t.int_array_col))

- Added a new ``Connections`` MBean for JMX which exposes the number of open
  connections per protocol.

- Added a new ``connections`` column to the ``sys.nodes`` table which contains
  the number of currently open connections per protocol and the total number of
  connections per protocol opened over the life-time of a node.

- Added support for ``COPY FROM ... RETURN SUMMARY`` which will return a result
  set with detailed error reporting of imported rows.

- Added a new ``stats.jobs_log_filter`` setting which can be used to control
  what kind of entries are recorded into the ``sys.jobs_log`` table.  In
  addition there is a new ``stats.jobs_log_persistent_filter`` setting which
  can be used to record entries also in the regular CrateDB log file.

- Exposed statement classification in ``sys.jobs_log`` table.

- Added a ``sys.jobs_metrics`` table which contains query latency information.

- The setting ``es.api.enabled`` has been marked as deprecated and will be
  removed in a future version. Once removed it will no longer be possible to
  use the Elasticsearch API. Please create a feature request if you're using
  the ES API and cannot use the SQL interface as substitute.

- Introduced the ``EXPLAIN ANALYZE`` statement for query profiling.

- Added ``typbasetype`` column to the ``pg_catalog.pg_type`` table.

- Added support for the ``SHOW TRANSACTION_ISOLATION`` statement.

- Added ``TimeZone`` parameter response to PostgreSQL Wire Protocol.

- Extended syntax support for certain ``ALTER BLOB TABLE RENAME``, ``REROUTE``
  and ``OPEN/CLOSE`` queries.


.. _Crash: https://crate.io/docs/crate/crash/en/latest/
