SBT 1.0 App Migration Guide

This page is a high level overview of what it takes to migrate SBT BETA apps to SBT 1.0 apps.

TLDR — SBT 1.0 Migration

  • Your core workflow does not change - sbt build and publish commands change slightly.

  • For existing (beta) apps: keep using --beta flags. You can keep them running as-is. Migration is not urgent.

  • For new SBT 1.0 apps: omit the --beta flag.

  • The YAML version and publisher are used.

  • sbt build-app creates a Prefect Deployment job

  • Running a published app in platform will run the variant via Prefect

1. What Is Changing

SBT 1.0 changes how apps are built and executed in the platform. Under the hood, compute moves off Snowflake stored procedures and onto Docker containers running in AWS via Prefect. For you day-to-day, the changes are smaller.

Execution Engine

Before (SBT Beta)

After (SBT 1.0)

Python apps execute code as Snowflake stored procedures.

Python based apps run in Docker containers on AWS, orchestrated by Prefect.

Package constraints. Not all Python libraries could be used.

No package constraints. Any library in your requirements.txt works.

External API calls were not possible.

Apps can call external APIs at runtime.

SBT Build commands just uploaded code to S3.

SBT Build also creates a Prefect Deployment pipeline before publishing.

Version numbers were auto-incremented (1, 2, 3...).

You set the version yourself as any alphanumeric string (e.g. 'v1.0', 'alpha-1').

Variant failures are triaged in Snowflake’s UI.

Variant failures are triaged in Prefect.

 Command Changes

Old Command (Beta)

New Command (SBT 1.0)

sbt build-app --app-name <name> --beta

sbt build-app --app-name <name>

sbt publish-app <name> <version> --beta

sbt publish-app <name> <version>

Note on existing beta apps!

Existing apps built on SBT Beta continue to work. They are now called legacy apps. You can still manage variants, trigger runs, and publish new versions using the --beta flag. Nothing breaks automatically.

2. Building and Publishing an SBT 1.0 App

The build and publish flows are similar to before, with two key differences: the --beta flag can be omitted, so that the build step now creates an app Deployment job in Prefect where all variants will run.

Build

sbt build-app --app-name <app-name>

# Example:
sbt build-app --app-name customer-trial-app

 What happens during build:

•       SBT uploads your app code, sources, and requirements to S3.

•       A Prefect Deployment is created and SBT monitors for the completion of the task.

•       This must be completed before publishing the app version.

•       If it fails, check your SBT log output for an error message.

Publish

sbt publish-app <app-name> <version>

# Example:

sbt publish-app customer-trial-app alpha-1

Once published, the new version will appear in the App Catalog, as a new version for that app. This does not push existing subscribers to be upgraded to this new version.

For Legacy (Beta) Apps — Build and Publish

Nothing changes for your existing apps right now. Use the --beta flag exactly as before:

sbt build-app --app-name <name> --beta

sbt publish-app <name> <version> --beta

3. Variant Runs for SBT 1.0 Apps

SBT 1.0 python based app variants now execute code in the built Prefect Deployment pipeline, offloading compute from Snowflake to AWS. Data is read from Snowflake and data output is persisted back to snowflake.

Deployment jobs are created with the following naming convention: ENV-APP_NAME-VERSION

4. Migrating an Existing App to SBT 1.0

When you are ready to migrate an existing beta app, here is the full process.

Checklist

#

Step

1

Test locally: sbt run <app-name> — make sure it still runs without errors.

2

Build with SBT 1.0 (omit --beta flag): sbt build-app --app-name <app-name>

3

Wait for the Prefect build job to be built. Check error message in output if it fails.

4

Publish: sbt publish-app <app-name> <version>

5

For each subscriber org, go to their org administration to upgrade their app and then initiate a variant run.

6

Verify variant runs in each org after upgrade… failures can be monitored in Prefect.

The big effort: org-by-org upgrades!

Building and publishing is fast. The slow part is upgrading each subscriber org one at a time. Until a bulk upgrade tool is available, this must be done manually for every org.

Suggestion: time your migrations with MTA work. If you are already touching an app’s configuration for MTA, that is a natural moment to also upgrade it to SBT 1.0.

5. Python Model Improvements

SBT 1.0 introduces a cleaner way to write Python models. You no longer need separate YAML files for each Python model, and you can have multiple models in one file.

New: @model Decorator

Instead of pairing each .py file with a .yaml file, you can now define all model metadata inline using the @model decorator. You can also put multiple models in one .py file.

# Old way: required iris_clean.py + iris_clean.yaml + iris_agg.py + iris_agg.yaml

# New way: one file, two models, no YAML needed

from sbt.models import model
from sbt.types import ModelRunCtx
import pandas as pd

@model(name='iris_clean', materialized='table', type='mapping')
def clean_data(session, seek: ModelRunCtx):
    # your logic here
    return df_clean

@model(name='iris_agg', materialized='table', type='output')
def iris_agg(session, seek: ModelRunCtx):
    df = seek.models['iris_clean']
    return df.groupby('target').mean()

This is optional for new apps. Existing apps with separate YAML files continue to work.