Implementation:MaterializeInc Materialize Get Minor Versions

Knowledge Sources	misc/python/materialize/checks/scenarios_upgrade.py, misc/python/materialize/version_list.py
Domains	Version Management, Upgrade Testing, Python API
Last Updated	2026-02-08

Overview

Concrete version resolution functions for discovering available Materialize minor versions, provided by materialize.checks.scenarios_upgrade and materialize.version_list.

Description

The version resolution implementation consists of two layers:

Layer 1: Scenario-level helpers (in scenarios_upgrade.py, lines 43–66):

• get_minor_versions() — Returns a cached list of published minor versions (latest patch per minor), excluding the current minor version, filtered to versions strictly less than the current cargo version. Used by upgrade scenarios to determine hop targets.
• get_last_version() — Returns the most recent entry from get_minor_versions() (i.e., the latest published minor version before the current one).
• get_previous_version() — Returns the second most recent entry from get_minor_versions() (i.e., the minor version before the last one).

All three functions use module-level caching via global variables to avoid redundant computation.

Layer 2: Core version enumeration (in version_list.py, lines 385–432):

• get_published_minor_mz_versions() — The workhorse function that enumerates all git tags, groups them by minor version, selects the latest patch for each, validates Docker image availability, and returns the result. Supports optional filtering via include_filter, ordering control via newest_first, result limiting via limit, and exclusion of the current minor version via exclude_current_minor_version.

Usage

Use these functions when you need to programmatically determine which Materialize versions are available for upgrade testing. The scenario-level helpers are sufficient for most use cases; the core get_published_minor_mz_versions() function is for advanced use cases requiring custom filters or limits.

Code Reference

Source Location

• misc/python/materialize/checks/scenarios_upgrade.py, lines 43–66.
• misc/python/materialize/version_list.py, lines 385–432.

Signature

Scenario-level helpers:

def get_minor_versions() -> list[MzVersion]: ...

def get_last_version() -> MzVersion: ...

def get_previous_version() -> MzVersion: ...

Core version enumeration:

def get_published_minor_mz_versions(
    newest_first: bool = True,
    limit: int | None = None,
    include_filter: Callable[[MzVersion], bool] | None = None,
    exclude_current_minor_version: bool = False,
) -> list[MzVersion]: ...

Import

from materialize.version_list import get_published_minor_mz_versions
from materialize.checks.scenarios_upgrade import get_minor_versions, get_last_version, get_previous_version

I/O Contract

Inputs

Parameter	Type	Description
newest_first	bool	If True (default), return versions in descending order. If False, ascending.
limit	None	Maximum number of minor versions to return. None means no limit.
include_filter	Callable[[MzVersion], bool] | None	Optional predicate to include only versions that satisfy a custom condition.
exclude_current_minor_version	bool	If True, exclude versions sharing the same major.minor as the current cargo version.

Outputs

Function	Return Type	Description
get_minor_versions()	list[MzVersion]	All published minor versions older than current, newest first.
get_last_version()	MzVersion	The single most recent published minor version before the current one.
get_previous_version()	MzVersion	The second most recent published minor version before the current one.
get_published_minor_mz_versions()	list[MzVersion]	Filtered, validated list of latest-patch-per-minor versions with confirmed Docker images.

Usage Examples

Getting the last version for a single-hop upgrade scenario:

from materialize.checks.scenarios_upgrade import get_last_version

last = get_last_version()
print(f"Upgrading from {last} to current")

Getting all minor versions for a multi-hop upgrade:

from materialize.checks.scenarios_upgrade import get_minor_versions

versions = get_minor_versions()
# versions[0] = last released minor version
# versions[1] = previous minor version
# versions[2] = two minor versions back
# ...

Using the core function with a custom filter:

from materialize.version_list import get_published_minor_mz_versions
from materialize.mz_version import MzVersion

# Only get versions from the 0.x major line, limited to 5
versions = get_published_minor_mz_versions(
    newest_first=True,
    limit=5,
    include_filter=lambda v: v.major == 0,
)

Related Pages

Implements Principle

• Principle:MaterializeInc_Materialize_Version_Resolution