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

# Dedicated databases

> Create a Dedicated PostgreSQL database, connect to it, resize it and manage its lifecycle.

> [!NOTE]
>
> **Not yet released.** This guide describes implemented changes awaiting rollout. Availability requires the corresponding backend and dashboard release.

## Goal

Run a business-critical PostgreSQL database on its own virtual machine.

## Prerequisites

* Dedicated switched on for your account
* A wallet balance or a saved card for billing

## Workflow

**Step 1**

List sizes with `stackshift database instance-classes` and pick one.

**Step 2**

Create the database with `stackshift database create --data '{"tier":"dedicated", ...}'` or `POST /api/v1/databases`, giving the size, storage and billing period. Save the master password from the response: it is shown only once.

**Step 3**

If the response says payment is required, open the checkout link and pay. The database starts as soon as the payment is confirmed.

**Step 4**

Connect your app through its project binding, or with the connection details on the database page.

**Step 5**

Check it is running with `stackshift database get DATABASE` and run a real query from your app. `stackshift database billing DATABASE` shows what you are paying.

## Create

* `name`: 3 to 40 lowercase letters, digits and dashes. `version`: 15 to 18 (default 17).
* `type` is `postgres`. MySQL on Dedicated isn’t available yet and the API answers `403` for it.
* `storage_gb`: 10 to 1024. `storage_max_gb` is the autogrow limit (default twice `storage_gb`, at most 1024).
* `master_username` defaults to `app_owner` and `database_name` to `app`.
* `backup_retention_days`: 7 to 35 (default 7). This is how far back you can restore.
* `maintenance_window`: day 0 (Sunday) to 6 and a start minute after midnight. If you leave it out, we pick one for you.
* `billing`: `monthly` (default), `yearly` or `hourly`. `standby`: `off` (default), `sync` or `async`, with `on_standby_loss` `degrade` (default) or `block`. See Standby and high availability.
* `deletion_protection`: `true` refuses deletion until you turn it off.
* If no server has room for that size right now you get “We’re adding capacity for this database size, please try again shortly.” Nothing is charged.

```json POST /api/v1/databases theme={null}
{
  "name": "orders-db",
  "type": "postgres",
  "tier": "dedicated",
  "version": "17",
  "instance_class": "s-2vcpu-4gb",
  "storage_gb": 50,
  "storage_max_gb": 200,
  "backup_retention_days": 14,
  "billing": "monthly",
  "standby": "off",
  "deletion_protection": true,
  "maintenance_window": { "day_of_week": 0, "start_minute": 120 }
}
```

## Connect

* Apps on StackShift reach the database privately; bind it to your app and the connection variables are set at deploy.
* Each database has a direct endpoint and a pooled endpoint (PgBouncer). Use the pooled one for app traffic and the direct one for migrations.
* Connections always use TLS. Download the CA certificate from the database page and keep certificate checks on.
* Turn on public access for a laptop or an external service, preferably limited to your IP addresses.
* Extensions such as `vector` and `postgis` install with `CREATE EXTENSION` as the master user.

## Day-to-day

