# Balance & Credits
Source: https://docs.nearbase.dev/billing/balance-and-credits
How account balance and promotional credits work on Nearbase
## Account Balance
Your Nearbase account has a **cash balance** — a prepaid credit balance you top up manually. When a payment is due (instance creation or monthly renewal), Nearbase deducts from your balance first before charging your saved card.
Keeping a balance topped up means renewals are processed instantly without requiring a card charge each month.
### Topping Up
1. Go to **Billing** in the console sidebar.
2. Click **Add Balance** (or **Top Up**).
3. Select an amount and complete the Stripe Checkout flow.
4. Your balance is updated immediately after the card charge succeeds.
Top-ups are processed via Stripe and appear on your bank statement as a Nearbase charge.
### Viewing Your Balance
Your current balance is displayed at the top of the **Billing** page. The balance panel shows:
* **Cash balance** — funds you have topped up
* **Promo credits** — any promotional credits applied to your account
***
## Promotional Credits
Promo credits are issued by Nearbase (for example, during a promotion, referral, or as a goodwill credit). They behave similarly to cash balance but with two differences:
| Property | Cash Balance | Promo Credits |
| ------------- | -------------------- | ----------------------- |
| Source | User top-up via card | Issued by Nearbase |
| Expiry | Never expires | May have an expiry date |
| Withdrawal | Not withdrawable | Not withdrawable |
| Payment order | Applied second | Applied first |
Promo credits are consumed before cash balance. Any unused promo credits expire on their expiry date and cannot be recovered.
***
## Transaction History
Every balance movement — top-ups, subscription charges, prorated refunds, and promo credit grants — is recorded as a transaction. To view your full transaction history:
1. Go to **Billing → Transactions** in the console.
2. Transactions are listed in reverse chronological order.
3. Each transaction shows the amount, type, date, and a link to the Stripe receipt (where applicable).
***
## Refunds
When you delete an instance before the end of its billing period, the unused portion of the subscription fee is returned to your **cash balance** as a prorated refund. See [Instance Lifecycle](/instances/lifecycle#prorated-refund) for details.
Refunds from Stripe (e.g., disputed charges) are handled separately and may take 5–10 business days to appear.
# Billing Profile
Source: https://docs.nearbase.dev/billing/billing-profile
Manage your billing contact and tax information for invoices
## Overview
Your billing profile stores the company and tax details that appear on your Nearbase invoices and receipts. Keeping this information accurate is important for accounting and compliance purposes.
## What's in Your Billing Profile
| Field | Description |
| ------------------- | ------------------------------------------------------------------- |
| **Company Name** | Your company or organization name, as it should appear on invoices. |
| **Tax ID** | Your VAT number, GST number, or other applicable tax identifier. |
| **Billing Email** | The email address where invoice notifications are sent. |
| **Billing Address** | Your company's registered address. |
## Updating Your Billing Profile
1. Go to **Billing** in the console sidebar.
2. Find the **Billing Profile** section.
3. Edit the fields and save.
Changes take effect on your next invoice. They do not retroactively update previously issued invoices.
## Tax / VAT
If your business is VAT-registered, add your VAT number to the **Tax ID** field. This number will appear on all future invoices.
Nearbase does not currently add VAT or GST on top of listed prices. If your
local tax authority requires you to self-assess tax on SaaS purchases, your
billing profile information will be available on each invoice for that
purpose.
## Invoice Delivery
Invoices are delivered to the **Billing Email** address in your profile after each charge. You can also view and download all past invoices from the **Billing → Transactions** page at any time.
Need a specific invoice format or have a billing inquiry? Contact [team@m.nearbase.dev](mailto:team@m.nearbase.dev).
# Billing Overview
Source: https://docs.nearbase.dev/billing/overview
How Nearbase billing works — subscriptions, payment, and invoices
## How Billing Works
Nearbase uses a **monthly subscription** model. When you create an instance, you pay for the first full billing period upfront. Each month, the subscription automatically renews and the next period's fee is charged.
### Payment Priority
Payments follow this order:
1. **Promo credits** — If you have promotional credits in your account, they are applied first (until they expire or run out).
2. **Cash balance** — Any remaining amount is deducted from your account balance.
3. **Saved card** — If your balance is insufficient, the remaining amount is charged to your saved Stripe payment card.
Top up your balance in advance to avoid relying on card charges at renewal
time. See [Balance & Credits](/billing/balance-and-credits).
## Subscriptions
Each Nearbase instance is a separate subscription. You can view, manage, and cancel subscriptions from the **Billing → Subscriptions** page in the console.
### Subscription States
| State | Description |
| ---------- | ------------------------------------------------------------------------------------------------------------ |
| `active` | Subscription is running and will renew at the end of the period. |
| `canceled` | Subscription has been canceled and will not renew. The instance is deleted at the end of the current period. |
### Canceling a Subscription
When you delete an instance, its subscription is canceled. You receive a [prorated credit](/instances/lifecycle#prorated-refund) back to your account balance for the unused days remaining in the billing period.
## Invoices
Nearbase generates an invoice for each charge. You can view all invoices from the **Billing → Transactions** page. Each invoice includes:
* The billing period
* The instance name and region
* The amount charged
* A link to the Stripe receipt
## Upcoming Renewal
The console shows you the upcoming renewal amount for each active subscription so there are no surprises at renewal time.
## Failed Payments
If a renewal charge fails (insufficient balance and card decline), the subscription enters a past-due state. Nearbase will attempt to retry the charge. If payment cannot be collected, the instance will be suspended and eventually deleted. Ensure your [balance](/billing/balance-and-credits) is sufficient or keep a valid payment card on file.
Need help with a billing question? Contact [team@m.nearbase.dev](mailto:team@m.nearbase.dev).
# Pricing
Source: https://docs.nearbase.dev/billing/pricing
Understand how Nearbase instances are priced
## Flat Monthly Pricing
Nearbase uses **flat monthly pricing** — one price per instance configuration, with no per-query fees, egress charges, or hidden costs. The price you see when creating an instance is the full monthly cost.
Your monthly price is determined by three factors:
1. **Instance class** — CPU and memory (see [Instance Classes](/instances/instance-classes))
2. **Storage size** — GB of provisioned disk
3. **Region** — Prices are consistent across regions
## What's Included
Every Nearbase subscription includes:
* Fully managed PostgreSQL (patching, monitoring, failover)
* Automated daily backups
* Custom hostname (`{instance-id}.pg.nearbase.app`)
* TLS encryption in transit and at rest
* Access to the monitoring dashboard (performance, logs, backups)
There are no additional fees for:
* Bandwidth / data transfer within the region
* Number of queries or connections (up to your instance limit)
* Support via email
## Pricing Calculator
For exact monthly prices across all regions, instance classes, and storage sizes, use the interactive pricing calculator on our website:
See live prices for any region, instance class, and storage combination at
nearbase.dev/pricing
## Prorated Charges and Refunds
* **New instances** are charged for the full first billing period upfront.
* **Deleted instances** receive a prorated credit for the unused portion of the current billing period. The credit is returned to your [account balance](/billing/balance-and-credits).
* **Scaling** (changing instance class or storage) adjusts your next renewal price. The current period is not repriced.
## Example
| Instance Class | Storage | Monthly Price (est.) |
| ----------------------------- | ------- | ---------------------- |
| Basic (1 vCPU, 1 GB RAM) | 20 GB | See pricing calculator |
| Basic (2 vCPU, 4 GB RAM) | 50 GB | See pricing calculator |
| Dedicated (2 vCPU, 16 GB RAM) | 100 GB | See pricing calculator |
Prices vary slightly by region. Visit [nearbase.dev/pricing](https://nearbase.dev/pricing) for exact figures.
# CLI
Source: https://docs.nearbase.dev/cli
Manage your Nearbase Postgres instances from the terminal
The Nearbase CLI lets you list and inspect your databases without leaving the terminal — think `nvidia-smi`, but for Postgres.
## Install
```bash theme={null}
npm install -g @nearbase/cli
```
Requires Node.js ≥ 20. The package is published as [`@nearbase/cli`](https://www.npmjs.com/package/@nearbase/cli).
## Quick start
```bash theme={null}
nearbase login # opens your browser to authenticate
nearbase # list every database across all your orgs
```
`nearbase login` runs an OAuth-style device flow. The CLI prints a short
code and opens [console.nearbase.dev](https://console.nearbase.dev) in your
browser. Sign in and approve the displayed code — the CLI receives a
long-lived token and stores it locally.
`nearbase` (or `nearbase ls`) prints a table of every instance across every
Clerk organization you belong to.
Add the global `--json` option for a stable machine-readable envelope. Use
`NEARBASE_TOKEN` to inject a previously authorized token without writing it
to disk.
## Commands
```text theme={null}
nearbase login [--no-open] Authenticate with the device flow
nearbase logout Forget locally stored credentials
nearbase ls [--org ORG] List instances
nearbase get ID --org ORG Get metadata without credentials
nearbase regions List available regions
nearbase engine-versions List PostgreSQL versions
nearbase classes List offered instance classes
nearbase price Quote the current monthly price
nearbase create Dry-run or create a short-lived quote
nearbase create --confirm ID Confirm a quote with an idempotency key
```
Run `nearbase --help` for configuration flags. `--org` accepts an
organization ID or slug. Write operations always require it explicitly.
### Example
```
$ nearbase
┌───────────┬─────────────┬─────────┬──────────────────────┬─────────┐
│ Org │ Name │ Status │ Region │ Storage │
├───────────┼─────────────┼─────────┼──────────────────────┼─────────┤
│ acme │ prod-main │ running │ Tokyo (Japan) │ 100 GB │
│ acme │ staging │ running │ Tokyo (Japan) │ 20 GB │
│ side-proj │ playground │ stopped │ Singapore (Singapore)│ 20 GB │
└───────────┴─────────────┴─────────┴──────────────────────┴─────────┘
3 instance(s)
```
## Authentication
`nearbase login` uses an OAuth-style device flow:
1. The CLI requests a one-time `device_code` and short `user_code` from the Nearbase API.
2. Your browser opens to the console, where you sign in with Clerk and approve the displayed code.
3. The CLI exchanges the device code for a long-lived access token (90 days) and stores it on disk.
The token is written to `~/.config/nearbase/auth.json` with file mode `0600` on Unix. To revoke access on a machine, run `nearbase logout`.
Tokens are scoped to your Clerk user and inherit the org memberships you have
at the moment each request is made. Removing a user from an org takes effect
on their next CLI command.
## Agent and automation usage
Machine output uses one JSON document on stdout:
```json theme={null}
{"ok":true,"data":{"instances":[]}}
```
Failures use the same envelope on stderr with a stable error code and optional
request ID. Exit codes are `0` for success, `1` for usage/general errors, `2`
for authentication errors, and `3` for API, network, or timeout errors.
```bash theme={null}
export NEARBASE_TOKEN='previously-authorized-token'
nearbase --json ls --org acme
nearbase --json price \
--region cn-hangzhou \
--engine-version 16 \
--db-instance-class pg.n2.medium.1 \
--db-instance-storage 20 \
--db-instance-storage-type general_essd \
--category Basic
```
For a remote login, `nearbase --json login --no-open` writes an
`authorization_required` event containing the URL and user code to stderr,
then waits for human approval.
### Safe create flow
Creating an instance is intentionally two-step:
1. Run `nearbase create` with `--org` and all configuration flags. The command
returns a ten-minute quote and does not charge or provision anything.
2. Confirm exactly that quote with
`nearbase create --confirm QUOTE_ID --idempotency-key STABLE_UNIQUE_KEY`.
3. If credits cover the total, provisioning starts. Otherwise the command
returns a Stripe Checkout URL that a person must open and complete.
The server revalidates org membership, SKU availability, price, and credits at
confirmation. Reusing the same idempotency key replays the original result;
using another key for the consumed quote is rejected. CLI JSON never includes
database passwords or connection strings.
Provider-backed dry runs are limited to five requests per user and organization
per minute.
Deletion, security-IP changes, payment-method management, start, stop, and
restart are not exposed to agents.
## Configuration
* `NEARBASE_API_URL` defaults to `https://console.nearbase.dev` and may target
staging or local development.
* `NEARBASE_TOKEN` overrides the token file for CI and agent processes. Treat
it as a secret and inject it through the runtime's secret manager.
## Troubleshooting
* **`Not logged in. Run nearbase login first.`** — Run `nearbase login`.
* **`Session expired or invalid.`** — Tokens are valid for 90 days; run `nearbase login` again.
* **Browser didn't open.** — Open the verification URL printed in the terminal manually.
## Source
The CLI is open source. Issues, feature requests, and PRs are welcome at [github.com/jiey2/nearbase-mono](https://github.com/jiey2/nearbase-mono).
# Connecting to Your Database
Source: https://docs.nearbase.dev/connecting
Connect to your Nearbase PostgreSQL database using any client or driver
## Connection String
Every Nearbase instance has a unique connection string available on the **Overview** tab in the [console](https://console.nearbase.dev). It follows this format:
```
postgresql://admin:{password}@{instance-id}.pg.nearbase.app:5432/postgres?sslmode=require
```
SSL is required for all connections. Always include `sslmode=require` (or its
equivalent for your driver). Connections without SSL are rejected.
## Connection Details
| Parameter | Value |
| --------- | ------------------------------- |
| Host | `{instance-id}.pg.nearbase.app` |
| Port | `5432` |
| Database | `postgres` |
| Username | `admin` |
| SSL mode | `require` |
## Code Examples
```bash psql theme={null}
psql "postgresql://admin:{password}@{instance-id}.pg.nearbase.app:5432/postgres?sslmode=require"
```
```javascript Node.js (pg) theme={null}
import pg from "pg";
const pool = new pg.Pool({
connectionString:
"postgresql://admin:{password}@{instance-id}.pg.nearbase.app:5432/postgres?sslmode=require",
});
const result = await pool.query("SELECT NOW()");
console.log(result.rows[0]);
```
```javascript Drizzle ORM theme={null}
import { drizzle } from "drizzle-orm/node-postgres";
import { Pool } from "pg";
const pool = new Pool({
connectionString:
"postgresql://admin:{password}@{instance-id}.pg.nearbase.app:5432/postgres?sslmode=require",
});
export const db = drizzle(pool);
```
```typescript Prisma theme={null}
// Add to your .env file:
// DATABASE_URL="postgresql://admin:{password}@{instance-id}.pg.nearbase.app:5432/postgres?sslmode=require"
// schema.prisma
datasource db {
provider = "postgresql"
url = env("DATABASE_URL")
}
```
```python Python (psycopg2) theme={null}
import psycopg2
conn = psycopg2.connect(
"postgresql://admin:{password}@{instance-id}.pg.nearbase.app:5432/postgres?sslmode=require"
)
cursor = conn.cursor()
cursor.execute("SELECT NOW()")
print(cursor.fetchone())
conn.close()
```
```python SQLAlchemy theme={null}
from sqlalchemy import create_engine, text
engine = create_engine(
"postgresql+psycopg2://admin:{password}@{instance-id}.pg.nearbase.app:5432/postgres?sslmode=require"
)
with engine.connect() as conn:
result = conn.execute(text("SELECT NOW()"))
print(result.fetchone())
```
```go Go (pgx) theme={null}
package main
import (
"context"
"fmt"
"github.com/jackc/pgx/v5"
)
func main() {
conn, err := pgx.Connect(
context.Background(),
"postgresql://admin:{password}@{instance-id}.pg.nearbase.app:5432/postgres?sslmode=require",
)
if err != nil {
panic(err)
}
defer conn.Close(context.Background())
var now string
conn.QueryRow(context.Background(), "SELECT NOW()").Scan(&now)
fmt.Println(now)
}
```
## Connection Pooling
For production applications, use a connection pool to efficiently reuse database connections rather than opening a new one per request.
A good starting point: set your pool size to **5–10 connections per CPU** on
your database instance. You can monitor live active connection counts on the
[Performance tab](/instances/monitoring).
```javascript Node.js (pg) theme={null}
const pool = new pg.Pool({
connectionString:
"postgresql://admin:{password}@{instance-id}.pg.nearbase.app:5432/postgres?sslmode=require",
max: 10, // maximum pool size
idleTimeoutMillis: 30000,
connectionTimeoutMillis: 2000,
});
```
```python SQLAlchemy theme={null}
engine = create_engine(
"postgresql+psycopg2://admin:{password}@{instance-id}.pg.nearbase.app:5432/postgres?sslmode=require",
pool_size=5,
max_overflow=10,
pool_pre_ping=True,
)
```
```go Go (pgxpool) theme={null}
import "github.com/jackc/pgx/v5/pgxpool"
config, _ := pgxpool.ParseConfig(
"postgresql://admin:{password}@{instance-id}.pg.nearbase.app:5432/postgres?sslmode=require",
)
config.MaxConns = 10
pool, err := pgxpool.NewWithConfig(context.Background(), config)
```
## SSL / TLS
All Nearbase databases require TLS. If your driver accepts a configuration object instead of a connection string, enable SSL explicitly:
```javascript theme={null}
const pool = new pg.Pool({
host: "{instance-id}.pg.nearbase.app",
port: 5432,
database: "postgres",
user: "admin",
password: "{password}",
ssl: { rejectUnauthorized: true },
});
```
Need help? Reach out at [team@m.nearbase.dev](mailto:team@m.nearbase.dev).
# Backups
Source: https://docs.nearbase.dev/instances/backups
Automated backups for your Nearbase PostgreSQL database
## Overview
Nearbase automatically backs up every running instance daily. Backups are managed entirely by the platform — no configuration required.
## Backup Schedule
| Property | Value |
| ----------- | ---------------------------- |
| Frequency | Daily automated backups |
| Type | Full + incremental |
| Managed by | Platform (Alibaba Cloud RDS) |
| User action | None required |
Backup windows are scheduled during low-traffic hours for your region's timezone to minimize impact on running workloads.
## Viewing Backup History
To see your backup history:
1. Open the instance in the [console](https://console.nearbase.dev).
2. Go to the **Backups** tab.
The table shows each backup entry with its:
* **Backup ID**
* **Backup type** (full or incremental)
* **Start and end time**
* **Backup size**
* **Status** (succeeded / failed)
## Retention Policy
Backups are retained according to the policy configured on your instance. You can view the current backup policy on the **Backups** tab. The default retention window is sufficient for most workloads; contact [team@m.nearbase.dev](mailto:team@m.nearbase.dev) if you need a longer retention period.
## Restoring from a Backup
Point-in-time restore and manual restore operations are handled by Nearbase support. If you need to restore your database to a previous state, contact [team@m.nearbase.dev](mailto:team@m.nearbase.dev) with:
* Your instance ID
* The target restore point (date and time, or backup ID)
Restoring from a backup overwrites the current state of your database.
Export any data you need to keep before requesting a restore.
## Exporting Data Manually
For application-level exports (e.g., migrating data or creating a local copy), use `pg_dump`:
```bash theme={null}
pg_dump "postgresql://admin:{password}@{instance-id}.pg.nearbase.app:5432/postgres?sslmode=require" \
--format=custom \
--file=backup.dump
```
Restore with `pg_restore`:
```bash theme={null}
pg_restore \
--dbname "postgresql://admin:{password}@{target-host}:5432/postgres?sslmode=require" \
backup.dump
```
# Creating an Instance
Source: https://docs.nearbase.dev/instances/create
Provision a new managed PostgreSQL database on Nearbase
## Overview
Creating a Nearbase instance takes 2–5 minutes. You'll select a region, PostgreSQL version, instance class, and storage size — then complete checkout. Once provisioned, you receive a connection string and your database is immediately ready.
## Steps
Go to [console.nearbase.dev](https://console.nearbase.dev) and navigate to
**Instances** in the sidebar. Click **New Instance**.
Select the region closest to your application servers or end users for the
lowest latency. See [Regions](/regions) for the full list and compliance
information.
If you're unsure, **Singapore** (`ap-southeast-1`) is a good default for
Southeast Asia. **Tokyo** (`ap-northeast-1`) is best for Japan and East
Asia workloads.
Choose the PostgreSQL major version. We recommend using the latest available
version unless you have a compatibility requirement.
Select the CPU and memory configuration that fits your workload. See
[Instance Classes](/instances/instance-classes) for a breakdown of all
available tiers and how to choose between them.
Choose the initial storage size in GB. Storage is backed by high-performance
cloud disk (`general_essd`) by default.
You can scale storage up later without downtime, but you cannot reduce it.
Start with enough room for your data plus anticipated growth.
Review the monthly price, then proceed to checkout. Payment is deducted from
your [account balance](/billing/balance-and-credits) first. If your balance
is insufficient, the remainder is charged to your saved card.
Your instance enters **Provisioning** status and is typically ready within
2–5 minutes. You'll see it switch to **Running** in the console.
## After Provisioning
Once your instance is **Running**:
* The **Overview** tab shows your full connection string.
* Connect with any PostgreSQL client — see [Connecting to Your Database](/connecting).
* Your IP address needs to be in the allowlist to connect. By default, all IPs (`0.0.0.0/0`) are allowed. Restrict this in the [Security tab](/instances/security).
## Instance Limits
There is no hard limit on the number of instances per organization. Each instance is billed as a separate monthly subscription.
# Instance Classes
Source: https://docs.nearbase.dev/instances/instance-classes
Understand Nearbase instance classes and how to choose the right one for your workload
## Overview
An instance class defines the CPU and memory allocated to your database. Nearbase
offers two groups: **General Purpose** and **Dedicated**. Pricing is **uniform
across every region** — the same class costs the same everywhere.
## Class Code Format
Instance class codes follow this pattern:
```
pg.{tier}.{size}.{variant}
```
| Segment | Meaning |
| ----------- | -------------------------------------------------------------------------------- |
| `pg` | PostgreSQL engine |
| `{tier}` | `n2e` / `n1e` = Economy (ARM) · `n2` / `n4` = General Purpose · `x8` = Dedicated |
| `{size}` | vCPU count, e.g. `2c`, `medium`, `xlarge` |
| `{variant}` | memory variant within the size class |
For example, `pg.n4.4c.1m` is a General Purpose instance with 4 vCPU and 16 GB memory.
## Catalog
### General Purpose
Balanced CPU and memory for most workloads. Includes low-cost economy (ARM)
options for small apps and trials.
| Class Code | vCPU | Memory | Notes |
| -------------- | ---- | ------ | ------------- |
| `pg.n2e.1c.1m` | 1 | 2 GB | Economy (ARM) |
| `pg.n1e.2c.1m` | 2 | 2 GB | Economy (ARM) |
| `pg.n2e.2c.1m` | 2 | 4 GB | Economy (ARM) |
| `pg.n4.2c.1m` | 2 | 8 GB | Standard |
| `pg.n2.4c.1m` | 4 | 8 GB | Standard |
| `pg.n4.4c.1m` | 4 | 16 GB | Standard |
| `pg.n4.6c.1m` | 6 | 24 GB | Standard |
| `pg.n4.8c.1m` | 8 | 32 GB | Standard |
**Best for:** Side projects, dev/test, internal tools, production web apps, APIs,
and moderate-traffic SaaS workloads.
Economy instances (`pg.n1e.*` / `pg.n2e.*`) are ARM-based and may not be
available in every region — `pg.n1e.*` in particular is **not available** in
`ap-northeast-1` (Tokyo), `ap-southeast-3` (Kuala Lumpur), and
`ap-southeast-7` (Bangkok). Availability is validated when you create an
instance; pick a Standard or Dedicated class in those regions.
### Dedicated
Dedicated CPU instances with a high memory-to-CPU ratio (8 GB RAM per vCPU).
Designed for CPU-intensive queries, analytics, and latency-sensitive workloads
that cannot tolerate CPU sharing.
| Class Code | vCPU | Memory |
| ----------------- | ---- | ------ |
| `pg.x8.medium.1` | 2 | 16 GB |
| `pg.x8.large.1` | 4 | 32 GB |
| `pg.x8.xlarge.1` | 8 | 64 GB |
| `pg.x8.2xlarge.1` | 16 | 128 GB |
| `pg.x8.4xlarge.1` | 32 | 256 GB |
**Best for:** Analytics, reporting, high-concurrency production databases,
workloads requiring consistent low-latency query performance.
## How to Choose
| Scenario | Recommended |
| ------------------------------------- | -------------------------------- |
| Development / staging environment | General Purpose (Economy) |
| Low-traffic production app | General Purpose (Economy) |
| Standard web app or API backend | General Purpose (Standard) |
| High-concurrency or latency-sensitive | General Purpose `n4` / Dedicated |
| Analytics / reporting queries | Dedicated |
| Large dataset, CPU-intensive workload | Dedicated |
## Scaling
You can change your instance class at any time from the instance detail page. Scaling is handled by the platform with minimal interruption. Your billing is adjusted on a prorated basis for the remainder of the billing period.
Start with a smaller class and scale up as needed. Nearbase supports vertical
scaling without data migration.
# Instance Lifecycle
Source: https://docs.nearbase.dev/instances/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
Deletion is permanent. All data in the instance is destroyed and cannot be
recovered. Make sure you have a backup or export before proceeding.
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.
# Monitoring
Source: https://docs.nearbase.dev/instances/monitoring
Monitor your instance's performance, resource usage, and logs in real time
## Overview
The Nearbase console provides live monitoring data for every running instance across four areas: Performance, Usage, Error Logs, and Slow Query Logs.
***
## Performance Tab
The **Performance** tab shows real-time and historical charts for the most important database metrics.
| Metric | Description |
| ---------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| **CPU Usage** | Percentage of allocated vCPUs in use. Sustained high CPU suggests the instance class needs to be scaled up. |
| **Memory Usage** | Percentage of allocated RAM in use. High memory pressure can cause query slowdowns and swapping. |
| **Disk IOPS** | Read and write I/O operations per second. Useful for identifying I/O-bound workloads. |
| **Active Connections** | Number of client connections currently open. Compare against your instance's connection limit. |
| **Slow Queries** | Count of queries that exceeded the slow query threshold in the selected time window. |
| **Long Transactions** | Count of transactions open for an unusually long time. Long transactions can block vacuuming and cause lock contention. |
If CPU or connections are consistently near their limits, consider scaling up
your [instance class](/instances/instance-classes) or adding connection pooling
in your application.
***
## Usage Tab
The **Usage** tab shows aggregate resource utilization for the instance.
| Metric | Description |
| -------------- | --------------------------------------------------------- |
| **Disk Usage** | Total storage consumed vs. your provisioned storage size. |
| **Memory** | Actual memory consumed by the database process. |
Storage can only be scaled up, not down. Monitor disk usage and scale storage
before you run out — the platform will alert you when usage is high.
***
## Error Logs
The **Error Logs** tab streams PostgreSQL error log entries from your instance.
**Filtering:**
* Use the **date range picker** to view logs from a specific time window.
* Results are paginated; use the navigation controls to scroll through older entries.
**Common log entries to watch for:**
| Message Pattern | What It Means |
| ------------------------------------------------ | ----------------------------------------------------------------- |
| `FATAL: password authentication failed` | A client attempted to connect with wrong credentials. |
| `ERROR: out of shared_buffers` | Memory pressure; consider scaling up or tuning `shared_buffers`. |
| `FATAL: remaining connection slots are reserved` | Connection limit reached; reduce pool size or scale up. |
| `ERROR: deadlock detected` | Two transactions were waiting on each other; one was rolled back. |
***
## Slow Query Logs
The **Slow Query Logs** tab lists queries that exceeded the slow query threshold, along with their execution time and query text.
**Filtering:**
* Use the **date range picker** to scope to a specific time window.
* Results are paginated.
**Using slow query logs:**
1. Sort by execution time to find the worst offenders.
2. Run `EXPLAIN ANALYZE` on slow queries in `psql` to see the query plan.
3. Add indexes on columns used in `WHERE`, `JOIN`, and `ORDER BY` clauses.
4. Consider rewriting queries that perform sequential scans on large tables.
Slow query logging is enabled by default. The threshold is set in your
instance's PostgreSQL parameters — see [Parameters](/instances/parameters).
# Parameters
Source: https://docs.nearbase.dev/instances/parameters
View and understand PostgreSQL configuration parameters on your Nearbase instance
## Overview
The **Parameters** tab on your instance detail page shows the PostgreSQL configuration parameters currently applied to your database. These are the settings that control memory allocation, query planning, connection limits, logging thresholds, and more.
## Viewing Parameters
1. Open the instance in the [console](https://console.nearbase.dev).
2. Go to the **Parameters** tab.
3. You'll see the full list of parameters with their current running values.
## Running vs. Pending Parameters
Some parameter changes take effect immediately; others require a database restart.
| State | Description |
| ----------- | ---------------------------------------------------------------------------------------------------------------- |
| **Running** | The value currently active on the database process. |
| **Pending** | A value has been submitted but not yet applied. This appears when a parameter requires a restart to take effect. |
When a parameter is in **Pending** state, the new value will be applied at the next scheduled maintenance window or when you manually restart the instance.
## Common Parameters
| Parameter | Description |
| ------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| `max_connections` | Maximum number of simultaneous client connections. |
| `shared_buffers` | Amount of memory dedicated to PostgreSQL's shared buffer cache. |
| `work_mem` | Memory available for each sort or hash operation per query. |
| `log_min_duration_statement` | Queries slower than this threshold (in ms) are written to slow query logs. Set to `-1` to disable. |
| `idle_in_transaction_session_timeout` | Automatically terminates sessions that have been idle in a transaction for longer than this duration. |
| `statement_timeout` | Automatically cancels queries that run longer than this duration. |
| `timezone` | The time zone used for timestamps in this database. |
Parameter modifications are available on request. Contact
[team@m.nearbase.dev](mailto:team@m.nearbase.dev) if you need to tune a specific
parameter for your workload.
## Slow Query Threshold
The `log_min_duration_statement` parameter controls what appears in your [Slow Query Logs](/instances/monitoring#slow-query-logs). By default it is set to capture queries that take longer than a few hundred milliseconds. Lowering this value captures more queries but increases log volume.
# Security
Source: https://docs.nearbase.dev/instances/security
Manage IP allowlists and understand SSL/TLS encryption for your Nearbase database
## IP Allowlist
Every Nearbase instance has an IP allowlist that controls which IP addresses are permitted to connect. By default, all IPs are allowed (`0.0.0.0/0`). For production databases, restrict this to only the IPs your application servers use.
### Viewing and Editing the Allowlist
1. Open the instance in the [console](https://console.nearbase.dev).
2. Go to the **Security** tab.
3. You'll see the current list of allowed IP addresses and CIDR ranges.
4. Add or remove entries as needed, then save.
### Allowlist Format
Entries can be individual IPs or CIDR ranges:
| Entry | Description |
| ---------------- | -------------------------------------------------------- |
| `203.0.113.42` | Allow a single IP address |
| `203.0.113.0/24` | Allow an entire subnet |
| `0.0.0.0/0` | Allow all IPs (default — not recommended for production) |
Leaving `0.0.0.0/0` in the allowlist means your database port is reachable
from any IP on the internet. It is still protected by password authentication
and SSL, but removing broad allowlist entries adds an extra layer of defense.
### Recommended Setup
For most deployments, allowlist only your application servers' outbound IPs:
* **Single server**: add its static IP.
* **Cloud provider (e.g., AWS, GCP)**: add your NAT gateway or egress IP range.
* **Local development**: add your workstation's IP temporarily. Remove it when done.
If your application runs on a service that does not have a static IP, consider
routing database traffic through a NAT gateway or VPN with a fixed egress IP.
***
## SSL / TLS
All Nearbase databases enforce TLS encryption in transit. Connections without SSL are rejected at the server level — there is no way to disable this.
### Encryption at Rest
Data stored on disk is encrypted at rest using AES-256 encryption managed by the underlying cloud infrastructure.
### Certificate Verification
When connecting with `sslmode=require`, the driver encrypts the connection but does not verify the server certificate. For stricter verification use `sslmode=verify-full` with a trusted CA bundle, or rely on `sslmode=require` which is sufficient for most applications.
```bash theme={null}
# Require SSL (recommended default)
psql "host={instance-id}.pg.nearbase.app port=5432 dbname=postgres user=admin password={password} sslmode=require"
```
***
## Password Management
Your instance's `admin` password is set during provisioning and displayed once in the console. Store it securely in your application's secret management system (e.g., environment variables, a secrets manager like AWS Secrets Manager or HashiCorp Vault).
If you need to reset your password, contact [team@m.nearbase.dev](mailto:team@m.nearbase.dev).
# Quickstart
Source: https://docs.nearbase.dev/quickstart
Get a managed PostgreSQL database running in minutes
## Get Started
Nearbase gives you a fully managed, auto-scaling PostgreSQL database in Asia — no ops, no cloud expertise required.
Go to [console.nearbase.dev](https://console.nearbase.dev) and create your
account.
Add your payment method and top up your balance.
Pick a region, choose your instance size, and click create. Your PostgreSQL
database will be ready in 2–5 minutes.
Grab your connection string from the console and connect with any PostgreSQL
client or driver.
Create your first database now at console.nearbase.dev
## Available Regions
Nearbase is available in 10 regions. See [Regions](regions) for the full list.
## Connect to Your Database
Once your database is running, connect using any PostgreSQL client:
```bash theme={null}
psql "host=your-instance.nearbase.dev port=5432 dbname=postgres user=admin password=YourPassword sslmode=require"
```
Or in your application:
```javascript theme={null}
import pg from "pg";
const pool = new pg.Pool({
connectionString:
"postgresql://admin:YourPassword@your-instance.nearbase.dev:5432/postgres?sslmode=require",
});
const result = await pool.query("SELECT NOW()");
console.log(result.rows[0]);
```
Need help? Reach out at [team@m.nearbase.dev](mailto:team@m.nearbase.dev).
# Regions
Source: https://docs.nearbase.dev/regions
Available regions for your Nearbase PostgreSQL databases
## Available Regions
Nearbase databases are available across Asia-Pacific, the Middle East, and the United States.
| Region ID | City | Country |
| ---------------- | ------------ | -------------------- |
| `ap-northeast-1` | Tokyo | Japan |
| `ap-northeast-2` | Seoul | South Korea |
| `ap-southeast-1` | Singapore | Singapore |
| `ap-southeast-3` | Kuala Lumpur | Malaysia |
| `ap-southeast-5` | Jakarta | Indonesia |
| `ap-southeast-6` | Manila | Philippines |
| `ap-southeast-7` | Bangkok | Thailand |
| `cn-hongkong` | Hong Kong | Hong Kong |
| `me-east-1` | Dubai | United Arab Emirates |
| `us-east-1` | Virginia | United States |
## Choosing a Region
Pick the region closest to your application servers or end users for the lowest latency. All regions support the same instance sizes and features.
If you're unsure which region to start with, **Singapore** (`ap-southeast-1`)
offers central coverage across Southeast Asia. **Tokyo** (`ap-northeast-1`) is
optimal for Japan and East Asia.
***
## Compliance & Data Residency
Nearbase hosts your data entirely within the region you select. No data is replicated or transferred to other regions unless you explicitly provision instances there. This makes it straightforward to satisfy local data residency requirements.
| Regulation | Jurisdiction | Nearbase Regions |
| ---------------------------------------------- | ------------------- | ----------------------------------------------------------- |
| **PDPA** (Personal Data Protection Act) | Thailand, Malaysia | `ap-southeast-7` (Bangkok), `ap-southeast-3` (Kuala Lumpur) |
| **PDPO** (Personal Data (Privacy) Ordinance) | Hong Kong | `cn-hongkong` |
| **PIPL** (Personal Information Protection Law) | China-adjacent / HK | `cn-hongkong` |
| **PDPA** (Philippines Data Privacy Act) | Philippines | `ap-southeast-6` (Manila) |
| **UU PDP** (Indonesian Data Protection Law) | Indonesia | `ap-southeast-5` (Jakarta) |
| **PDPA** (Singapore PDPA) | Singapore | `ap-southeast-1` |
| **PDPL** (UAE Personal Data Protection Law) | UAE | `me-east-1` (Dubai) |
Nearbase provides infrastructure-level data residency. You remain responsible
for ensuring your application-level data handling complies with applicable
regulations. Consult your legal counsel for compliance guidance specific to
your use case.