API referenceConsole
Cloud provider
Polylane maps your Neon projects, branches and computes, runs read-only queries and query stats to find slow queries and compute problems, and writes the fix.

Connect

Connect Neon from the terminal. Pass --help for the flags Neon accepts, plus --no-browser for headless environments.

Terminal
polylane cloud connect --provider neon

How it works

Infrastructure graph

Polylane syncs the organization every 15 minutes. It maps projects, branches, computes and databases. A project contains its branches, a parent branch defines each branch that forks from it, computes serve their branch, and branches contain their databases. Compute nodes show their autoscaling limits.

A service that connects to a Neon compute host, for example through a DATABASE_URL or a Cloudflare Hyperdrive configuration, links to that compute on the topology.

Which branches Polylane monitors

Polylane monitors production branches by default. A branch is production when its Neon environment setting says so. Without that setting, the default branch of each project is production, and Polylane reads the environment of other branches from their names. To monitor preview, staging and development branches too, turn them on in the account settings.

Metrics and checks

Each project charts its compute (CU-hours), network transfer and branch storage from Neon consumption history. Consumption history is available on the Launch plan and above, so projects on other plans show no charts.

By default, Polylane runs these checks every 30 minutes on the branches in scope:

  • Compute time, written data and data transfer, compared with the history of the account.
  • Storage headroom of the fullest branch against the branch size limit of its project. A breach adds a capacity warning to the check run and does not open an issue alone.
  • Failed control-plane operations, such as a compute start that failed.

No check queries Postgres. A query wakes a suspended compute and starts compute billing.

Investigations

During an investigation, agents can run one read-only SQL statement on a branch database, read the top statements from pg_stat_statements with connection and cache counters, and list recent control-plane operations. Postgres runs each statement in a READ ONLY transaction, so it refuses writes. These queries wake a suspended compute, so they run only when an agent asks for them. Agents can also read other Neon API endpoints. Polylane refuses API paths that return API keys, role passwords or connection strings.

Writes

The Neon API tool can send write requests. Connections start in read-only mode, so Polylane refuses each write until a workspace admin turns read-only mode off. After that, each write needs safety review and your approval before it runs.

Troubleshooting

"Neon does not recognize this API key" error

  • Make sure that you copied the full key and that it is not revoked under Organization settings → API keys.

"This Neon API key cannot read the projects in this organization" error

  • A project-scoped API key reaches one project and cannot list the organization. Create an organization API key.
  • A personal API key must belong to an account that is a member of the organization.

"Multiple Neon organizations are reachable" error

  • The key can reach more than one organization. Name the organization to connect.
  • In the console, pick the organization when Polylane asks.
  • With the API, set the orgId field to the organization ID (org-…).

Missing resources

  • The first sync can take a few minutes.
  • Click Sync in the account header to start a sync immediately.

Disconnecting

Disconnecting stops every sync and check, and deletes the key that Polylane stored. The key stays valid in Neon. Revoke it under Organization settings → API keys in the Neon Console.

Disconnect

Disconnecting stops every sync and check and deletes the credentials Polylane held. Everything Polylane set up in Neon is removed as well; nothing is left behind.

Terminal
polylane cloud disconnect <id>

Tools

4

Operations agents can perform in threads.

neonRunQuery
Run a read-only SQL query on a Neon branch database
neonGetQueryStats
Get top queries, connections and cache hit ratio for a Neon database
neonListOperations
List recent Neon control-plane operations, such as compute starts and branch creations, with failures
neonApi
Call any Neon API endpoint that lacks a dedicated tool

Supported resources

4

Resource types that show up in your infrastructure graph.

Project
Branch
Compute
Database