.. _version_5.1.0:

=============
Version 5.1.0
=============

Released on 2022-10-11.

.. NOTE::

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

    We recommend that you upgrade to the latest 5.0 release before moving to
    5.1.0.

    A rolling upgrade from 5.0.x to 5.1.0 is supported.
    Before upgrading, you should `back up your data`_.

.. WARNING::

    Tables that were created before CrateDB 4.x will not function with 5.x
    and must be recreated before moving to 5.x.x.

    You can recreate tables using ``COPY TO`` and ``COPY FROM`` or by
    `inserting the data into a new table`_.

.. _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:


Breaking Changes
================

- Removed the ``node.store.allow_mmapfs`` setting. It was deprecated in 4.1.0
  in favour of the ``node.store.allow_mmap`` setting.

- Removed the ``indices.breaker.fielddata.limit`` setting and the ``*.overhead``
  settings for all circuit breakers. They were deprecated in 4.3.0 and had no
  effect since then.

- Removed the deprecated ``discovery.zen.publish_timeout``,
  ``discovery.zen.commit_timeout``, ``discovery.zen.no_master_block``,
  ``discovery.zen.publish_diff.enable`` settings.
  They had no effect since 4.0.0 and have been deprecated in 4.4.0.

- Removed the deprecated azure discovery functionality.

- Fields referencing ``catalog`` in :ref:`information_schema <information_schema>`
  tables now return ``'crate'`` (the only catalog in CrateDB) instead of the
  table ``schema``.

Deprecations
============

- Deprecated the ``upgrade_segments`` option of the
  :ref:`OPTIMIZE TABLE <sql-optimize>` statement. The option will now longer
  have any effect and will be removed in the future.


Changes
=======

SQL Statements
--------------

- Added initial support for cursors. See :ref:`DECLARE <sql-declare>`,
  :ref:`FETCH <sql-fetch>` and :ref:`CLOSE <sql-close>`.

- Added support for the :ref:`EXISTS <sql_dql_exists>` expression.

- Added support for correlated scalar sub-queries within the select list of a
  query. See :ref:`Scalar subquery <sql-scalar-subquery>`.

- Added support of ``GROUP BY`` on :ref:`ARRAY <type-array>` typed columns.

SQL Standard And PostgreSQL Schema Compatibility
------------------------------------------------

- Added support for ``SET TIME ZONE`` to improve PostgreSQL Compatibility.
  Timezone will be ignored on the server side.

- Added a :ref:`application_name <conf-session-application-name>` session
  setting that can be used to identify clients or applications which connect to
  a CrateDB node.

- Added support for ``catalog`` in fully qualified table and column names,
  i.e.::

    SELECT * FROM crate.doc.t1;
    SELECT crate.doc.t1.a, crate.doc.t1.b FROM crate.doc.t1;

- Made the commas between successive ``transaction_modes`` of the
  :ref:`BEGIN <ref-begin>` and its SQL equivalent
  :ref:`START TRANSACTION <sql-start-transaction>` statement optional to support
  compatibility with clients and tools using an older (< 8.0) PostgreSQL syntax.

- Changed the :ref:`interval <type-interval>` parameter of
  :ref:`date_trunc <scalar-date_trunc>` to be case insensitive.

- Added support for ``'YES'``, ``'ON'`` and ``'1'`` as alternative way to
  specify a ``TRUE`` boolean constant and ``'NO'``, ``'OFF'`` and ``'0'`` as
  alternative way to specify ``FALSE`` boolean constant improving compatibility
  with PostgreSQL.

- Added support for casting :ref:`TIMESTAMP <type-timestamp>` and
  :ref:`TIMESTAMP WITHOUT TIME ZONE <type-timestamp-without-tz>` values to the
  :ref:`DATE <type-date>` data type and vice versa.

Performance Improvements
------------------------

- Improve performance of queries on :ref:`sys.snapshots <sys-snapshots>`.

Administration and Operations
-----------------------------

- Updated to Admin UI 1.23.1, which improves scrolling behavior on wide result
  sets, and fixes formatting of :ref:`TIMESTAMP WITHOUT TIME ZONE
  <type-timestamp-without-tz>` values in query console result table.

- Added I/O throughput throttling of the :ref:`analyze` statement as well as of
  the periodic statistic collection controlled by the
  :ref:`stats.service.interval` setting to lower the impact on the cluster
  load. This throttling can be controlled by a new setting
  :ref:`stats.service.max_bytes_per_sec <stats.service.max_bytes_per_sec>` and
  is set 40MB/s by default.
