PlanetScale

Write data to a PlanetScale serverless MySQL-compatible database using INSERT ON DUPLICATE KEY UPDATE for upsert. Use Zeotap to materialize model results, enriched profiles, or audience membership into PlanetScale tables.

Prerequisites

A PlanetScale database with an active branch (e.g., main)
A set of branch credentials (username and password) generated from the PlanetScale dashboard
The branch credentials must have write access to the target database
Network connectivity between Zeotap and PlanetScale (PlanetScale is cloud-hosted, so no firewall changes are typically needed)

Authentication

PlanetScale uses Username & Password authentication with branch-scoped credentials.

Open your PlanetScale dashboard and navigate to your database
Click Connect and select your branch (e.g., main)
Click New password to generate credentials
Copy the Username and Password into Zeotap

PlanetScale credentials are scoped to a specific database branch. Ensure you generate credentials for the branch you want to write to.

Configuration

Field	Type	Required	Description
Host	Text	Yes	PlanetScale database host (e.g., `aws.connect.psdb.cloud`). Found in the Connect dialog of your PlanetScale dashboard.
Port	Number	No	Server port. Default: `3306`
Database	Text	Yes	PlanetScale database name

Target Settings

Field	Type	Required	Description
Table	Text	Yes	Target table name. Zeotap creates the table automatically if it does not exist.

Supported Operations

Sync Modes

Mode	Supported	Description
Upsert	Yes	Insert new rows and update existing rows matched by primary key using `INSERT ... ON DUPLICATE KEY UPDATE`
Insert	Yes	Insert new rows only
Update	Yes	Update existing rows matched by primary key
Mirror	Yes	Full sync: upsert new/changed rows and delete removed rows

Audience Sync Modes

Mode	Supported	Description
Add	Yes	Add members to the audience table
Remove	Yes	Remove members from the audience table
Mirror	Yes	Full membership sync: add new members and remove departed members
Upsert	Yes	Add or update audience members

Features

Field Mapping: Yes
Schema Introspection: Yes — Zeotap reads column metadata from PlanetScale’s information_schema
Auto-create Table: Yes — Zeotap creates the target table on first sync if it does not exist
Auto-add Columns: Yes — Zeotap adds missing columns to the target table as TEXT columns

How It Works

Staging: Zeotap creates a temporary staging table and inserts the batch rows with diff metadata (_diff_op, _pk)
Schema evolution: Any columns in the batch that do not exist in the target table are added as TEXT columns
Apply: Based on the sync mode, Zeotap executes the appropriate SQL operations:
- Upsert: INSERT ... ON DUPLICATE KEY UPDATE for rows with _diff_op of added or changed
- Insert: INSERT INTO ... SELECT for rows with _diff_op of added
- Update: UPDATE ... INNER JOIN for rows with _diff_op of changed
- Mirror: Upsert followed by DELETE ... INNER JOIN for rows with _diff_op of removed
Cleanup: The staging table is dropped after the batch completes

Rate Limits

PlanetScale enforces the following limits that affect sync operations:

Per-transaction timeout: 20 seconds
Result set size: 64 MiB maximum
Row limit: 100,000 rows per query
Connection lifetime: Connections held open longer than 24 hours may be terminated
Max tables per database: 2,048

Zeotap writes data in batches that stay within these limits. For very large syncs, data is automatically chunked across multiple transactions.

Best Practices

Use production branches for syncs: Generate credentials from your main (production) branch, not development branches
Define primary keys: Ensure your target table has a primary key for upsert and update sync modes to work correctly
Monitor table count: PlanetScale limits databases to 2,048 tables. Plan your table structure accordingly
Use specific field mappings: Map only the fields you need rather than syncing all columns to keep table schemas clean

Troubleshooting

Connection refused or timeout

PlanetScale is cloud-hosted and accessible over the public internet. If you see connection errors:

Verify the Host value matches what is shown in your PlanetScale Connect dialog
Ensure you are using port 3306
Check that your PlanetScale database is not sleeping (free-tier databases sleep after inactivity)

Access denied

Verify the Username and Password are correct
Ensure the credentials were generated for the correct database branch
PlanetScale credentials are branch-scoped; credentials for dev will not work on main

Table does not exist

Zeotap creates the target table automatically on the first sync. If table creation fails:

Ensure the database has not reached the 2,048 table limit
Verify the branch credentials have DDL permissions

TLS handshake error

PlanetScale requires TLS for all connections. Zeotap enables TLS automatically. If you see TLS errors:

Ensure your network does not perform SSL inspection that breaks the TLS connection
Check that the PlanetScale host certificate is valid

Transaction timeout

PlanetScale enforces a 20-second per-transaction timeout. For very large batches:

Reduce the number of fields being synced
Ensure the target table has appropriate indexes

Duplicate column name errors

Zeotap automatically adds missing columns to the target table. If you see warnings about duplicate columns, these are safe to ignore — Zeotap handles this gracefully.