Running on PlanetScale?

PlanetScale deploy requests or branches tangled? We unstick it.

A deploy request from two weeks ago is in conflict with main, someone added a column on a branch that nobody remembers, and the application started throwing errors after a schema change that looked harmless. We walk through the deploy requests, reconcile the branches, and get the schema back to a state that matches what the code expects.

  • Since 2015Fixing technology
  • FreeEstimates
  • US teamReal engineers

planetscale.log

still broken

What it is

PlanetScale at a glance

PlanetScale is a managed database service built on Vitess, the scaling layer that Google and YouTube developed for MySQL. It offers MySQL-compatible databases with horizontal sharding, non-blocking schema changes, and a workflow built around branches and deploy requests that borrows from Git and from code review tools. A developer creates a branch, changes the schema on it, opens a deploy request, and once the request is approved the change is rolled out to the production branch without locking the tables.

The company shut down its free tier in 2024 and has since focused on paid plans with larger database sizes, dedicated metal clusters and PlanetScale Managed, which runs the Vitess stack inside the customer's own cloud account. It is popular with teams that want MySQL semantics, strong online schema change tooling, and a path to horizontal scale, and the usual places people get hurt are deploy request conflicts, the lack of foreign keys in the default configuration, and read-replica lag during heavy writes.

Type
Managed MySQL on Vitess
First released
2021 general availability
License
Proprietary SaaS, Apache 2.0 Vitess core
Maintained by
PlanetScale, Inc.
Typically used for
High-scale web and mobile backends, multi-tenant SaaS, schema-heavy applications that need safe migrations

The honest version

PlanetScale pros and cons

No technology is all upside. This is where PlanetScale earns its place and where it tends to cause trouble.

Where PlanetScale is strong

  • Schema changes without lockingOnline schema changes using the Vitess ghost workflow mean adding or altering columns on a busy table does not freeze the application the way a classic ALTER would.
  • A review workflow for the databaseDeploy requests put schema changes through the same conversation as code pull requests, which catches a lot of accidents that otherwise ship straight to production.
  • Vitess underneathThe same sharding and query routing layer that scales YouTube and Slack is doing the heavy lifting, so horizontal scale is a real option rather than a sales promise.
  • Branches for safe experimentationA branch is a copy of the schema that you can migrate on, test against, and discard, which turns risky migrations into routine ones.
  • Connection scaling built inThe PlanetScale proxy pools connections sensibly, so serverless and edge callers do not blow out the database the way they do on vanilla MySQL.
  • Managed offerings for the paranoidPlanetScale Managed runs the same stack inside your own AWS account, which fits teams that need the data to stay within a specific boundary.

Where PlanetScale bites

  • No foreign keys by defaultVitess historically skipped foreign key enforcement for sharding reasons. Teams coming from classic MySQL assume FKs are there and find out the hard way that referential integrity has to live in the application.
  • Deploy requests conflict with stale branchesA deploy request opened two weeks ago, after main has moved on, needs to be rebased and re-reviewed. Teams that treat it as a one-way form run into conflicts repeatedly.
  • The free tier is gonePlanetScale removed the Hobby plan in 2024, which pushed a lot of small projects elsewhere. New users start on a paid plan from day one.
  • Some SQL is rewritten or blockedVitess reshapes certain cross-shard queries and refuses others outright. Code that worked on vanilla MySQL can hit a query rewriter error that is not obvious from the SQL alone.
  • Costs climb with row reads and storageThe pricing meters row reads, writes and storage separately, which can produce a bill that is hard to predict until you have run a month on the plan.
  • Lock-in through the toolingBranches, deploy requests and the PlanetScale CLI shape how the team works. Moving to another MySQL host is possible but gives up the parts that made the platform attractive in the first place.

Sound familiar?

Common PlanetScale problems we fix

The PlanetScale problems that bring people to us, and what you have once each one is fixed.

schema conflicts with main

A deploy request cannot be deployed

The branch has drifted behind main, or another deploy request landed first and changed one of the same tables. The platform will not deploy until the branch is reconciled, and the fix is a rebase rather than a merge.

Deploy request clean and ready to ship

Error 1205: Lock wait timeout exceeded

Transactions are timing out under load

A long-running transaction holding row locks, or two code paths grabbing rows in a different order, so writers queue behind each other until MySQL gives up.

Transactions short, lock ordering consistent

cross-shard subquery not allowed

Vitess refused a query that worked on classic MySQL

A JOIN or subquery that crosses sharded tables in a way the Vitess query rewriter will not handle. The query returns an error rather than silently doing the wrong thing.

Query shape fits the sharded model

Hobby branch paused after 7 days without a connection

A branch paused and stopped responding

