pscale connect "branch ... not found" proxy in CI

By Kaveh Alemi·Latchkey

pscale connect starts a local proxy that forwards to a PlanetScale branch over TLS. It fails if the named branch does not exist, if authentication is missing, or if the local port it wants is already taken by another process in the job.

What this error means

A background "pscale connect" step exits with "branch pr-123 not found" or "address already in use", and later steps that connect to 127.0.0.1 on the proxy port cannot reach the database.

Error: branch "pr-123" not found in database "app"
# or, if the port is taken:
Error: listen tcp 127.0.0.1:3306: bind: address already in use

Common causes

The branch does not exist when connect runs

The proxy targets a branch that the create step did not produce, so connect cannot establish the tunnel.

The proxy port is already bound

A local MySQL service or a prior proxy holds the default port, so pscale connect cannot listen.

How to fix it

Create the branch and pick a free port

1. Ensure the branch exists before starting the proxy.
2. Bind the proxy to an explicit free port with --port.
3. Point your client at 127.0.0.1 on that port.

pscale connect app "pr-${{ github.event.number }}" \
  --org "$PLANETSCALE_ORG" --port 3307 &

Wait for the proxy to be ready

Poll the proxy port before running the steps that connect, so a race does not fail the first query.

for i in $(seq 1 15); do nc -z 127.0.0.1 3307 && break; sleep 1; done

How to prevent it

• Start the proxy only after the branch exists.
• Pin an explicit, unused proxy port with --port.
• Wait for the port to accept connections before dependent steps.

Frequently asked questions

Related guides

References

• GitHub Actions documentation