Powering next gen AI apps with Postgres πŸš€ Learn More
Guides/Neon features/Extensions

The neon_utils extension

Monitor how Neon's Autoscaling feature allocates compute resources

The neon_utils extension provides a num_cpus() function you can use to monitor how Neon's Autoscaling feature allocates vCPU in response to workload. The function returns the current number of allocated vCPUs.

For information about Neon's Autoscaling feature, see Autoscaling.

Install the neon_utils extension

Install the neon_utils extension by running the following CREATE EXTENSION statement in the Neon SQL Editor or from a client such as psql that is connected to Neon.

For information about using the Neon SQL Editor, see Query with Neon's SQL Editor. For information about using the psql client with Neon, see Connect with psql.

Use the num_cpus() function

In Neon, computing capacity is measured in Compute Units (CU). One CU has 1 vCPU and 4 GB of RAM, 2 CUs have 2 vCPUs and 8 GB of RAM, and so on. The amount of RAM in GBs is always 4 times the number of CUs. A Neon compute can have anywhere from .25 to 7 CUs.

When you enable Autoscaling for a compute endpoint, you define a minimum and maximum compute size, as shown below:

Edit compute endpoint dialog showing an Autoscaling configuration

As your workload changes, computing capacity scales dynamically between the minimum and maximum settings defined in your Autoscaling configuration. To retrieve the number of allocated vCPUs at any point in time, you can run the following query:

For Autoscaling configuration instructions, see Compute size and Autoscaling configuration.


The following limitations apply:

  • The num_cpus() function does not return fractional vCPU sizes. The Autoscaling feature can scale in fractional vCPUs, but the num_cpus() function reports the next whole number. For example, if the current number of allocated vCPUs is .25 or .5, the num_cpus() function returns 1.
  • The num_cpus() function only works on compute endpoints that have the Autoscaling feature enabled. Running the function on a fixed size compute endpoint does not return a correct value.

Observe Autoscaling with neon_utils and pgbench

The following instructions demonstrate how you can use the num_cpus() function with pgbench to observe how Neon's Autoscaling feature responds to workload.


Run the test

  1. Install the neon_utils extension:

  2. Create a test.sql file with the following queries:

  3. To avoid errors when running pgbench, initialize your database with the tables used by pgbench. This can be done using the pgbench -i command, specifying the connection string for your Neon database. You can obtain a connection string from the Connection Details widget on the Neon Dashboard. Your connection string will appear similar to the one below:

  4. Run a pgbench test with your test.sql file, specifying your connection string:

    The test produces output similar to the following on a compute endpoint set to scale from 0.25 to 4 CUs.

  5. Call the num_cpus() function to retrieve the current number of allocated vCPUs.

Need help?

Send a request to support@neon.tech, or join the Neon community forum.

Edit this page
Was this page helpful?