> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nearbase.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Instance Lifecycle

> Understand instance states, how to rename an instance, and how to delete one

## Instance States

A Nearbase instance moves through the following states during its lifetime:

| Status             | Description                                                  |
| ------------------ | ------------------------------------------------------------ |
| `provisioning`     | Instance is being created. Usually completes in 2–5 minutes. |
| `running`          | Instance is healthy and accepting connections.               |
| `restarting`       | Instance is restarting (e.g., after a parameter change).     |
| `stopped`          | Instance is stopped.                                         |
| `degraded`         | Instance is running but has detected a health issue.         |
| `provision_failed` | Provisioning encountered an error and did not complete.      |
| `deleting`         | Deletion is in progress.                                     |
| `deleted`          | Instance has been permanently deleted.                       |

### Provisioning

After you create an instance, it enters `provisioning` state. The console polls for status updates automatically. Most instances are ready within **2–5 minutes**.

### Provision Failed

If provisioning fails, the instance enters `provision_failed` state. This is uncommon. Contact [team@m.nearbase.dev](mailto:team@m.nearbase.dev) with your instance ID and we'll investigate. You will not be charged for a failed provision.

### Degraded

A `degraded` instance is running but has a detected issue (e.g., a replica lag or storage warning). Connections still work. The platform automatically attempts to recover. If the state persists, contact support.

## Renaming an Instance

You can rename an instance at any time from the instance detail page without any downtime or connection disruption. The connection string hostname (`{instance-id}.pg.nearbase.app`) does not change when you rename — only the display name in the console changes.

To rename:

1. Open the instance in the console.
2. Click the instance name at the top of the page.
3. Enter the new name and confirm.

## Deleting an Instance

<Warning>
  Deletion is permanent. All data in the instance is destroyed and cannot be
  recovered. Make sure you have a backup or export before proceeding.
</Warning>

To delete an instance:

1. Open the instance in the console.
2. Go to the **Overview** tab and scroll to the bottom.
3. Click **Delete Instance** and confirm by typing the instance name.

### Prorated Refund

Nearbase bills monthly upfront. When you delete an instance before the end of its billing period, you receive a **prorated credit** back to your account balance for the unused days. This credit is applied to your next payment.

For example, if you delete on day 10 of a 30-day period, you receive roughly 20/30 of the monthly fee back as a balance credit.