diff --git a/doc/release/3.2.0.rst b/doc/release/3.2.0.rst new file mode 100644 index 000000000..b91ae5f20 --- /dev/null +++ b/doc/release/3.2.0.rst @@ -0,0 +1,298 @@ +Tarantool 3.2 +============= + +Release date: August 21, 2024 + +Releases on GitHub: :tarantool-release:`3.2.0` + +The 3.2 release of Tarantool adds the following main product features and improvements for the Community and Enterprise editions: + +* **Community Edition (CE)** + + * A new experimental module for validating role configurations. + * The initial support for encoding structured data using Protobuf. + * Next prefix and Previous prefix iterators. + * Support for all UUID versions. + * Automatic loading of the most often used built-in modules into the console environment. + +* **Enterprise Edition (EE)** + + * Time-to-live (TTL) for keys in a Tarantool-based configuration storage. + + + +.. _3-2-features-for-developers: + +Developing applications +----------------------- + +.. _3-2-configuration-validation: + +Configuration validation +~~~~~~~~~~~~~~~~~~~~~~~~ + +Tarantool 3.2 includes a new experimental module for :ref:`validating role configurations ` using a declarative schema. +For example, you can validate the type of configuration values, provide an array of allowed values, or specify a custom validation function. + +Suppose, a sample :ref:`'http-api' custom role ` can accept the ``host`` and ``port`` configuration values: + +.. code-block:: yaml + + roles: [ http-api ] + roles_cfg: + http-api: + host: '127.0.0.1' + port: 8080 + +First, you need to load the ``experimental.config.utils.schema`` module: + +.. code-block:: lua + + local schema = require('experimental.config.utils.schema') + +The ``validate_port()`` function can be used to check that a port value is between ``1`` and ``65535``: + +.. code-block:: lua + + local function validate_port(port, w) + if (port <= 1 or port >= 65535) then + w.error("'port' should be between 1 and 65535, got %q", port) + end + end + +Then, you can create a schema used for validation: + +- ``host`` should be a string value from the ``allowed_values`` array. +- ``port`` should be a number that is checked using the ``validate_port()`` function declared above. + +.. code-block:: lua + + local listen_address_schema = schema.new('listen_address', schema.record({ + host = schema.scalar({ + type = 'string', + allowed_values = { '127.0.0.1', '0.0.0.0' }, + }), + port = schema.scalar({ + type = 'number', + validate = validate_port, + }), + })) + +Finally, you can pass the specified schema to the :ref:`validate() ` role's function: + +.. code-block:: lua + + local function validate(cfg) + if (cfg.host and cfg.port) then + listen_address_schema:validate(cfg) + end + end + + + + + +.. _3-2-protobuf: + +Protobuf encoder +~~~~~~~~~~~~~~~~ + +The 3.2 release adds the initial support for encoding structured data using `Protocol buffers `__. +First, you need to load the ``protobuf`` module: + +.. code-block:: lua + + local protobuf = require('protobuf') + +To encode data, you need to defined a protocol: + +.. code-block:: lua + + local customer_protocol = protobuf.protocol({ + -- Define a message and enum -- + }) + +The two main components of the protocol are messages and enums: + +- A message specifies the structure of data, in particular, the fields and their types. +- An enum defines a set of enumerated constants within the message. + +To create a message and enum, use the ``message()`` and ``enum()`` functions, respectively: + +.. code-block:: lua + + local customer_protocol = protobuf.protocol({ + protobuf.message('Customer', { + id = { 'int32', 1 }, + firstName = { 'string', 2 }, + lastName = { 'string', 3 }, + customerType = { 'CustomerType', 4 } + }), + protobuf.enum('CustomerType', { + active = 0, + inactive = 1, + }) + }) + +Once the protocol is specified, use the ``encode()`` method to encode data: + +.. code-block:: lua + + local sample_customer = customer_protocol:encode('Customer', + { id = 3, + firstName = 'Andrew', + lastName = 'Fuller', + customerType = 1 + }) + + + +.. _3-2-next-prefix-iterator: + +Next prefix iterator +~~~~~~~~~~~~~~~~~~~~ + +This release adds two new :ref:`iterators for TREE indexes `: ``np`` (next prefix) and ``pp`` (previous prefix). +If a key is a string value, a prefix is a common starting substring shared by multiple keys. +Suppose, the ``products`` space contains the following values: + +.. code-block:: tarantoolsession + + application:instance001> box.space.products:select() + --- + - - ['clothing_pants'] + - ['clothing_shirt'] + - ['electronics_laptop'] + - ['electronics_phone'] + - ['electronics_tv'] + - ['furniture_chair'] + - ['furniture_sofa'] + - ['furniture_table'] + ... + +If you use the ``np`` iterator type and set the key value to ``electronics``, the output should look as follows: + +.. code-block:: tarantoolsession + + application:instance001> box.space.products:select({ 'electronics' }, { iterator = 'np' }) + --- + - - ['furniture_chair'] + - ['furniture_sofa'] + - ['furniture_table'] + ... + +Similarly, you can use the ``pp`` iterator type: + +.. code-block:: tarantoolsession + + application:instance001> box.space.products:select({ 'electronics' }, { iterator = 'pp' }) + --- + - - ['clothing_shirt'] + - ['clothing_pants'] + ... + +Note that new iterators work only for the :ref:`memtx engine `. + + + +.. _3-2-uuid-ttl-config-storage: + +Tarantool configuration storage: TTL support for keys (EE) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The Enterprise Edition now includes a time-to-live (TTL) for keys in a Tarantool-based :ref:`configuration storage `. +You can specify a TTL value in the :ref:`config.storage.put() ` call as follows: + +.. code-block:: lua + + config.storage.put('/foo/bar', 'v1', { ttl = 60 }) + +Similarly, you can configure TTL in :ref:`config.storage.txn() `: + +.. code-block:: lua + + config.storage.txn({ + predicates = { { 'revision', '==', revision } }, + on_success = { { 'put', '/foo/bar', 'v1', { ttl = 60 } } } + }) + +A new ``config.storage.info.features.ttl`` field allows you to check whether the current version of the configuration storage supports requests with TTL: + +.. code-block:: lua + + local info = conn.call('config.storage.info') + if info.features == nil or not info.features.ttl then + error('...') + end + + + +.. _3-2-uuid: + +Support for all UUID versions +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Before the 3.2 version, Tarantool supported only UUIDs following the rules for RFC 4122 version 4. +With v3.2, UUID values of all versions (including new 6, 7, and 8) can be parsed using the :ref:`uuid ` module. +This improves interoperability with third-party data sources whose data is processed by Tarantool. + + + +.. _3-2-administration-and-maintenance: + +Administration and maintenance +------------------------------ + +.. _3-2-admin-console: + +Interactive console +~~~~~~~~~~~~~~~~~~~ + +With this release, both :ref:`Tarantool ` and :ref:`tt ` interactive consoles automatically add the most often used built-in modules into the environment. +This means that you can start using a module without loading it using the ``require`` directive. +In the interactive session below, the :ref:`config ` module is used to get the instance's configuration state right after connecting to this instance: + +.. code-block:: tarantoolsession + + application:instance001> config:info('v2') + --- + - status: ready + meta: + last: &0 [] + active: *0 + alerts: [] + ... + +To start using this new behavior, you need to set the ``console_session_scope_vars`` :ref:`compat ` value to ``new``: + +.. code-block:: yaml + + compat: + console_session_scope_vars: 'new' + + + +.. _3-2-admin-observability: + +Observability +~~~~~~~~~~~~~ + +The 3.2 release adds the following improvements related to observability: + +- A new :ref:`box.info.config ` field allows you to access an instance's configuration status. + +- :ref:`box.info.synchro.queue.term ` now includes the ``age`` and ``confirm_lag`` fields: + + - ``age`` -- shows how much time the oldest entry in the queue has spent waiting for the quorum. + - ``confirm_lag`` -- shows how much time the latest successfully confirmed entry has waited for the quorum to gather. + +- New :ref:`metrics ` are added: + + - ``tnt_memtx_tuples_data_total`` + - ``tnt_memtx_tuples_data_read_view`` + - ``tnt_memtx_tuples_data_garbage`` + - ``tnt_memtx_index_total`` + - ``tnt_memtx_index_read_view`` + - ``tnt_vinyl_memory_tuple`` + - ``tnt_config_alerts`` + - ``tnt_config_status`` diff --git a/doc/release/index.rst b/doc/release/index.rst index 0961bcbc2..1b44f54e8 100644 --- a/doc/release/index.rst +++ b/doc/release/index.rst @@ -61,6 +61,12 @@ For information about earlier versions, see :doc:`eol_versions`. - End of support - Versions + * - :doc:`3.2 ` + - **August 21, 2024** + - **August 21, 2026** + - **Not planned yet** + - | :tarantool-release:`3.2.0` + * - :doc:`3.1 ` - **April 16, 2024** - **April 16, 2026** @@ -110,6 +116,7 @@ For information about earlier versions, see :doc:`eol_versions`. .. toctree:: :maxdepth: 1 + 3.2.0 3.1.0 3.0.0 2.11.0