* Change size: `stackshift database resize DATABASE --data '{"instance_class":"d-2vcpu-8gb","apply":"window"}'`. The switch happens in your maintenance window (or now with `"apply":"now"`), and connections drop for a few seconds. Cancel a scheduled change with `stackshift database resize-cancel DATABASE`.
* Storage grows by itself before it fills up, without downtime, up to `storage_max_gb`. Raise the limit or grow it yourself with `stackshift database storage DATABASE --data '{"storage_gb":100,"storage_max_gb":400}'` (`PATCH /api/v1/databases/{id}/storage`). Growing storage by hand is a priced change, so you confirm the charge first.
* Stop, start and restart from the database page or with `stackshift database stop|start|restart DATABASE`. A stopped database starts again automatically after 7 days. Its storage is still billed while stopped.
* Change `name`, `deletion_protection`, `backup_retention_days` (7 to 35) or `maintenance_window` in place with `stackshift database settings DATABASE --data '{"deletion_protection":false}'` (`PATCH /api/v1/databases/{id}`). Leave out what you don’t want to change. Renaming works on every tier and never changes the database’s addresses; a name another database already uses is refused. The other three settings are Dedicated only. A size change waiting for the window moves with the new window.
* Tune PostgreSQL with parameter groups, choose the weekly window for updates, and move to a newer PostgreSQL version when you are ready. See Parameter groups, Maintenance window and updates, and PostgreSQL version upgrades.
* See what your database is busy with, and what happened to it, in Performance Insights and the events feed. Take a fast restore point before a risky change where it is offered.
* Deleting takes a final snapshot first unless you ask to skip it (`?skip_final_snapshot=true`). With deletion protection on, deletion is refused until you turn it off.

## Availability

Dedicated databases are rolling out. If Create doesn’t offer Dedicated, it isn’t switched on for your account yet, and the API answers `403`.

## Expected result

> [!TIP]
>
> The database is running on its own virtual machine and your app reads and writes data.

## Common failures

> [!WARNING]
>
> * `402 payment_required`: open `checkout_url` and pay. An unpaid database is removed after 24 hours.
> * `409 price_confirmation_required` on a change: the response shows the charge; send the same request again with `confirm_charge_minor` set to that amount. See Dedicated billing.
> * `409` “We’re adding capacity…”: try again shortly; nothing was charged.
> * `403` when creating MySQL on Dedicated: it isn’t available yet. Create a PostgreSQL database, or use a Starter MySQL database.
> * Permission denied for a superuser-only command: the master user is not a superuser on Dedicated. Use the allowed extensions and roles instead.

## Related guides

> **[Starter or Dedicated](https://docs.stackshift.cloud/databases/starter-and-dedicated.md)**
>
> Starter databases share a server with other databases. A Dedicated database is its own virtual machine with a standby, read replicas and restore to any second.

> **[Standby and high availability](https://docs.stackshift.cloud/databases/standby-and-high-availability.md)**
>
> Add a standby on another server. If the primary fails, the standby takes over and your connection address stays the same.

> **[Restore to any second](https://docs.stackshift.cloud/databases/point-in-time-restore.md)**
>
> Dedicated databases archive every change, so you can restore to an exact second. A restore always creates a new database.

> **[Fast restore points](https://docs.stackshift.cloud/databases/fast-restore-points.md)**
>
> Take a quick restore point before a risky change and roll the database back to it in minutes. Offered on some servers only.

> **[Performance Insights and events](https://docs.stackshift.cloud/databases/performance-insights-and-events.md)**
>
> See what a Dedicated database spends its time on, find its slowest queries, and read a feed of failovers, backups and maintenance.

> **[Parameter groups](https://docs.stackshift.cloud/databases/parameter-groups.md)**
>
> Tune PostgreSQL settings such as work\_mem or statement\_timeout for one or many Dedicated databases with a reusable parameter group.

> **[Maintenance window and updates](https://docs.stackshift.cloud/databases/maintenance-window.md)**
>
> Choose the weekly window when StackShift updates your Dedicated database, see what is waiting, and apply it now if you prefer.

> **[PostgreSQL version upgrades](https://docs.stackshift.cloud/databases/postgresql-version-upgrades.md)**
>
> Upgrade a Dedicated database to a newer PostgreSQL major version, in place with a short outage or blue/green with a switch that takes seconds.

> **[Dedicated billing](https://docs.stackshift.cloud/databases/dedicated-billing.md)**
>
> Pay for a Dedicated database monthly, yearly or by the hour, from your wallet or card.

> **[PostgreSQL and extensions](https://docs.stackshift.cloud/databases/postgresql.md)**
>
> PostgreSQL 15 to 18 with pgvector, PostGIS, pg\_cron and more, ready to turn on with one SQL statement.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.