.. _version_5.3.1:

=============
Version 5.3.1
=============

Released on 2023-04-28.

.. 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.1.

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

    A rolling upgrade from 5.3.x to 5.3.1 is supported.
    For upgrades from 5.2.x, see the warning below.
    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.1
    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:

See the :ref:`version_5.3.0` release notes for a full list of changes in the
5.3 series.

Fixes
=====

- Fixed a performance regression introduced in 5.2.3 which led to filters on
  object columns resulting in a table scan if used with views or virtual tables.
  See `#14015 <https://github.com/crate/crate/issues/14015>`_ for details.

- Fixed an issue that caused ``geo_shape_array IS NULL`` expressions to fail
  with an ``IllegalStateException``.

- Fixed an issue that caused the actual cast/type conversion error to be hidden
  when it failed for a sub-column of an object column, when using a client
  statement with parameters i.e (python).::

    CREATE TABLE a (b OBJECT(DYNAMIC) AS (c REAL));
    # create a connection and a cursor and then:
    cursor.execute("INSERT INTO a VALUES (?)", [({"c": True},)])

- Fixed a regression that caused the ``-h`` option in ``bin/crate`` to fail with
  an ``Error parsing arguments!`` error.

- Added a :ref:`null_or_empty <scalar-null-or-empty-object>` scalar function
  that can be used as a faster alternative to `IS NULL` if it's acceptable to
  match on empty objects. This makes it possible to mitigate a performance
  regression introduced in 5.0.3 and 5.1.1

- Fixed an issue that led to ``NullPointerException`` when trying to query an
  ``OBJECT`` field with no values, using the ``NOT`` operator, e.g.::

     CREATE TABLE test (obj OBJECT(DYNAMIC)); -- no data
     SELECT myobj FROM test WHERE (obj::TEXT) NOT LIKE '%value%';

- Fixed an issue in the PostgreSQL wire protocol implementation that could
  lead to ``ClientInterrupted`` errors with some clients. An
  example client is `pg-cursor <https://www.npmjs.com/package/pg-cursor>`_.

- Fixed an issue that allowed creating columns with names conflicting with
  subscript pattern, such as ``"a[1]"``, a subscript expression enclosed in
  double quotes.

- Fixed an issue that caused ``SQLParseException`` when quoted subscript
  expressions contained quotes. An example would be querying an array with the
  name containing quotes like ``SELECT "arr""[1]";``.

- Fixed an issue that caused ``ALTER TABLE ADD COLUMN`` statement to assign
  ``PRIMARY KEY`` to wrong columns, when adding multiple primary key columns,
  having none-primary columns in-between.

- Fixed an issue that caused ``ALTER TABLE ADD COLUMN`` statement to assign a
  wrong type to ``ARRAY(TEXT)`` column and create a ``TEXT`` column instead if
  column has a ``FULLTEXT`` index.

- Fixed an issue that prevented assigning default expression to ``ARRAY``
  columns.

- Reverted base image change in the Docker image as it broke downstream components
  which rely on some of the bundled tools like ``rev``.
