Monitoring PlanetScale with Vigilmon: API Health, Branch Monitoring & Connection Pool Alerts

PlanetScale is a serverless MySQL platform built on Vitess that brings Git-style branching to database schema changes. The branching model is powerful, but it also means you have multiple active database endpoints (main, staging, feature branches) — each of which can degrade independently. Deploy requests add another layer: a failed or stuck migration can block your main branch without any obvious signal. Vigilmon gives you external visibility into all of these: API health, branch-level connectivity, connection pool status, and deploy request health.

What You'll Build

• An HTTP monitor on PlanetScale's database API to confirm connectivity
• Branch-level health checks for your production and staging branches
• Connection pool health monitoring through an application endpoint
• Deploy request monitoring to catch stuck or failed migrations
• SSL certificate monitoring for PlanetScale custom domains

Prerequisites

• A PlanetScale account with at least one database (from planetscale.com)
• A PlanetScale service token with database read permissions
• A free account at vigilmon.online

Step 1: Locate Your PlanetScale Connection Endpoints

PlanetScale provides branch-specific connection strings. Find them in the dashboard under Branches → Connect or via the PlanetScale CLI:

pscale connect YOUR_DATABASE YOUR_BRANCH --port 3306

For HTTP monitoring (which Vigilmon uses), you'll use either:

• The PlanetScale API (api.planetscale.com/v1) to check branch and database status
• An application-level health endpoint that queries your PlanetScale database

Step 2: Monitor PlanetScale's Database API

PlanetScale exposes a REST API for managing databases and branches. Use it to check whether your database and branches are accessible:

1. Log in to Vigilmon → Add Monitor → HTTP.
2. URL: https://api.planetscale.com/v1/organizations/YOUR_ORG/databases/YOUR_DB
3. Request headers:
   • Authorization: Bearer YOUR_SERVICE_TOKEN
   • Accept: application/json
4. Expected status: 200
5. Keyword: "state": "ready" (PlanetScale returns the database state in the response)
6. Interval: 5 minutes
7. Click Save.

This confirms that PlanetScale can reach your database and that it's in a healthy state.

Step 3: Monitor Production Branch Connectivity

Check your production branch specifically — this is the one your application connects to:

1. Add Monitor → HTTP.
2. URL: https://api.planetscale.com/v1/organizations/YOUR_ORG/databases/YOUR_DB/branches/main
3. Request headers: same service token as above
4. Expected status: 200
5. Keyword: "production": true and "ready": true — confirm the branch is both production-grade and ready
6. Interval: 5 minutes

If the production branch enters a degraded state (e.g., during a schema migration or infrastructure issue), this monitor will fire.

Step 4: Add an Application-Level DB Health Endpoint

The most reliable way to monitor database connectivity is from your application, which validates the actual connection string, credentials, and connection pool:

// Express/Node example with PlanetScale HTTP driver
import { connect } from '@planetscale/database';

const conn = connect({
  host: process.env.DATABASE_HOST,
  username: process.env.DATABASE_USERNAME,
  password: process.env.DATABASE_PASSWORD,
});

app.get('/health/db', async (req, res) => {
  try {
    const results = await conn.execute('SELECT 1 AS ok');
    res.json({ status: 'ok', planetscale: 'connected', rows: results.rows });
  } catch (err) {
    res.status(503).json({ status: 'error', message: err.message });
  }
});

Configure Vigilmon to monitor this endpoint:

1. Add Monitor → HTTP.
2. URL: https://your-app.example.com/health/db
3. Expected status: 200
4. Keyword: "planetscale": "connected"
5. Response timeout: 10 seconds (PlanetScale serverless connections can have brief cold starts)
6. Interval: 60 seconds

This is the most valuable monitor — it validates the complete connection path from your application to PlanetScale's serverless MySQL layer.

Step 5: Monitor Deploy Requests (Schema Migrations)

PlanetScale's deploy request workflow applies schema changes non-blocking, but a failed or stuck deploy request can silently leave your schema in an inconsistent state. Monitor your pending deploy requests:

