Skip to content

PlanetScale — Support's notes from the field

Summary

Mike Stojan's 2023-01-11 PlanetScale Support post is a customer-facing tutorial covering the three most common issues the PlanetScale Support team sees in the field: SSL/TLS certificate verification errors, data-import complications, and hard-timeout violations. The architectural density is modest (the bulk is a Let's Encrypt CA primer and boilerplate SSL/TLS advice aimed at developers connecting from third-party tools like Retool and Google Data Studio) but three durable operational disclosures justify ingest as a borderline Tier-3 scope-pass:

  1. PlanetScale's hard timeouts — 20 s transaction, 900 s query — with their specific error messages and the documented per-session workaround (set workload='olap').
  2. The import machinery's _vt metadata database — a temporary MySQL database PlanetScale's importer creates on the customer's current primary to track replication state, plus the observable failure mode when it isn't cleaned up after an aborted import.
  3. The source-MySQL configuration prerequisites for PlanetScale Database Imports — gtid_mode, binlog_format, and expire_logs_days / binlog_expire_logs_seconds must all be settable by the user, which is a constraint some managed-MySQL offerings impose restrictions on.

Stojan is not one of PlanetScale's canonical deep-internals voices (Dicken, Burlacu, Lambert, Noach) — this is a support-team field-notes post — but the operational-limit canonicalisation (20 s / 900 s with verbatim error messages, _vt temp database as observable state, OLAP-mode escape hatch) is durable wiki content that the existing Lord petabyte-scale post and Raju 2021 launch post don't cover at this altitude.

Key takeaways

  1. PlanetScale enforces a 20-second transaction timeout and a 900-second query timeout as hard limits, with specific vttablet error messages for each:
  2. Transaction: vttablet: rpc error: code = Aborted desc = transaction <transaction>: in use: in use: for tx killer rollback (CallerID: planetscale-admin)
  3. Query: target: example-db.-.primary: vttablet: rpc error: code = Canceled desc = (errno 2013) due to context deadline exceeded, elapsed time: 15m0.002989349s, killing query ID 65535 (CallerID: <id>)

