.. _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: http://crate.io/docs/crate/guide/best_practices/rolling_upgrade.html
.. _full restart upgrade: http://crate.io/docs/crate/guide/best_practices/full_restart_upgrade.html
.. _back up your data: https://crate.io/a/backing-up-and-restoring-crate/
.. _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
  availabel 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 Postgres 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 Postgres 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 scalar function ``ignore3vl`` which eliminates the 3-valued logic
  of null handling for every logical expression beneath it. If 3-valued logic
  is not required, the use of this function in the ``WHERE`` clause beneath a
  ``NOT`` 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 ES 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 Postgres Wire Protocol.

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