1. Add Monitor → HTTP.
2. URL: https://api.planetscale.com/v1/organizations/YOUR_ORG/databases/YOUR_DB/deploy-requests
3. Request headers: service token
4. Expected status: 200
5. Keyword: avoid "state": "error" — set this as a keyword must be absent check if Vigilmon supports negative assertions, or monitor via application tooling.
6. Interval: 15 minutes during active deployments; 1 hour otherwise

Alternatively, build a small monitoring script that polls deploy request state and pings a Vigilmon heartbeat:

#!/bin/bash
STATE=$(curl -s -H "Authorization: Bearer $PS_TOKEN" \
  "https://api.planetscale.com/v1/organizations/$ORG/databases/$DB/deploy-requests?state=open" \
  | jq -r '.data[0].state // "none"')

if [ "$STATE" != "error" ] && [ "$STATE" != "none" -o "$1" = "check" ]; then
  curl -fsS -X POST https://vigilmon.online/api/heartbeat/YOUR-HEARTBEAT-ID
fi

Create a Heartbeat monitor in Vigilmon with a 20-minute grace period. If your script stops pinging (because a deploy request errored), Vigilmon alerts you.

Step 6: Monitor Connection Pool Health

PlanetScale routes connections through a serverless connection pool (PlanetScale uses Vitess connection pooling under the hood). Add a monitor that checks connection pool exhaustion — typically visible as slow query times or connection refused errors:

Extend your application health endpoint to include connection pool metrics:

app.get('/health/db', async (req, res) => {
  const start = Date.now();
  try {
    const results = await conn.execute('SELECT 1 AS ok');
    const latency = Date.now() - start;
    
    if (latency > 2000) {
      return res.status(503).json({ status: 'degraded', latency_ms: latency });
    }
    res.json({ status: 'ok', latency_ms: latency });
  } catch (err) {
    res.status(503).json({ status: 'error', message: err.message });
  }
});

Vigilmon's response time graph will show latency trends over time. Configure a response time alert threshold of 2000 ms — if queries are taking longer than 2 seconds, the connection pool may be under pressure.

Step 7: Monitor SSL Certificate (Custom Domains)

If you've configured a custom domain in front of PlanetScale (e.g., via Cloudflare), add an SSL monitor:

1. Add Monitor → SSL Certificate.
2. Domain: your custom database domain.
3. Alert when expiry is within: 30 days.

For the default psdb.cloud domains, PlanetScale manages SSL — but add them to your monitor list anyway to catch infrastructure-level TLS issues.

Step 8: Configure Alerting

In Vigilmon under Settings → Notifications, set up your channels:

| Monitor | Trigger | Action | |---|---|---| | App DB health endpoint | Non-200 or keyword missing | Page on-call; check PlanetScale dashboard | | Production branch API | Non-200 or "ready" missing | Check branch state in PlanetScale console | | Database API | Non-200 | PlanetScale platform issue; check planetscalestatus.com | | Response time > 2000 ms | Latency alert | Check connection pool metrics; consider scaling | | Deploy request heartbeat | Missed | Check open deploy requests for errors |

Alert after: 2 consecutive failures for DB health (connection blips are possible). 1 failure for branch API and SSL alerts.

PlanetScale Monitoring Coverage

| Scenario | Vigilmon monitor | |---|---| | Production branch degraded during incident | Branch API monitor fires | | Application connection string changed but not deployed | App health endpoint fires | | Failed schema migration left in error state | Deploy request heartbeat stops; Vigilmon alerts | | Connection pool exhausted under load | Latency exceeds 2 s threshold; alert fires | | Custom domain SSL expiring | SSL monitor alerts at 30/14/7/1 days | | PlanetScale platform incident | Database API monitor fires; check status page |

PlanetScale's Git-style branching and serverless MySQL model give teams schema safety and scale without managing Vitess clusters directly. But that abstraction means failures can happen in layers you can't see from inside the application. Vigilmon monitors PlanetScale from the outside — watching API health, branch state, connection pool latency, and migration status — so you know about problems before your users do.

Start monitoring PlanetScale in under 5 minutes — register free at vigilmon.online.