These are "deliberately set timeouts that exist for performance reasons and to encourage good application design", not configurable ceilings. Hitting them is usually an application-design problem — "it's rather the user's application keeping the transaction open while handling other tasks such as data manipulation or sorting instead of closing the transaction first" — and loops (while, until, for) are particularly susceptible. (Source: sources/2026-04-21-planetscale-supports-notes-from-the-field)

  1. set workload='olap'; is the documented per-session escape hatch that lifts PlanetScale's configured timeouts, but comes with an explicit "do not use unless you must" framing: "it can cause rather drastic side effects such as a workload consuming all available resources or blocking other important, short-lived queries or transactions from completing, or overloading a database up to a point where it goes into an unrecoverable state and where manual intervention is needed." The workload setting cannot be changed globally and resets to OLTP when the session closes — it's a deliberate per-statement opt-in with operator friction. Canonicalises OLTP-vs-OLAP on PlanetScale as a per-session runtime toggle, not a separate cluster. (Source: sources/2026-04-21-planetscale-supports-notes-from-the-field)

  2. PlanetScale's documented alternatives to raising the timeout stack as a recommendation ladder: optimistic locking for simple workloads, Sagas for complex workloads, PlanetScale Insights for query-tuning telemetry, and data-integration engines (Airbyte, Stitch, Datadog integration) for ETL workloads that would otherwise exceed the timeout. First canonical wiki citation of saga + optimistic-locking as the PlanetScale-documented workarounds for the hard-timeout envelope. (Source: sources/2026-04-21-planetscale-supports-notes-from-the-field)

  3. PlanetScale Database Imports uses MySQL's binlog replication under the hood and requires a controllable set of server-side knobs on the source MySQL: gtid_mode, binlog_format, and the binlog-retention knobs expire_logs_days and/or binlog_expire_logs_seconds. "You will need to be able to change your MySQL server's gtid_mode, its binlog_format, as well as its expiration times … otherwise you will not be able to use our importer." Operational constraint that restricts which source-MySQL offerings can participate — some managed services lock down one or more of these. Canonical wiki statement that PlanetScale's import path is snapshot-plus-binlog-catchup on top of GTID positioning. (Source: sources/2026-04-21-planetscale-supports-notes-from-the-field)

  4. The importer's observable metadata surface is a temporary _vt database on the customer's current primary, created at import start and cleaned up on successful completion: "to be able to import your database, we create a temporary database named _vt on your current primary. We clean it up automatically when finishing up the import, but if you decide to start over, we cannot automatically detect that." When an import is aborted mid-flight, the customer-visible error on retry is Error checking server configuration: found existing Vitess state on the external database, and the operator manual-intervention is to DROP DATABASE _vt on the current primary. First wiki canonicalisation of the _vt temp database as observable import-pipeline state — a detail the Lord 2026-02-16 petabyte-scale post doesn't name and Raju's 2021 launch post treats as internal implementation detail. (Source: sources/2026-04-21-planetscale-supports-notes-from-the-field)

  5. PlanetScale's importer frames itself as a safer alternative to cat backup.sql | pscale shell because the latter "is easy to quickly overwhelm your database with heavy IO operations if you're not careful. A huge influx in concurrent writes to your database will lead to a degraded service." Because the importer uses binlog replication with PlanetScale registered as a replica, the cut-over is controllable and cross-traffic writes to the customer's source primary are still routed correctly until explicit promotion: "You can point your application to your PlanetScale database once it's been registered as a replica. We will route any writes back to the primary until the point where you have elevated PlanetScale to become the primary itself." Canonical framing of bulk-load as an IO-concurrency-control problem, with replication-based ingest as the operator-safe alternative. (Source: sources/2026-04-21-planetscale-supports-notes-from-the-field)

  6. Important caveat on the importer: schema changes do not replicate in either direction during an ongoing import. "One important caveat is that schema changes do not get replicated between databases in either direction. Please make sure not to execute any DDL (Data Definition Language) operations such as CREATE, DROP, ALTER or TRUNCATE while the import is ongoing." A freeze-point constraint on the source schema during the replication-catchup window — orthogonal to the row-level cutover freeze at promotion time. (Source: sources/2026-04-21-planetscale-supports-notes-from-the-field)

  7. PlanetScale's TLS certificate is issued by Let's Encrypt (ISRG Root X1) — a nonprofit CA that has issued certificates for over 300 million websites. Most client-side "unable to verify certificate" failures are not PlanetScale-side issues but missing CA roots on the client OS (Linux without ca-certificates package; misconfigured driver CA paths; old libssl; libraries compiled without SSL support). Operationally important hard rule: "Disable SSL/TLS certificate verification … will make your connection susceptible to man-in-the-middle attacks. … You will never ever need to [create your own CA and SSL certificates] when using PlanetScale!" Third-party tools (Retool, Google Data Studio) that expose CA Cert fields should receive Let's Encrypt's ISRG Root X1 .pem, not a self-signed certificate. (Source: sources/2026-04-21-planetscale-supports-notes-from-the-field)

Systems

  • PlanetScale — managed Vitess/MySQL vendor; SaaS target of this support field-notes post.
  • Vitess — underlying MySQL-sharding substrate; source of the vttablet error messages and the importer's VReplication substrate.
  • MySQL — the source database for imports; the gtid_mode, binlog_format, and expire_logs_days configuration knobs must all be mutable.
  • PlanetScale Insights — recommended as the query-tuning telemetry lens for finding transactions and queries that approach the hard timeouts.