A development branch with no traffic was paused, and the next deploy or test hits a connection error until someone manually resumes it.

Right branch lifecycle for how it is used

Row read units: 2.1B used

Row reads are over the included allowance

A chatty ORM calling the same query many times per request, an unindexed scan on a growing table, or a reporting job hitting the primary instead of a replica.

Reads traced and reduced, bill back on plan

Duplicate entry for key 'users.email'

Unique constraints fire unexpectedly

A migration that deduplicated data on a branch but ran into duplicates on main, or an application that assumes case-insensitive uniqueness when the collation is case-sensitive.

Constraints correct, data cleaned

Read replica lag: 00:04:22

Read replicas have fallen behind

A large write burst, a long-running transaction, or a schema change replicating more slowly than new rows arrive. Applications reading from replicas serve stale data.

Lag monitored, reads routed sensibly

Deploy request: safe migrations would take 00:42:11

A schema change is estimated to take hours

A big index being added to a very large table, with throttling applied to keep the primary responsive. Running it blind in a maintenance window is the risky path.

Migration chunked or scheduled with monitoring

What we do

PlanetScale help, from deploy conflicts to steady operation

Call us for one stuck deploy request, or hand us the whole database platform.

Deploy request rescue
Conflicting, abandoned or long-running deploy requests reconciled against main, with a workflow your team can keep using after we leave.
Schema design on Vitess
Sharding keys, indexes and the honest trade-offs around foreign keys and cross-shard joins, planned for the queries your application actually runs.
Migrations
Moving onto PlanetScale from RDS, Aurora or a self-hosted MySQL, or off PlanetScale when the pricing or feature mix no longer fits.
Performance
Row read reduction, index work, replica usage and connection handling, with the invoice and the latency measured on both sides of the change.
CI and branches
Branch lifecycles, deploy request review, and pull request previews wired into GitHub so schema changes go through the same gate as code.
Managed Tech
Weekly review of deploy requests, lag and read units, with alerts that catch runaway queries before they produce a surprise invoice.

How it works

From first message to fixed

  1. Look Free estimate

    Tell us what's going wrong. We look at it, then tell you plainly what's wrong and what it will cost.

  2. Fix

    We fix the cause, not the symptom. If something is down, getting it back up comes first.

  3. Harden

    Backups, monitoring, updates and access, so the same problem can't quietly come back.

  4. Hand back or stay on

    You get a plain-language write-up. Or we stay on for hosting, upkeep and new work.

Often found together

Running PlanetScale alongside something else?

We work on the whole stack, so the problem can be wherever it actually is.

Questions

PlanetScale questions

Something else? Call+1 737 727 7327

Why can we not deploy our PlanetScale deploy request?

The common cause is a schema conflict with main, because another deploy request landed in between or the branch was created long enough ago that main has moved on. PlanetScale will not apply a change that cannot be cleanly reconciled, and the fix is to rebase the branch onto the latest main, reopen the deploy request, and have it reviewed again. We help teams build a habit of short-lived branches and prompt reviews so this stops being a weekly problem.

Why does PlanetScale not enforce foreign keys?

Vitess, the engine underneath PlanetScale, historically did not enforce foreign keys because they are hard to maintain across shards. Recent versions support them with caveats, but the default assumption is that referential integrity lives in the application. For teams moving from classic MySQL this needs a plan: either accept the check in code, add database-side constraints where it is safe to, or structure the schema so cross-table references are explicit.

Can you take over a PlanetScale database from a previous team?

Yes, and this is a common piece of our work. We audit the branches and deploy requests, check which migrations are pending or abandoned, review the schema against the application code, rotate access tokens into your organization, and leave documentation that explains how the branches and deploy flow are actually used.

Is PlanetScale worth it for a small application?

After the free tier retired, PlanetScale is best suited to teams that want the branch and deploy-request workflow, or that expect to grow into Vitess's sharding story. For a small app with modest traffic and no plan to shard, a plain managed MySQL or PostgreSQL is often a better match. We will show the numbers both ways before recommending either.

How do we handle a large schema change on PlanetScale?

By using the branch and deploy-request flow the platform is built around. The change is applied on a branch, tested against a copy of production data, reviewed as a deploy request, and then deployed by the online schema change engine, which does the work in the background without locking the application. For very large tables we chunk and schedule the work, and watch replica lag throughout.

How much does PlanetScale help cost?

The estimate is free. Describe what the database is doing and what has gone wrong, and we come back with a price and a short plan before changing anything.

Free estimate

PlanetScale database giving you trouble?

Tell us what you're running and what's going wrong. A person reads it and comes back with an estimate.

  • No charge to find out what it will take
  • If it's urgent, say so

Replies come from a person. By sending, you authorize us to email you back. No marketing.