3.8.0

Date: 2026-07-09 Tag: 3.8.0

Overview

Tarantool 3.x is the recommended release series. Users of Tarantool 2.11 are encouraged to update to the latest 3.x release.

This release introduces 33 improvements and resolves 24 bugs since 3.7.0.

Notable changes are:

• Significant improvements to backup machinery:
  • Backups now include xlogs up to the point when box.backup.start() was called.
  • Incremental backups, containing only xlogs since the previous backup, are now supported.
  • Point-in-time recovery is now possible by creating recovery_points periodically and restoring the database state to these points using the tt utility. Creating cluster-wide recovery points in a VShard cluster is also supported. Full support for point-in-time recovery will be available in the upcoming tt 2.14.0 and VShard 0.1.42 releases.
• Built-in health checks for Tarantool instances. The new box.info.health field reports liveness and readiness states, including per-check statuses and failure reasons. Applications can register liveness probes with box.ctl.liveness_probe(), while application roles can provide readiness checks using the new health_check() role method. Failed health checks are also exposed through box.info.config.alerts.
• Human-readable units are now supported in time- and memory-related configuration options, both in configuration files and via box.cfg{...}:
  • Memory-related configuration option values can be specified using B, KiB, MiB, GiB, TiB, and PiB.
  • Time-related configuration option values can be specified using ms, s, m, h, d, w, M, and y.

Please consider the full list of user-visible changes below.

Compatibility

Tarantool 2.x and 3.x are compatible in the binary data layout, client-server protocol, and replication protocol. It means upgrade may be performed with zero downtime for read requests and the order-of-network-lag downtime for write requests.

Please follow the upgrade procedure to plan your update actions.

Users of Tarantool 2.x may be interested in the compat options that allow to imitate some 2.x behavior. This allows to perform application code update step-by-step, not all-at-once.

Functionality added or changed

Core

• Now, if Tarantool is started without a configuration file and box.cfg.app_threads is set from application code, the experimental.threads module is initialized with the default thread group named app (gh-12601).
• It is now possible to use a thread ID as a target for the call and eval functions provided by the experimental.threads module (gh-12628).
• Application threads are now named <group><id>, where <group> is the name of the configured group the thread belongs to and <id> is the ID of the thread within that group. Thread names are used in logs, so this change helps identify the thread that logged a particular message. Additionally, the meaning of the thread_id field returned by the info() function of the experimental.threads Lua module has been changed: it now shows the thread's ID within the group, rather than the global thread ID used internally (gh-12643).
• Added support for the XDG Base Directory specification for the console history file. The history file is now searched for in $XDG_STATE_HOME/tarantool and $HOME/.local/state/tarantool directories, with the legacy $HOME/.tarantool_history location taking priority to ensure seamless migration. On fresh installations, the XDG-compliant state directory is created automatically (gh-12356).
• The Lua module trigger is now available in application threads (gh-12707).
• The experimental.threads Lua module can now be used for calling the tx thread when thread groups are not configured (gh-12709).
• Replication errors and Raft messages now include extended node representations (name/uuid, id, and addr) for both local and remote nodes (gh-12697).
• box.backup.start() has been enhanced to back up xlogs that are rotated at the time of the call (gh-11729).
• Added the from_vclock parameter to the box.backup.start() to enable incremental backups (gh-11729).
• Added the ttl parameter to the box.backup.start() to set expiration time for backups (gh-11729).
• Added the box_backup_default_ttl compatibility option to control the default expiration time for backups (gh-11729).
• Added a new API, box.backup.info() to retrieve information about the running backup (gh-11729).
• Added box.backup.recovery_point.create() to create a recovery point (gh-11729).
• Added the recovery_points field to the box.backup.info() result, showing recovery points located in backup xlogs (gh-11729).
• Added the session.users.<name>.idle_timeout configuration option to close idle IPROTO connections of a user after the specified timeout (gh-12839).
• Introduced a recovery point manager in box.backup.recovery_point: manager_create(), manager_drop(), and the managers table. A manager periodically creates recovery points using a pluggable backend and is available before box.cfg() is called (gh-12865).
• Added box.info.health with liveness and readiness checks. Applications can register liveness probes with box.ctl.liveness_probe(), and roles can provide readiness checks through the health_check() role method.

Config

