.. _version_5.3.0:

=============
Version 5.3.0
=============

Released on 2023-04-04.

.. WARNING::

    CrateDB 5.3.x versions up to :ref:`5.3.3 <version_5.3.3>` (excluding)
    contain a critical bug which can lead to data corruption/loss when using
    a column definition with a number data type and disabled index
    (``INDEX OFF``).
    It is not recommended to use those versions, use CrateDB >=
    :ref:`5.3.3 <version_5.3.3>` instead.

.. NOTE::

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

    We recommend that you upgrade to the latest 5.2 release before moving to
    5.3.0.

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

.. WARNING::

    Due to a bug in the replication layer, rolling upgrades from 5.2.x to 5.3.0
    with ongoing write traffic can lead to corrupted shards and in worse case,
    data loss. We recommend that you stop all write traffic before upgrading
    and/or perform a full cluster restart.


.. 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 support for ``SET LICENSE``. The statement had no effect since CrateDB
  4.5 and was only kept for backward compatibility.


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

None


Changes
=======

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

- Changed the behavior of ``SHOW search_path`` to omit the implicit
  ``pg_catalog`` schema, unless the user set it explicitly. This matches the
  PostgreSQL behavior.

- Allowed schema and table names to contain upper case letters. This can be
  achieved by quoting the names. Unquoted names with upper case letters are
  converted to lower cases which has been the existing behaviour.

- Allowed schema and table names to start with ``_``.

- Added the :ref:`col_description(integer, integer) <scalar-col_description>` scalar
  function for improved PostgreSQL compatibility. CrateDB does not support
  comments for columns, so this function always returns ``NULL``.


SQL statements
--------------

- Changed the behavior of ``INSERT INTO`` on tables with generated columns which
  use non-deterministic functions.
  Previously, if the columns were included in the column target list, the
  provided values were validated against re-computed values of the generated
  expression. Given that the functions are not deterministic, this validation
  always failed and made it impossible to copy data between tables
  with such columns.

  In the new behavior the values are no longer validated for non-deterministic
  functions but are accepted as is. If the column is not present in the target
  list, they are re-computed as before. This lets users do copy operations
  between such tables and decide if the source value should be used as is, or if
  they should be re-computed by either adding or removing the columns from the
  ``INSERT INTO`` column target list.


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

- Optimized the evaluation of ``CASE`` expressions to prevent stack overflows
  for very large expressions.

- Improved the performance of queries using a correlated sub-query inside the
  ``WHERE`` clause in conjunction with a non-correlated filter clause.

- Improved performance of statements that create multiple partitions at once,
  which can occur during ``COPY FROM`` or INSERTS with multi-values into
  partitioned tables.

- Improved ingestion performance by up to 30%.
