Usage metrics

When branches are created, they initially do not add to storage since they share data with the parent branch. However, as soon as changes are made to a branch, new WAL records are created, adding to your history. Additionally, when a branch ages out of your project's history retention window, its data is no longer shared with its parent and is counted independently, thus adding to storage.

To avoid branches consuming storage unnecessarily, reset branches to restart the clock or delete them before they age out of the history retention window.

Yes. Any data-modifying operation, such as deleting a row from a table in your database, generates a WAL record, so even deletions temporarily increase your history size until those records age out of your history retention window.

Any data-modifying operation increases the size of your history. As WAL records age out of your history retention window, they are removed, reducing your history and potentially decreasing your total storage size.

Here are some strategies to consider:

• Optimize your history retention

  Your history retention setting controls how much change history your project retains. Decreasing history reduces the window available for things like point-in-time restore or time-travel. Retaining no history at all would make branches expensive, as a branch can only share data with its parent if history is retained. Your goal should be a balanced history retention configuration; one that supports the features you need but does not consume too much storage. See History retention for how to configure your retention period.

• Use branches instead of duplicating data

  Use short-lived Neon branches for things like testing, previews, and feature development instead of creating separate standalone databases. As long as your branch remains within the history retention window, it shares data with its parent, making branches very storage-efficient. Added to that, branches can be created instantly, and they let you work with data that mirrors production.

• Consider the impact of deletions

  It may seem counterintuitive, but deleting rows from a table temporarily increases storage because delete operations are logged as part of your change history. The records for those deletions remain part of your history until they age out of your retention window. For mass deletions, DELETE TABLE and TRUNCATE TABLE operations are more storage-efficient since they log a single operation rather than a record for each deleted row.

• Delete or reset branches before they age out

  Delete old branches or reset them before they age out of the history retention window. Deleting branches before they age out avoids potentially large increases in storage. Resetting a branch sets the clock back to zero for that branch.

Your storage limit varies depending on your Neon plan.

• Free Plan: If you reach your storage limit on the Free Plan (0.5 GB-month), any further database operations that would increase storage (inserts, updates, and deletes) will fail, and you will receive an error message.
• Launch, Scale, and Business Plans: For users on a paid plan (Launch, Scale, or Business), exceeding your storage limit will result in extra usage.

These factors could be contributing to your high storage consumption:

• Frequent data modifications: If you are performing a lot of writes (inserts, updates, deletes), each operation generates WAL records, which are added to your history. For instance, rewriting your entire database daily can lead to a storage amount that is a multiple of your database size, depending on the number of days of history your Neon project retains.
• History retention: The length of your history retention window plays a significant role. If you perform many data modifications daily and your history retention window is set to 7 days, you will accumulate a 7-day history of those changes, which can increase your storage significantly.

To mitigate this issue, consider adjusting your history retention setting. Perhaps you can do with a shorter window for point-in-time restore, for example. Retaining less history should reduce your future storage consumption.

Also, make sure you don't have old branches lying around. If you created a bunch of branches and let those age out of your history retention window, that could also explain why your storage is so large.

If you're looking to control your storage costs, you might start by deleting old data from your tables, which reduces the data size you're billed for going forward. Since, in typical Postgres operations, deleted tuples are not physically removed until a vacuum is performed, you might then run VACUUM, expecting to see a further reduction in the Data size reported in the Console — but you don't see the expected decrease.

Why no reduction?

In Postgres, VACUUM doesn't reduce your storage size. Instead, it marks the deleted space in the table for reuse, meaning future data can fill that space without increasing data size. While, VACUUM by itself won't make the data size smaller, it is good practice to run it periodically, and it does not impact availability of your data.

VACUUM your_table_name;

Use VACUUM FULL to reclaim space

Running VACUUM FULL does reclaim physical storage space by rewriting the table, removing empty spaces, and shrinking the table size. This can help lower the Data size part of your storage costs. It’s recommended to use VACUUM FULL when a table has accumulated a lot of unused space, which can happen after heavy updates or deletions. For smaller tables or less frequent updates, a regular VACUUM is usually enough.

To reclaim space using VACUUM FULL, you can run the following command per table you want to vacuum:

VACUUM FULL your_table_name;

However, there are some trade-offs:

• Table locking — VACUUM FULL locks your table during the operation. If this is your production database, this may not be an option.
• Temporary storage spike —The process creates a new table, temporarily increasing your peak storage. If the table is large, this could push you over your plan's limit, triggering extra usage charges. On the Free Plan, this might even cause the operation to fail if you hit the storage limit.

In short, VACUUM FULL can help reduce your data size and future storage costs, but it can also result in temporary extra usage charges for the current billing period.

Recommendations

• Set a reasonable history window — We recommend setting your history retention period to balance your data recovery needs and storage costs. Longer history means more data recovery options, but it consumes more storage.

• Use VACUUM FULL sparingly — Because it locks tables and can temporarily increase storage costs, only run VACUUM FULL when there is a significant amount of space to be reclaimed and you're prepared for a temporary spike in storage consumption.

• Consider timing — Running VACUUM FULL near the end of the month can help minimize the time that temporary storage spikes impact your bill, since charges are prorated.