• Added support for the union schema type to the experimental.config.utils.schema module. It allows values to match one of several schema variants (gh-12539).
• Dropped the legacy string, number and number, string schema types from the experimental.config.utils.schema module. Use the union schema type instead (gh-12539).
• Added config:cluster_config() to return a raw cluster configuration after merging all cluster configuration sources. Default values are not applied, and template variables are not substituted in the returned configuration (gh-10617).
• Extended metrics.include and metrics.exclude to accept custom metric selectors in addition to built-in metric groups (gh-11358).
• Extended the alerts API: set(), add(), unset(), and clear() now return a bool indicating whether a change was made. For example, set() returns false if an alert with the same key and message already exists. Also added alerts_namespace:get(key) to look up an alert by key.
• Added support for scalar values in config.context: a template variable can now be set directly to a string, number, or boolean. Variables can be overridden at any hierarchy level (global, group, replicaset, instance) (gh-11002).
• Added logging of the collected instance configuration when declarative configuration startup fails after the configuration has been collected and TT_CONFIG_DEBUG=1 is set. Sensitive values are masked (gh-11117).
• Added the sharding.rebalancer_bucket_send_timeout configuration option. Supported since vshard 0.1.41. The default value is infinity.
• Memory-related configuration options now support human-readable size units. Values can be specified using B, KiB, MiB, GiB, TiB, and PiB in both configuration files and via box.cfg{...} (gh-5786).
• Duration-related configuration options now support human-readable time units. Values can be specified using ms, s, m, h, d, w, M, and y in both configuration files and via box.cfg{...} (gh-5786).
• The experimental.config.utils.schema module now provides the :normalize() method. It converts human-readable byte sizes and duration strings, such as 256MiB or 30s, to numeric values according to the schema annotations (gh-5786).
• Added config:is_metric_enabled() to check whether a metric group or selector is enabled by the applied metrics.include / metrics.exclude configuration (gh-12841).
• Added the built-in roles.recovery-point-manager role. This role periodically creates recovery points across a cluster, using a configurable backend (the built-in net-replicaset backend creates a point on a remote replicaset's leader) (gh-12865).

Metrics

• Updated the metrics submodule to 1.8.1.

Changes in 1.8.0:

• Added selector-based filtering for custom metrics. Custom metrics can now be associated with hierarchical selectors and controlled via metrics.set_filter() or metrics.cfg() include/exclude options. Unknown include/exclude entries are treated as custom selectors, while built-in metric group names keep the existing behavior (gh-543).

• Added metrics.namespace() and metrics.set_filter() to mark custom collectors and callbacks with selectors and filter them at collection time (gh-543).

Changes in 1.8.1:

• Fixed metrics.cfg{exclude = {'all'}} so it excludes custom metric selectors in addition to built-in metric groups (gh-548).

Bugs fixed

Core

• Fixed a double-free bug that occurred at exit when application threads were configured (gh-12631).
• Fixed a bug when Tarantool crashed at exit if there was a fiber waiting on a condition variable created in an application thread (gh-12792).
• Fixed a bug when application threads could not be called from shutdown triggers (gh-12790).
• Fixed an assertion failure in fiber_signal_reset() that occurred during application threads initialization on CentOS 7 based systems (gh-12846).
• Fixed a heap-use-after-free bug when a space.before_replace trigger yielded with disabled MVCC (gh-12779).
• Fixed a stack overflow when checking MsgPack input with deeply nested values containing extension types (ghs-162).
• Fixed an issue where zero values were incorrectly rejected by fixed-point decimal fields when their scale was greater than or equal to their precision (gh-12808).

Memtx

• Fixed a bug in MVCC read-confirmed isolation where delete and update could see an incorrect tuple (gh-12260).

Replication

• Fixed a crash that could occur when a replication source was removed from box.cfg.replication at the same time as the node reached its maximum WAL queue size (configured by box.cfg.wal_queue_max_size) (gh-12719).
• Fixed a replica sending its master an outdated acknowledgement right after reconnecting, which made the replica's vclock progress appear to move backwards on the master in box.info.replication (gh-12795).
• Fixed a bug where replicas kept their old connection to the master and ignored changes to replication parameters (gh-12728).
• election_mode='off' has been reworked internally. A promoted off-mode node will now be reported as 'leader' in box.info.election.state. Additionally, such nodes are now able to vote for other nodes that may have different election modes (gh-8095).

LuaJIT

Backported patches from the vanilla LuaJIT trunk (gh-12480). The following issues were fixed as part of this activity:

• Fixed incorrect JIT behavior for vararg FFI functions on the macOS AArch64 platform (gh-6097).
• Fixed various FFI ABI and calling convention issues for x64/AArch64 architectures.
• Fixed ipairs_aux() to match JIT backend behavior on x86/x64.
• Fixed os.time() returning -1.
• Fixed UBSan warnings for table.new().

SQL

• Fixed collisions of prepared statement IDs - now a new prepared statement will always be assigned a free ID (gh-12537).
• Added permission checks when creating a trigger in SQL. Now only users with 'alter' privileges on a table can create triggers for that table (ghs-163).
• An error now occurs if a column appears more than once in a subquery of a SELECT statement (gh-12337).

Config

• An unsupported (too old) or missing vshard version required by the sharding configuration is now detected at the configuration validation stage, rather than during application. This ensures that invalid configurations are rejected before any changes are applied.

Lua

Datetime

• Fixed parsing for time with a decimal fraction of hour or minute (gh-12082).
• Fixed a stack overflow strptime() function when parsing timezones (ghs-146).

Pickle

• Fixed abortion on calling pack() with an empty format string or a string value for the 'a' format specifier (gh-12063).