Comment on page
This guide is tailored for existing NATS users upgrading from NATS version 2.9.x. This will read as a summary with links to specific documentation pages to learn more about the feature or improvement.
Although all existing client versions will work, new client versions will expose additional options used to leverage new features. The minimum client versions that have full 2.10.0 support include:
For critical infrastructure like NATS, zero downtime upgrades are table stakes. Although the best practice for all infrastructure like this is for users to thoroughly test a new release against your specific workloads, inevitably there are cases where an upgrade occurs in production followed by a decision to downgrade. This is never recommended and can cause more harm than good for most infrastructure and data systems.
Below are a few important considerations if downgrading is required.
2.10.0 brings on-disk storage changes which bring significant performance improvements. These are not compatible with previous versions of the NATS Server. If an upgrade is performed to a server with existing stream data on disk, followed by a downgrade, the older version server will not understand the stream data in the new format.
However, being mindful of the possibility of the need to downgrade, a special version of the 2.9.x series was released with awareness of key changes in the new storage format, allowing it to startup properly.
The takeaway is that if a downgrade is the only resort, it must be to 2.9.22 or later to ensure storage format changes are handled appropriately.
There are new stream and consumer configuration options that could be problematic if a downgrade occurs since previous versions of the server have no awareness of them. Examples include:
- Multi-filter consumers - Downgrading would result in no filter being applied since the new field is configured as a list rather than a single string.
- Subject-transform on streams - Downgrading would result in the subject transform not being applied since the server has no awareness of it.
- Compression on streams - Downgrading when compression is enabled on streams will cause those streams to become unloadable since the older server versions will not understand the compression being used.
- A new
sync_intervalserver config option has been added to change the default sync interval of stream data when written to disk, including allowing all writes to be flushed immediately. This option is only relevant if you need to modify durability guarantees.
- The requirement to use all wildcard tokens in subject mapping or transforms has been relaxed. This can be applied to config or account-based subject mapping, stream subject transforms, and stream republishing, but not on subject mappings that are associated with stream and service import/export between accounts.
tsfield has been added to stream info responses indicating the server time of the snapshot. This was added to allow for local time calculations relying on the local clock.
- An array of subject-transforms (subject filter + subject transform destination) can be added to a mirror or source configuration (can not use the single subject filter/subject transform destination fields at the same time as the array).
- A stream configured with
sourcescan source from the same stream multiple times when distinct filter+transform options are used, allowing for some messages of a stream to be sourced more than once.
tsfield has been added to consumer info responses indicating the server time of the snapshot. This was added to allow for local time calculations without relying on the local clock.
- A bucket configured as a mirror or sourcing from other buckets
- A pluggable server extension, referred to as auth callout, has been added. This provides a mechanism for delegating authentication checks against a bring-your-own (BYO) provider and, optionally, dynamically declaring permissions for the authenticated user.
- When defining routes between servers, a handful of optimizations have been introduced including a pool of TCP connections between servers, optional pinning of accounts to connections, and optional compression of traffic. There is quite a bit to dig into, so check out the v2 routes page for details.
- Prior to 2.10, setting
republishconfiguration on mirrors would result in an error. On sourcing streams, only messages that were actively between stored matching configured
subjectswould be republished. The behavior has been relaxed to allow republishing on mirrors and includes all messages on sourcing streams.
- A new header has been added on a fetch response that indicates to clients the fetch has been fulfilled without requiring clients to rely on heartbeats. It avoids some conditions in which the client would issue fetch requests that could go over limits or have more fetch requests pending than required.
- Previously, a leafnode configured with two or more remotes binding to the same hub account would be rejected. This restriction has been relaxed since each remote could be binding to a different local account.