Skip to main content
Turbo is the recommended successor to Mirror. For a complete feature-by-feature comparison, see Mirror vs. Turbo pipelines. This page walks you through the practical steps to migrate an existing Mirror pipeline.
In most cases (around 95%) a Mirror pipeline can be mapped 1:1 onto a Turbo pipeline. The remaining cases involve features that Turbo does not currently support — see When you can’t migrate yet before you start.

​
Before you start

  • Install the latest CLI. The Turbo commands live under goldsky turbo — see the Turbo CLI reference and the installation guide.
  • Read Mirror vs. Turbo pipelines so you know which sources, transforms, and sinks change shape.
  • Export your existing Mirror pipeline definition with goldsky pipeline get <name> so you have the YAML to translate.

​
When you can’t migrate yet

Turbo doesn’t (yet) replace every Mirror feature. Stay on Mirror if your pipeline depends on: If none of those apply, you’re good to migrate.

​
Step 1: Translate the YAML

Turbo’s YAML is similar to Mirror’s but drops a few fields and renames others.

​
Top-level changes

MirrorTurbo
apiVersion: 3 (required)Remove — Turbo doesn’t use apiVersion
resource_size: s | m | l | xl | xxlSame — top-level resource_size
name, descriptionSame
See the full Turbo schema in Pipeline configuration.

​
Sources

Both products use type: dataset, but Turbo adds start_block / end_block for block ranges and uses start_at: latest | earliest for the starting position. Mirror’s source-level Fast Scan filter: carries over to Turbo with the same SQL WHERE-clause syntax — see Fast scan in Turbo EVM sources. See also:

​
Transforms

  • SQL transforms — Turbo uses Apache DataFusion instead of Flink. Most Mirror SQL works as-is; we’ve backported the common Flink functions as UDFs. A handful of less-used functions need rewrites — check Turbo SQL functions reference for the supported list.
  • External HTTP handlers — see HTTP handler transforms. secret_name, one_row_per_request, payload_version, schema_override, batch_size, and batch_flush_interval are all supported in Turbo. Mirror’s payload_columns is the one option that doesn’t carry over.
  • New transforms you can adopt — TypeScript/WASM transforms (note the sandbox constraints — no Node APIs, no fetch, no async/await), dynamic tables, and throttle.

​
Sinks

Most sink types have direct equivalents. Watch out for these specific renames and reshapes:
  • PostgreSQL secrets — Mirror uses a JSON-object secret (type, host, port, …). Turbo uses a Postgres connection string (postgres://user:pass@host:port/db). Recreate the secret with goldsky secret create. See Turbo Postgres sink and Mirror secrets.
  • SQS — Mirror uses type: sqs; Turbo uses type: sqs_sink and lets you pass access_key_id / secret_access_key inline. See Turbo SQS sink.
  • S3 — In Mirror this goes through the object storage sink; Turbo has a native s3_sink.
  • Kafka — Turbo’s Kafka sink adds data_format (required), topic_partitions, and message_max_bytes. schema_registry_url lives in the Kafka secret, not the sink config.
  • Webhooks — Turbo’s webhook sink supports secret_name (with httpauth secrets), one_row_per_request, payload_version, and primary_key.
  • Google Cloud Pub/Sub — Turbo has a native Pub/Sub sink; Mirror does not.

​
U256 / I256 values

EVM datasets contain uint256 / int256 values (e.g. value, balance, amount). The Postgres sink writes these as NUMERIC(78, 0) — see 256-bit integers in the Postgres sink. If you have existing Postgres tables created by a Mirror pipeline with a different column type, you’ll need to migrate the column or drop and let Turbo recreate the table. For the full matrix and per-sink tuning options see Mirror vs. Turbo § Sinks and § Sink tuning parameters.

​
Step 2: Validate the Turbo definition

Once you have a translated YAML file: 
goldsky turbo validate path/to/pipeline.yaml
Then use live inspect to see the data flowing through each step before you point it at production sinks: 
goldsky turbo inspect path/to/pipeline.yaml
A quick sanity check is to swap the real sink for the blackhole sink during inspection.

​
Step 3: Choose a cutover strategy

Mirror’s processed-data state does not carry over to Turbo, so plan for one of the strategies below depending on how much double-write or downtime you can tolerate. Turbo itself is at-least-once with checkpointing, so make sure your sink is set up to deduplicate (typically via primary_key) before you cut over. Best when your sink can tolerate duplicate writes (e.g. Postgres with primary keys, ClickHouse with ReplacingMergeTree, or any idempotent webhook).
  1. Deploy the Turbo pipeline with start_at: latest in every dataset source so it begins at the chain tip.
  2. Leave the Mirror pipeline running.
  3. Once the Turbo pipeline is healthy and you see writes landing in your sink, pause the Mirror pipeline with goldsky pipeline pause <name>.
  4. After a buffer period to confirm Turbo is stable, delete the Mirror pipeline.
You may see a small window of duplicate inserts during the overlap; upserts or unique constraints will absorb them.

​
Option B — Block-number cutover

Best when your sink cannot dedupe and you want a clean handoff.
  1. Pick a future block X for the cutover.
  2. Edit the Mirror pipeline so it stops at block X (add a block-number filter in your SQL transform — Mirror sources don’t support end_block).
  3. Deploy the Turbo pipeline configured to start at block X+1 (use start_block on the source — see EVM sources).
  4. Once Mirror reaches block X and Turbo picks up at X+1, pause and remove the Mirror pipeline.

​
Option C — Cold cutover (downtime accepted)

If a short gap in your sink is fine, pause Mirror, deploy Turbo with start_at: latest, and accept the brief gap. Simplest, but you lose the blocks in between.

​
Step 4: Decommission Mirror

After the Turbo pipeline has been running cleanly for your chosen verification window: 
goldsky pipeline delete <mirror-pipeline-name>
Mirror secrets can stay in place if they’re shared, or be removed via goldsky secret delete.

​
Common gotchas

  • Solana, Bitcoin, Stellar, and NEAR sources were removed from Mirror — they’re Turbo-only now. See Solana, Bitcoin, Stellar, and NEAR.
  • CLI namespace — every command moves from goldsky pipeline ... to goldsky turbo .... Update scripts and CI accordingly.
  • Job mode — if your migration is actually a one-time backfill, consider Turbo job mode instead of a streaming pipeline.

​
Get help

If you hit anything that doesn’t translate cleanly, reach out to support or your Goldsky contact — we’re actively closing the remaining gaps and happy to help with the rewrite. For background on what differs between the two products, see Mirror vs. Turbo pipelines and the Turbo FAQ.