Skip to content

PlanetScale — Bring your data to PlanetScale

Summary

Phani Raju's 2021 feature-launch post is the earliest public architectural description of PlanetScale's zero-downtime external-MySQL import feature. It predates the much more detailed 2026-02-16 Matt Lord petabyte-scale post by ~4.5 years and canonicalises on the wiki two primitives that the later post treats as assumed background: Vitess unmanaged tablet as the mechanism by which PlanetScale connects to a customer's external MySQL without taking over its process lifecycle, and the database-as-data-router cutover shape in which the destination transparently forwards writes back to the source during the validation phase, then the direction is reversed at cutover. The post also gives the canonical user-visible surface: "no dumping your data, no restoring from backup — just give us a connection."

Key takeaways

  • Unmanaged tablet is the composition primitive. Vitess's unmanaged tablet feature — a Vitess tablet that attaches to an externally- managed MySQL (one whose process, storage, and backups are operated by someone else) — is what lets PlanetScale bring an external customer MySQL into the Vitess control plane without rehoming the MySQL itself. "PlanetScale's data imports are powered by Vitess's Unmanaged Tablet technology." The 2026-02-16 Matt Lord deep-dive assumes this as background; the 2021 post is the canonical wiki attribution. (Source: the post body.)

  • Prerequisites, stated explicitly. Two operational preconditions: "credentials for a user who has read and write permissions to your database, and you will need to have binary logs enabled." These are what every downstream replication-based migration tool needs — replicating permissions + durable CDC stream. Canonical preflight list. (Source: the post body.)

  • Pre-copy schema-compatibility gate. Before the row copy starts, PlanetScale runs a schema-compatibility check and surfaces any issues up front: "We will notify you of any schema incompatibility or connection errors that might interfere with using PlanetScale." This is the static-validation analogue of VDiff — shift the discovery of migration-breaking issues as early in the timeline as possible, before hours-to-days of copy work is spent. (Source: the post body.)

  • Copy + binlog-replication is the data-motion shape. Canonical two-phase statement: "PlanetScale will connect to your database and begin copying over the schema and data from your target database automatically, writing it in chunks back to PlanetScale … After the initial data copy is complete, we will keep PlanetScale's database in sync with your database by utilizing Binary Log File replication." This is patterns/snapshot-plus-catchup-replication expressed at the product-launch altitude — the Matt Lord 2026 post gives the exact GTID + lock-tables mechanism underneath. (Source: the post body.)

  • Database-as-data-router is the validation shape. The load-bearing novel claim in the post: during the validation phase, the customer points their application at PlanetScale while the source MySQL is still the authoritative write target. PlanetScale transparently routes writes back to the source over the same replication channel, and they flow back into PlanetScale via ongoing replication. "This works because your new PlanetScale database is also acting as a 'data router'. Queries will be served by PlanetScale with writes transparently routed to your existing database, and then replicated back to PlanetScale using Vitess' powerful Routing Rules." Canonical wiki formulation of the database-as-data-router pattern — the destination terminates the application's wire protocol, routes reads locally, and routes writes back to the legacy primary. Distinct from the 2026 MoveTables SwitchTraffic design, where cutover is an atomic routing-rule flip with no interim bidirectional phase. (Source: the post body.)

  • The stated business property of the bidirectional phase: "This step of routing your application's reads and writes through PlanetScale allows you to safely validate that your application is fully compatible with PlanetScale without taking downtime and without fragile application-level migration mechanisms like dual writes." The author explicitly contrasts the pattern with dual writes and positions it as the architecturally superior alternative. Canonical wiki statement. (Source: the post body.)

  • Cutover is "Enable primary mode" — a direction reversal, not an atomic swap. "You do this by clicking on the 'Enable primary mode' button in the data import banner. This will reverse the direction of the routing — reads and writes will now go directly to PlanetScale, and we'll replicate any writes and updates back to your original database, to make sure it stays in sync." The 2021 design keeps the external source in sync via reverse replication even after cutover, so rollback is a second direction-reversal click. This is the earliest public documentation of the reverse-replication-for-rollback guarantee that the 2026 post names explicitly. (Source: the post body.)

  • Detach is the explicit tear-down step. "Once you're fully migrated and ready to use PlanetScale forever, we're going to detach your external database from PlanetScale. Click on the 'Detach external database' button and follow the prompts to disconnect PlanetScale from your database. We will delete all connection details from PlanetScale and no longer read/write from/to your external database." Canonical three-stage lifecycle: validate (reads on PS, writes routed back) → primary mode (direction reversed, reverse-replication running) → detach (external database disconnected, credentials deleted). No step is implicit. (Source: the post body.)

