# How to Migrate from an Older Feast Version to the Latest Release

> Easily migrate from older Feast versions to the latest release. Upgrade your SDK, use the repo-upgrade tool, and switch registries for a smoother workflow.

- Repository: [Feast/feast](https://github.com/feast-dev/feast)
- Tags: migration-guide
- Published: 2026-03-01

---

**Migrate from legacy Feast v0.9 to the modern v0.10+ architecture by backing up your PostgreSQL registry, upgrading the SDK, running the automated `repo-upgrade` tool, and switching to file-based registry with CLI-driven materialization.**

Feast has undergone a fundamental architectural transformation from a Kubernetes-centric service stack to a lightweight, CLI/SDK-first framework. This guide walks you through the complete migration path from **feast-dev/feast** v0.9 (or any pre-0.10 release) to the latest version, preserving your feature definitions while adopting the modern file-based registry and simplified operational model.

## Understanding the Architecture Changes

Three core layers changed between v0.9 and v0.10+, each requiring specific migration steps.

### Registry Storage

The registry moved from a **gRPC service backed by PostgreSQL** to a **file-based registry** stored on local paths, S3, or GCS. According to the source analysis in `docs/project/feast-0.9-vs-feast-0.10+.md`, you must export the old database-backed registry and import it into the new format, or allow the CLI to generate a fresh registry during initialization.

### Feature Definitions

`FeatureView` constructors now require **keyword arguments** exclusively, and the `features` parameter was renamed to `schema`. The class definition in [`sdk/python/feast/feature_view.py`](https://github.com/feast-dev/feast/blob/main/sdk/python/feast/feature_view.py) enforces these new signatures, breaking any code using positional arguments or the old `features=` parameter.

### Materialization Workflow

Materialization is no longer a background job managed by a Kubernetes service. Instead, it is a CLI command (`feast materialize`) that you invoke directly or schedule via Airflow, Prefect, or similar orchestrators. This change eliminates the need for Helm charts and custom job-service scripts.

## Pre-Migration Checklist

Before executing the migration, verify your current state and secure your data.

### Verify Current Version

Run the following command to identify your starting point:

```bash
feast --version

```

If you are on **v0.9** or any pre-0.10 release, you must follow the full migration path including registry conversion. If you are on v0.10 or later but pre-0.20, you can skip the registry export but must perform manual code refactoring (or upgrade to 0.20+ to use the automated tool).

### Back Up the Legacy Registry

The v0.9 registry resides in a PostgreSQL database (default name `registry`). Create a dump before proceeding:

```bash

# Export to JSON for safety and potential re-import

feast registry export -p postgres://user:pwd@host:5432/registry -o registry_backup.json

```

This backup allows rollback if the conversion to the file-based registry encounters errors.

## Step-by-Step Migration Process

### Upgrade the Feast SDK

Install the latest version of the Python SDK, which includes the migration utilities:

```bash
pip install --upgrade "feast[aws]"   # Add relevant extras (aws, gcp, etc.)

```

As noted in [`CHANGELOG.md`](https://github.com/feast-dev/feast/blob/main/CHANGELOG.md), versions v0.20 and later include the `repo-upgrade` command essential for automated refactoring.

### Run the Automated Repo-Upgrade (v0.20+)

From the root of your feature repository, execute the built-in migration script:

```bash
feast repo-upgrade .

```

This tool, referenced in [`docs/blog/feast-0-20-adds-api-and-connector-improvements.md`](https://github.com/feast-dev/feast/blob/main/docs/blog/feast-0-20-adds-api-and-connector-improvements.md), performs the following transformations:

- Converts `FeatureView(features=…)` to `FeatureView(schema=…)`.
- Transforms `Feature` objects into `Field` objects.
- Ensures all constructor arguments use keyword syntax.
- Adds optional metadata fields (`owner`, `description`) where missing.

### Manual FeatureView Refactoring (pre-0.20)

If you cannot upgrade to v0.20+ first, manually update your Python definitions. Compare the old and new patterns:

**Old Style (v0.9):**

```python
from feast import Feature, FeatureView

driver_fv = FeatureView(
    "driver_stats",
    ["driver_id"],
    [
        Feature("daily_trip_count", Int64),
        Feature("hourly_trip_count", Int64),
    ],
)

```

**New Style (v0.10+):**

```python
from feast import Field, FeatureView

driver_fv = FeatureView(
    name="driver_stats",
    entities=["driver_id"],
    schema=[
        Field(name="daily_trip_count", dtype=Int64),
        Field(name="hourly_trip_count", dtype=Int64),
    ],
    description="Aggregated driver statistics",
    owner="ml-platform@example.com",
)

```

Key changes enforced by [`sdk/python/feast/feature_view.py`](https://github.com/feast-dev/feast/blob/main/sdk/python/feast/feature_view.py):
- **Parameter rename:** `features` → `schema`
- **Type change:** `Feature` objects → `Field` objects
- **Syntax:** All arguments must be keyword arguments (no positional args)

### Initialize the File-Based Registry

Create the new registry structure by running:

```bash
feast apply

```

This command, implemented in [`sdk/python/feast/cli/cli.py`](https://github.com/feast-dev/feast/blob/main/sdk/python/feast/cli/cli.py), initializes the file-based registry at the path specified in your [`feature_store.yaml`](https://github.com/feast-dev/feast/blob/main/feature_store.yaml) (local, S3, or GCS). If you exported a backup JSON from the old PostgreSQL registry, import it now:

```bash
feast registry import -i registry_backup.json

```

### Update Materialization Workflows

Replace Kubernetes job services or custom scripts with direct CLI calls. For example, to materialize features for the past week:

```bash
feast materialize --start-date "$(date -d '7 days ago' +%F)" --end-date "$(date +%F)"

```

Schedule this command using your existing orchestrator (Airflow, Prefect, Dagster). This eliminates the operational overhead of maintaining the legacy job service infrastructure.

### Verify the Migration

Run the built-in validation suite:

```bash

# Validate feature definitions

feast validate

# Test online feature retrieval

feast get features driver_stats:hourly_trip_count -e driver_id=123

```

Additionally, execute the unit test suite to ensure compatibility:

```bash
make test-python-unit

```

Successful validation confirms that your feature definitions are syntactically correct and the registry is properly configured.

## Summary

- **Back up your legacy PostgreSQL registry** using `feast registry export` before starting the migration.
- **Upgrade to the latest SDK** (v0.20+) to access the `feast repo-upgrade` automation tool.
- **Transform FeatureView definitions** by changing `features=` to `schema=` and using `Field` objects instead of `Feature`.
- **Adopt the file-based registry** by running `feast apply`, replacing the old database-backed gRPC service.
- **Modernize materialization** by replacing Kubernetes job services with the `feast materialize` CLI command scheduled via your orchestrator.

## Frequently Asked Questions

### How do I migrate from Feast v0.9 to v0.10+ without losing my feature definitions?

Export your existing PostgreSQL registry to JSON using `feast registry export`, then upgrade your Python SDK to v0.20 or later and run `feast repo-upgrade .` from your feature repository root. This automated script converts legacy `FeatureView` syntax (using `features=` and `Feature` objects) to the modern API (using `schema=` and `Field` objects) while preserving your business logic.

### What happened to the PostgreSQL registry in newer Feast versions?

Feast replaced the gRPC-based PostgreSQL registry with a lightweight **file-based registry** stored on local filesystems, S3, or GCS. As documented in `docs/project/feast-0.9-vs-feast-0.10+.md`, this change eliminates the need for running a persistent database service for registry storage. You initialize the new registry by running `feast apply`, which creates the registry file at the path specified in your [`feature_store.yaml`](https://github.com/feast-dev/feast/blob/main/feature_store.yaml).

### Can I still use Kubernetes to run Feast after upgrading?

Yes, but the architecture changes significantly. Modern Feast (v0.10+) does not require a Kubernetes-based **Core service** or **job service** for materialization. Instead, you run `feast materialize` as a CLI command within your existing Kubernetes jobs, Airflow pods, or other orchestrators. This simplifies operations by removing the need to maintain Helm charts for the Feast control plane while still allowing you to execute feature engineering workloads on Kubernetes.

### Where can I find the complete list of breaking changes between versions?

Consult the official [`CHANGELOG.md`](https://github.com/feast-dev/feast/blob/main/CHANGELOG.md) in the feast-dev/feast repository for a chronological list of all breaking changes, deprecations, and migration notes. Additionally, `docs/project/feast-0.9-vs-feast-0.10+.md` provides a detailed architectural comparison specifically for the major transition between the legacy Kubernetes-centric model and the modern CLI/SDK-first architecture. For API-specific changes, examine the source code in [`sdk/python/feast/feature_view.py`](https://github.com/feast-dev/feast/blob/main/sdk/python/feast/feature_view.py) to see the current constructor signatures.