Migrate from Tinybird Classic¶

Tinybird Forward introduces a new way of working with your data projects, with changes to APIs and CLI that may be incompatible with Tinybird Classic. If you're starting a new project, see the Get started guide.

Why migrate to Forward¶

Forward is a significant evolution of the Tinybird developer experience. Migrating unlocks the following benefits:

• Deployments: Project iteration is easier. You ship a new version of the project, and Tinybird handles all the backfills, tables exchanges... automatically. No more tb push datasource_v2 and copy data from datasource_v1.
• Git-native deployments and CI/CD: Every change ships through your repository. Use the built-in CI/CD workflows for automated validation, preview deployments, and safe rollouts to production.
• Local development: Build and iterate against the Tinybird Local container with full parity to Tinybird Cloud. Test changes on your machine before they ever reach a shared environment. And easier to verify in your CI with the local image.
• Faster, simpler testing: Fixture tests make it easier to define realistic scenarios and catch regressions before deploy, replacing the heavier regression and data quality test workflows from Classic.
• Cleaner project structure: First-class connection files, secrets, and generic pipes replace ad-hoc include files and per-environment glue, so projects stay portable and reviewable in code.
• Modern, consistent CLI: A redesigned tb command provides a unified workflow for local development, cloud deployments, and testing, with clearer commands and better feedback.
• AI friendly: Use the agent skills npx skills add tinybirdco/tinybird-agent-skills to teach Tinybird best practices to your coding agent.
• Active development: New features land in Forward first. Classic continues to receive critical fixes, but the roadmap (new connectors, deployment improvements, agent integrations) is Forward-only.

Choose your migration path¶

There are two paths to migrate to Forward, depending on whether your project uses connectors (S3, GCS, Kafka, DynamoDB, and similar):

• Migrate without connectors: Use this path if your project ingests data through the Events API, direct HTTP requests, or any other method that doesn't rely on a managed connector. This is the fastest path and can be run entirely from the CLI.
• Migrate with connectors (coming soon): Use this path if your project uses S3, GCS, Kafka, DynamoDB, or other connectors. Connection configuration changes between Classic and Forward, so these projects need additional steps. Follow the detailed migration guide below.

If you're unsure, check your workspace for connection resources (Kafka, S3, GCS, or DynamoDB data sources). If you have any, follow the migration steps below.

Considerations before migrating¶

Before migrating your workspace from Tinybird Classic, understand these key differences in Forward:

• Development is files based. You edit the .pipe, .datasource... in a Cloud branch or locally using the Tinybird Local container. Check Development Workflow for more details.
• Before starting the migration, remove all the branches that are not the main one. That can be done from the UI or using the CLI.
• Contact the Tinybird support team if you cannot remove any existing rollback releases. Only the live release must remain to proceed with the migration.
• If you are not doing the automated migration with the CLI flow tb migrate-to-forward, contact Tinybird support team to enable a feature flag to enable the migration to Forward.
• The following features have limitations or require changes:

If these changes work for your use case, continue reading to learn how to migrate.

External ID changes for AWS integrations¶

In Classic, Tinybird uses the workspace ID as the seed for generating External IDs, while in Forward it uses the connection name. This means the same connection will have a different External ID after migration.

Update AWS Trust Policy¶

To get the new External ID for your connection, access:

https://<your_host>/v0/integrations/s3/policies/trust-policy \
  ?external_id_seed={CONNECTION_NAME} \ # Replace with your connection name
  &token={YOUR_ADMIN_TOKEN} # Replace with your admin token

This returns a Trust Policy with the new External ID. Add this new External ID to your existing Trust Policy's sts:ExternalId array to maintain access during and after migration.

Additional S3 Sinks permission¶

If you use S3 Sinks, add the s3:GetBucketLocation permission to your AWS Access Policy. This requirement allows connections to work with buckets across multiple regions without specifying the region when creating the connection, making it more flexible for multi-region deployments.

Migrate your workspace¶

curl https://tinybird.co | sh

# For Classic CLI
uvx --from tinybird-cli@latest tb

# For Forward CLI
uvx --from tinybird@latest tb

# Add to .bashrc or .zshrc
alias tb-classic="path/to/classic/tb"
alias tb-forward="path/to/forward/tb"

uvx --from tinybird-cli@latest tb auth --interactive

uvx --from tinybird@latest tb --cloud pull

uvx --from tinybird@latest tb --cloud deploy --check

* No changes to be deployed
* No changes in tokens to be deployed

NODE n
SQL >
    SELECT 'forward'

TYPE endpoint

uvx --from tinybird@latest tb init --type cli --dev-mode manual --folder .

uvx --from tinybird@latest tb --cloud deploy

uvx --from tinybird@latest tb --cloud open

The migration is complete! Your project will continue working as expected; you do not need to change your tokens, endpoint URLs, or anything else.

Common migration errors¶

Common errors and changes include (but are not limited to):

Missing connection files¶

In Forward, .connection files are used to store your connector details.

You need to create .connection files to enable your connections to Kafka, S3, or GCS. If you manually pulled your datafiles, the .connection files were created, but they are empty.

See Connectors for more information about the syntax.

Kafka settings have been deprecated¶

Some settings in the Kafka connector have been deprecated. You need to update your Kafka .connection file to use the most up-to-date Kafka settings.

Replace include files¶

Include files are not supported in Forward. The fix depends on your use of include files:

• If you use include files to store secrets, use tb secret to set secrets in your local and cloud environments.
• If you use include files to reuse query logic, you can create generic pipes and reference them in your endpoint pipes. For example:

NODE apply_params
SQL >
    %
    SELECT * FROM my_datasource
    WHERE
        tenant_id = {{ String(tenant) }}
        AND date BETWEEN {{ Date(start_date) }} AND {{ Date(end_date) }}

NODE endpoint
SQL >
    %
    SELECT * FROM reusable_filters

TYPE endpoint

Add TYPE endpoint to your .pipe files¶

You need to add TYPE endpoint to your .pipe files so they can be published as API endpoints.

If you omit the TYPE instruction, the pipe will be a generic pipe that is not publicly exposed.

NODE my_node
SQL >
    SELECT * FROM my_datasource

TYPE endpoint

Next steps¶

• Learn about working with Forward in the Forward documentation.