Canonical new concepts / patterns / systems

New system page:

  • systems/vitess-unmanaged-tablet — first canonical wiki page on Vitess's unmanaged-tablet feature. The composition primitive that lets Vitess attach to an externally-managed MySQL and make it addressable as a tablet inside a Vitess keyspace. Named explicitly by the 2021 post as the implementation substrate under PlanetScale Imports.

New pattern page:

  • patterns/database-as-data-router — first canonical wiki page on the bidirectional-routing cutover shape. The destination speaks the database wire protocol, terminates the application connection, serves reads locally, and forwards writes back to the legacy primary while the migration is in flight. Direction is reversed at cutover. Distinct from the routing-rule-swap cutover pattern where the flip is atomic and no bidirectional phase exists.

Cross-source continuity

Complements sources/2026-02-16-planetscale-zero-downtime-migrations-at-petabyte-scale on the same architectural programme, four-and-a-half years earlier. The 2026 post describes a more mature design — MoveTables SwitchTraffic performs an atomic routing-rule swap at sub-second cutover — while the 2021 post describes an earlier variant where the destination acts as a transparent write-through proxy during a user-driven validation phase, with cutover as an explicit direction reversal ("Enable primary mode") rather than a sub-second flip. Both share the same underlying primitives (VReplication, binlog-based catch-up, routing rules, reverse replication for rollback) but compose them into different UX shapes. The 2021 post's contribution is canonicalising the unmanaged-tablet substrate and the database-as-data-router pattern that the 2026 post takes as background.

Complements sources/2025-07-01-planetscale-planetscale-for-postgres on the online-import capability axis. The 2025 post announces Postgres online-import as a vendor-agnostic capability; this 2021 post gives the canonical MySQL-side mechanism (unmanaged tablet + VReplication + routing rules). Same capability, different substrate — Postgres does it via logical-replication slots, MySQL does it via unmanaged tablet + binlog.

Complements systems/vitess on the unmanaged-tablet axis. Prior wiki coverage of Vitess has focused on its native sharding + replication primitives; this post canonicalises the interop-with-external-MySQL primitive that lets Vitess's workflow machinery operate against foreign MySQL instances without owning them.

Caveats

  • Product-launch voice, not deep-dive architecture. Details of chunk size, parallelism, primary-key ordering, binlog-retention discipline, failure recovery, and GTID handling are not in this post — they're in Matt Lord's 2026-02-16 deep-dive. The 2021 post is the announcement altitude.
  • No production numbers. No cutover latency, no copy throughput, no customer adoption, no error rates.
  • Illustrative screenshots referenced by relative URLs in the raw file — not fetched.
  • "Primary mode" terminology is the 2021 name for the cutover operation; the 2026 post canonicalises it as MoveTables SwitchTraffic. Same mechanism, different name.
  • Dual-write is framed as strictly inferior to the database-as-data-router approach. This is true in application-level migration — dual writes require the application to know about both databases, which fragments consistency guarantees. The wiki's existing patterns/dual-write-migration page covers dual writes at the DDL-altitude (single database, schema migration) where they are load-bearing. The two patterns live at different altitudes despite sharing a name.

Scope disposition

On-scope Tier-3 — PlanetScale product-launch post with architectural density ~60-70% of body (VReplication + unmanaged tablet + binlog replication + routing rules + reverse replication + detach lifecycle). The launch framing is ~30-40% of body but every framed feature is backed by an architectural primitive disclosure. Clears the Tier-3 bar decisively per companies/planetscale.md skip-rules: while the post is a feature-launch (normally a skip signal for Tier-3), it makes two architectural disclosures (unmanaged tablet as composition primitive, data-router shape as validation phase) that no other PlanetScale post on the wiki canonicalises. The borderline-case test passes overwhelmingly ("Only skip if architecture content is <20% of the body").

Source

Last updated · 319 distilled / 1,201 read