1. MooseStack
  3. Migrate
  5. Migration Types

Migration Types

This guide provides detailed examples of different migration types. For the complete workflow overview, see Migrations & Planning.

Adding New Infrastructure Components

Adding New Infrastructure Components

Keep in mind that only the modules that you have enabled in your moose.config.toml will be included in your migrations.

[features]olap = truestreaming_engine = trueworkflows = true

New OLAP Table or Materialized View

interface AnalyticsSchema {  id: string;  event_type: string;  timestamp: Date;  user_id: string;  value: number;} export const analyticsTable = new OlapTable<AnalyticsSchema>("Analytics");

Migration Result: Creates ClickHouse table Analytics with all fields from AnalyticsSchema

Ensure OLAP is enabled

If you have not enabled the olap feature flag, you will not be able to create new OLAP tables.

[features]olap = true
Understanding OLAP Migrations

Check out the OLAP migrations guide to learn more about the different migration modes.

New Stream

export const userEvents = new Stream<UserSchema>("UserEvents");export const systemEvents = new Stream<SystemEventSchema>("SystemEvents");

Migration Result: Creates Redpanda topics UserEvents and SystemEvents

Ensure Streaming Engine is enabled

If you have not enabled the streaming_engine feature flag, you will not be able to create new streaming topics.

[features]streaming_engine = true

Schema Modifications

Adding Fields

// Beforeinterface UserSchema {  id: string;  name: string;  email: string;} // Afterinterface UserSchema {  id: string;  name: string;  email: string;  age: number;  created_at: Date;  is_active: boolean;}

Migration Result: Adds age, created_at, and is_active columns to existing table

Removing Fields

// Beforeinterface UserSchema {  id: string;  name: string;  email: string;  age: number;  deprecated_field: string;  // Will be removed} // Afterinterface UserSchema {  id: string;  name: string;  email: string;  age: number;}

Migration Result: Drops deprecated_field column (data permanently lost)

Type Changes

// Beforeinterface UserSchema {  id: string;  name: string;  email: string;  score: number;  // Will change to string} // Afterinterface UserSchema {  id: string;  name: string;  email: string;  score: string;  // Changed from number}

Migration Result: Alters score column type (data converted if compatible)

Removing Infrastructure

// Beforeexport const usersTable = new OlapTable<UserSchema>("Users");export const analyticsTable = new OlapTable<AnalyticsSchema>("Analytics");export const deprecatedTable = new OlapTable<DeprecatedSchema>("Deprecated"); // After (remove deprecated table)export const usersTable = new OlapTable<UserSchema>("Users");export const analyticsTable = new OlapTable<AnalyticsSchema>("Analytics");

Migration Result: Drops Deprecated table (all data lost)

Working with Local Infrastructure

There are two main ways to inspect your local infrastructure to see how your migrations are applied:

Using the CLI

Run moose ls to see the current state of your infrastructure:

# Verify object definitions
moose ls

Connecting to your local infrastructure

You can also connect directly to your local infrastructure to see the state of your infrastructure.

Credentials Located in Project Config

All credentials for your local infrastructure are located in your project config file (moose.config.toml).

Connecting to ClickHouse

# Using clickhouse-client
clickhouse-client --host localhost --port 18123 --user panda --password pandapass --database local
 
# Using connection string
clickhouse-client "clickhouse://panda:pandapass@localhost:18123/local"

Connecting to Redpanda

# Using kafka-console-consumer
kafka-console-consumer --bootstrap-server localhost:19092 --topic UserEvents --from-beginning
 
# Using kafka-console-producer
kafka-console-producer --bootstrap-server localhost:19092 --topic UserEvents

Viewing Temporal Workflows

Navigate to http://localhost:8080 to view the Temporal UI and see registered workflows.

Gotchas:

Your dev server must be running to connect to your local infrastructure.

moose dev

Only the modules that you have enabled in your moose.config.toml will be included in your migrations:

[features]olap = true # Required for OLAP Tables and Materialized Viewsstreaming_engine = true # Required for Streamsworkflows = true # Required for Workflows and Tasks

On this page

Adding New Infrastructure ComponentsNew OLAP Table or Materialized ViewNew StreamSchema ModificationsAdding FieldsRemoving FieldsType ChangesRemoving InfrastructureWorking with Local InfrastructureUsing the CLIConnecting to your local infrastructureGotchas:
FiveonefourFiveonefour
Fiveonefour Docs
MooseStackTemplatesGuides
Release Notes
Source523
  • Overview
Build a New App
  • 5 Minute Quickstart
  • Browse Templates
  • Existing ClickHouse
Add to Existing App
  • Next.js
  • Fastify
Fundamentals
  • Moose Runtime
  • MooseDev MCP
  • Data Modeling
Moose Modules
  • Moose OLAP
  • Moose Streaming
  • Moose Workflows
  • Moose APIs & Web Apps
Deployment & Lifecycle
  • Moose Migrate
  • Moose Deploy
Reference
  • API Reference
  • Data Types
  • Table Engines
  • CLI
  • Configuration
  • Observability Metrics
  • Help
  • Release Notes
Contribution
  • Documentation
  • Framework
interface AnalyticsSchema {  id: string;  event_type: string;  timestamp: Date;  user_id: string;  value: number;} export const analyticsTable = new OlapTable<AnalyticsSchema>("Analytics");
export const userEvents = new Stream<UserSchema>("UserEvents");export const systemEvents = new Stream<SystemEventSchema>("SystemEvents");
// Beforeinterface UserSchema {  id: string;  name: string;  email: string;} // Afterinterface UserSchema {  id: string;  name: string;  email: string;  age: number;  created_at: Date;  is_active: boolean;}
// Beforeinterface UserSchema {  id: string;  name: string;  email: string;  age: number;  deprecated_field: string;  // Will be removed} // Afterinterface UserSchema {  id: string;  name: string;  email: string;  age: number;}
// Beforeinterface UserSchema {  id: string;  name: string;  email: string;  score: number;  // Will change to string} // Afterinterface UserSchema {  id: string;  name: string;  email: string;  score: string;  // Changed from number}
// Beforeexport const usersTable = new OlapTable<UserSchema>("Users");export const analyticsTable = new OlapTable<AnalyticsSchema>("Analytics");export const deprecatedTable = new OlapTable<DeprecatedSchema>("Deprecated"); // After (remove deprecated table)export const usersTable = new OlapTable<UserSchema>("Users");export const analyticsTable = new OlapTable<AnalyticsSchema>("Analytics");