Concepts

  • PlanetScale hard transaction/query timeouts (new) — 20 s transaction, 900 s query, set workload='olap' per-session escape hatch, verbatim vttablet error messages, operator recommendation ladder (optimistic locking → sagas → Insights → Airbyte/Stitch/Datadog for ETL).
  • OLTP vs OLAP — canonical workload-archetype distinction; this post reinforces that on PlanetScale the OLAP toggle is per-session at the query layer (set workload='olap';), not a separate engine. "The workload cannot be changed globally, and it will reset to OLTP after you have closed the session."
  • Online database import — PlanetScale Database Imports use MySQL binlog replication; the _vt temp database and gtid_mode/binlog_format/retention knobs are the source-side observable surface.
  • Binlog replication — substrate of the import path; customer points their app at PlanetScale once it's registered as a replica, and writes are routed back to the source primary until explicit promotion.
  • GTID position — source-MySQL must have gtid_mode enabled for the PlanetScale importer to track replication state.

Patterns

  • Snapshot-plus-catchup replication — the import mechanism; binlog-based catchup after an initial copy phase, with PlanetScale registered as a MySQL replica throughout.
  • Read replica as migration source — not directly discussed, but implicit in the operator recommendation to avoid cat backup.sql | pscale shell in favour of the importer's controlled throughput.

Operational numbers

  • 20 seconds — transaction timeout. Hit message: in use: for tx killer rollback (CallerID: planetscale-admin).
  • 900 seconds (15 minutes) — query timeout. Hit message: context deadline exceeded, elapsed time: 15m0.002989349s, killing query ID 65535.
  • _vt — temp database name on customer primary; created by importer at start, cleaned up on success, DROP DATABASE _vt required on retry after aborted import.
  • ISRG Root X1 — Let's Encrypt's root CA serving PlanetScale's TLS certificate; 300M+ websites issued.
  • CA path by OS: /etc/ssl/cert.pem (macOS); /etc/ssl or /etc/pki (Linux); CryptoAPI store (Windows).
  • Required source-MySQL knobs for import: gtid_mode (controllable), binlog_format (controllable), expire_logs_days and/or binlog_expire_logs_seconds (controllable).

Caveats

  • Tutorial/support voice, not deep-internals. Mike Stojan is on the PlanetScale Support team (Customer Engineering + Cloud Support). Not a Dicken / Burlacu / Lambert / Noach default-include byline. Ingested on substance (specific numbers + _vt observability + OLAP escape hatch), not voice.
  • Borderline scope. First two-thirds of the post is SSL/TLS primer (Let's Encrypt, CA root stores by OS, don't-disable-certificate-verification warnings, Retool screenshot). The wiki-durable contributions are concentrated in the final third (imports + hard timeouts). Architectural density ~30–40% of body.
  • Timeouts presented as immutable. "We are looking into ways to lift or at least extend these, but for the time being, these need to be considered hard timeouts." Date of this remark is 2023-01-11; PlanetScale may have relaxed these in the interim — the wiki canonicalisation is the 2023 operational snapshot, not a current-state claim.
  • OLAP escape-hatch warning hand-waves mysqld configuration. The "workload mode" toggle is a Vitess / vttablet construct, not a MySQL server directive — the post doesn't explain that OLAP mode causes vttablet to skip its query-deadline enforcement, which is why the 900 s ceiling lifts. A reader coming in without Vitess context might assume it's a MySQL session variable.
  • No diagrams. The single image is a Retool connection- test screenshot.
  • No production numbers beyond the timeouts themselves. The recommendation ladder is qualitative — "start with a low concurrency rate and to be conservative with increases"; no observed import-throughput figures, no concurrency breakpoints, no queue-length observations.
  • _vt database is observable but the remediation is brittle. "If you decide to start over, we cannot automatically detect that. In that case, you will need to drop the _vt database from the current primary first before you can reattempt the import." Canonical instance of manual-operator-intervention as the failure mode for an otherwise-automated import pipeline — worth noting as a counterpoint to the "no dumping, no restoring from backup, just give us a connection" framing in the 2021 launch post.
  • Import ignores DDL in both directions. CREATE / DROP / ALTER / TRUNCATE on source or destination during an import are silently not replicated — a class of quiet-failure that can yield schema drift at cutover.

Source

Last updated · 470 distilled / 1,213 read