Migrate from Classic with connectors

Follow this path if your project ingests data through a managed connector (S3, GCS, Kafka, or DynamoDB). Connectors are configured differently in Forward, so connector-backed projects need a few extra checks before you migrate.

If your project ingests data only through the Events API, direct HTTP requests, or another method that doesn't rely on a managed connector, follow Migrate without connectors instead.

Migration is permanent and cannot be reversed. After deploying with Forward, you cannot switch your workspace back to Classic.

Migrating with connectors is only supported for DynamoDB use cases. For all other connectors, follow Migrate from Tinybird Classic or contact Tinybird support.

How connectors change in Forward

In Forward, resources are defined as files and deployed as a project. A connector is represented by two kinds of file:

  • A .connection file that holds the connector settings (for example, the IAM role and region for DynamoDB).
  • One .datasource file per ingested table or topic, which references the connection by name and carries the import settings.

tb --cloud pull from the Forward CLI writes these files for you from the Classic workspace, so most of the migration is auditing the pulled files and confirming the AWS or Kafka side still matches.

Migrate a DynamoDB-only project

If DynamoDB is the only connector in your workspace, the automated CLI migration works end to end. A tb --cloud pull followed by tb migrate-to-forward is enough; you don't need the feature-flag flow.

Prerequisites

Before starting, make sure:

  • You are using the latest Forward CLI. See Install Tinybird.
  • The Classic workspace has no active branches except main, and no rollback releases except the live release. If you cannot remove rollback releases, contact Tinybird support.
  • The DynamoDB tables still have the AWS features the connector requires: DynamoDB Streams and point-in-time recovery (PITR) enabled, an S3 export bucket, and an IAM role Tinybird can assume to read the table and stream and read/write the export bucket.
1

Authenticate to your workspace

Log in to your workspace with the Classic CLI:

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

Pull your project

Download your datafiles from Tinybird Cloud with the Forward CLI:

tb --cloud pull

For a workspace with a DynamoDB connector, this writes a connection file under connections/ and the DynamoDB-backed data sources under datasources/:

connections/
  ddb_orders.connection
datasources/
  orders.datasource
3

Audit the pulled DynamoDB files

Open each pulled .connection file and confirm it has the connector type, role ARN, and region:

connections/ddb_orders.connection
TYPE dynamodb
DYNAMODB_ARN arn:aws:iam::123456789012:role/tinybird-dynamodb-role
DYNAMODB_REGION us-east-1

Then open each DynamoDB-backed .datasource file and confirm it references the connection, table ARN, and export bucket, and keeps the ReplacingMergeTree settings that DynamoDB updates and deletes rely on:

datasources/orders.datasource
ENGINE "ReplacingMergeTree"
ENGINE_SORTING_KEY "<partition_key>, <sort_key>"
ENGINE_VER "_timestamp"
ENGINE_IS_DELETED "_is_deleted"

IMPORT_CONNECTION_NAME 'ddb_orders'
IMPORT_TABLE_ARN 'arn:aws:dynamodb:us-east-1:123456789012:table/orders'
IMPORT_EXPORT_BUCKET 'my-dynamodb-export-bucket'

Use only the S3 bucket name in IMPORT_EXPORT_BUCKET, not an s3:// URI. Treat IMPORT_TABLE_ARN and IMPORT_EXPORT_BUCKET as immutable: the first Forward deployment should preserve the existing DynamoDB binding, not change it.

4

Migrate to Forward

Run the migration command:

tb migrate-to-forward

This deletes branches and releases, runs a deploy check, generates a tinybird.config.json file, switches the workspace to Forward, and deploys it. After it finishes, query a few DynamoDB-backed endpoints and confirm ingestion continues.

If your workspace uses AWS PrivateLink for private networking, the migration doesn't change it. Private networking is configured at the workspace and region level, not in the datafiles you migrate, and the workspace keeps the same region. The DynamoDB connector reaches AWS through the same IAM role and endpoints before and after migration.

Optionally store the role ARN as a secret

When you create a DynamoDB connection natively in Forward, DYNAMODB_ARN is stored as a secret and the connection file references it with tb_secret(...). The tb migrate-to-forward step does not do this conversion: it carries the role ARN through as the plain value you saw in the pulled connection file.

The ARN doesn't need to be a secret, so you can leave it inline. If you'd prefer to manage it as a secret to match how Forward creates DynamoDB connections, set the secret in Cloud:

tb --cloud secret set dynamodb_role_arn_ddb_orders 'arn:aws:iam::123456789012:role/tinybird-dynamodb-role'

Then reference it from the connection file and deploy:

connections/ddb_orders.connection
TYPE dynamodb
DYNAMODB_ARN {{ tb_secret("dynamodb_role_arn_ddb_orders") }}
DYNAMODB_REGION us-east-1

Use one secret per IAM role. If several connections intentionally use the same role they can share a secret, but one secret per connection makes rotation and review easier.

Other connectors and mixed projects

If your workspace uses S3, GCS, or Kafka connectors, the same shape applies: tb --cloud pull writes the .connection and .datasource files, and you audit them before migrating. Some details differ, for example Kafka has deprecated settings to update, and S3 connectors change how AWS External IDs are seeded. See External ID changes for AWS integrations before migrating an S3 connector or Sink.

If tb migrate-to-forward reports changes you can't resolve, fix them in Classic, pull again, and rerun the migration. For projects with connector configurations the automated flow can't reconcile, follow the manual deploy-check and feature-flag flow in Migrate from Tinybird Classic or contact Tinybird support.

Next steps

Updated
Looking for Classic docs?