• Manual VACUUM for scale to zero users — In Neon, autovacuum is enabled by default. However, when your compute endpoint suspends due to inactivity, the database activity statistics that autovacuum relies on are lost. If your project uses scale to zero, it’s safer to run manual VACUUM operations regularly on frequently updated tables rather than relying on autovacuum. This helps avoid potential issues caused by the loss of statistics when your compute endpoint is suspended.

  To clean a single table named playing_with_neon, analyze it for the optimizer, and print a detailed vacuum activity report:

  VACUUM (VERBOSE, ANALYZE) playing_with_neon;

  See VACUUM and ANALYZE statistic for a query that shows the last time vacuum and analyze were run.

It's a metric for tracking compute usage. 1 compute hour is equal to 1 active hour for a compute with 1 vCPU. If you have a compute with .25 vCPU, as you would on the Neon Free Plan, it would require 4 active hours to use 1 compute hour. On the other hand, if you have a compute with 4 vCPU, it would only take 15 minutes to use 1 compute hour.

To calculate compute hour usage, you would use the following formula:

compute hours = compute size * active hours

If you're noticing an unexpectedly high number of compute hours, consider the following steps:

• Check your compute size: Compute sizes range from 0.25 CU to 56 CUs. Larger compute sizes will consume more compute hours for the same active period. The formula for compute hour usage is: compute hours = compute size * active hours. If your application can operate effectively with a smaller compute size (less vCPU and RAM), you can reduce compute hours by configuring a smaller compute. See Edit a compute for instructions.

• Check for active applications or clients: Some applications or clients might be polling or querying to your compute regularly, preventing it from scaling to zero. For instance, if you're replicating data from Neon to another service, that service may poll your compute endpoint at regular intervals to detect changes for replication. This behavior is often configurable.

  To investigate database activity, you can run the following query to check connections:

  SELECT
      client_addr,
      COUNT(*) AS connection_count,
      MAX(backend_start) AS last_connection_time
  FROM
      pg_stat_activity
  GROUP BY
      client_addr
  ORDER BY
      connection_count DESC;

This query displays the IP addresses connected to the database, the number of connections, and the most recent connection time.

Each of Neon's plans includes a certain number of compute hours per month:

• Free Plan: This plan includes 191.9 compute hours per month, and you can use up to 5 of those compute hours with non-default branches, in case you want to use Neon's branching feature. Why 191.9? This is enough compute hours to provide 24/7 availability on a 0.25 vCPU compute (our smallest compute size) on your default branch. The math works like this: An average month has about 770 hours. A 0.25 vCPU compute uses 1/4 compute hours per hour, which works out to 180 compute hours per month if you run the 0.25 vCPU compute 24/7. The 11.9 additional compute hours per month are a little extra that we've added on top for good measure. You can enable autoscaling on the Free Plan to allow your compute to scale up to 2 vCPU, but please be careful not to use up all of your 191.5 compute hours before the end of the month.
• Launch Plan: This plan includes 300 compute hours (1,200 active hours on a 0.25 vCPU compute) total per month for all computes in all projects. Beyond 300 compute hours, you are billed for compute hours at $0.16 per hour.
• Scale Plan: This plan includes 750 compute hours (3000 active hours on a 0.25 vCPU compute) total per month for all computes in all projects. Beyond 750 compute hours, you are billed an extra $0.16 per additional hour.
• Business Plan: This plan includes 1000 compute hours (4000 active hours on a 0.24 vCPU compute) total per month for all computes in all projects. Beyond 1000 compute hours, you are billed an extra $0.16 per additional hour.

You can monitor compute hour usage for a Neon project on the Project Dashboard. To monitor compute usage for your Neon account (all compute usage across all projects), refer to your Billing page. See View usage metrics in the Neon Console.

On the Free Plan, if you go over the 5 compute hour allowance for non-default branch computes, those computes are suspended until the allowance resets at the beginning of the month. If you go over the 191.9 compute hour allowance, all computes are suspended until the beginning of the month.

On our paid plans (Launch, Scale, and Business), you are billed automatically for any compute hours over your monthly allowance, which is 300 compute hours on Launch and 750 compute hours on Scale. The billing rate is $0.16 per compute hour.

On the Free Plan, no. You'll have to upgrade to a paid plan. On the Launch, Scale, and Business plans, you are billed automatically for any compute hours over your monthly allowance: 300 compute hours on Launch, 750 compute hours on Scale, and 1000 hours on Business. The billing rate is $0.16 per compute hour.

The formula for compute hour usage is: compute hours = compute size * active hours. You will use more compute hours when your compute scales up in size to meet demand. When you enable autoscaling, you define a max compute size, which acts as a limit on your maximum potential compute usage. See Configuring autoscaling.

The formula for compute hour usage is: compute hours = compute size * active hours. If you increase your compute size for more vCPU and RAM to improve performance, you will use more compute hours.

Scale to zero places your compute into an idle state when it's not being used, which helps minimize compute hour usage. When enabled, computes are suspended after 5 minutes of inactivity. On Neon's paid plans, you can disable scale to zero. See Scale to Zero.