---
title: Choose a dedicated database
description: Choose a PostgreSQL server for your production database, approve the move, and follow it through completion or a return to the source server.
slug: /guides/choose-a-dedicated-database
order: 53
visibility: public
redirects_from: []
---

# Choose a dedicated database

Prompt:

> Move my production database onto a server of its own.

A dedicated database gives your application's production database its own PostgreSQL server in the same cell and region. The development database stays on a shared server.

A dedicated size must be supported on the platform you are using. For a billed account, it must also be opened to that account. A refused request answers `database_size_not_open` if either condition is unmet. The answer names the account's open sizes, says none are open, or explains that this platform serves no dedicated size.

## What to choose

Choose a dedicated size when you want a production database on a server reserved for your application. Your application must be a server application with a provisioned production database. A serverless application's database stays shared; requesting a dedicated size for it is refused.

| Size | Memory | CPU cores |
| --- | --- | --- |
| `database-dedicated-2gb` | 2 GiB | 1 |
| `database-dedicated-4gb` | 4 GiB | 2 |
| `database-dedicated-8gb` | 8 GiB | 2 |

These servers have burstable CPU. After their CPU credits are spent, they run at their base CPU share. The core count is not a promise of sustained full-core performance.

Backups are kept for 35 days and are geo-redundant. The server runs in one zone. A host failure can cause a restart at any time; scheduled maintenance is Sunday, 14:00–15:00 UTC.

You can later choose another dedicated size or `database-shared` to move back to a shared server. Each change moves the production database and interrupts its service.

### The charge

A dedicated database is a monthly item, charged in advance at the start of the UTC month, or for the days left if added later, including that day. Read the current [pricing](https://turnzero.ai/pricing) and the charge information on the approval page before approving the move.

The move's charge is checked again when the target server is ready, before production is frozen. If the charge cannot be posted, the move stops before that interruption. If the move fails after the charge posts, the month's line remains. It covers another attempt at the same size in that UTC month. Leaving a size or moving to a smaller one gives no credit back.

The dedicated charge covers the application's development database too, although that database stays on a shared server. From the first daily pass after the move, the application is no longer counted for `database-shared`. The shared line already charged in the move's month stays.

Each dedicated size is a separate monthly item. Moving to a different dedicated size can start a new charge for the days left, even when it is smaller. No new line is needed if the number already charged for that size this month covers the number you will hold.

## What changes during the move

The platform prepares the target server, freezes production, copies the database, switches its connection and redeploys the production application. Production is unavailable from the freeze until the new deployment succeeds, or a revert restores the source. Preparing the server can take time before the interruption begins. There is no fixed completion time.

A production deploy or promote is refused throughout the move, including while the server is being prepared.

The application, hostname, environments, code, database and role names, and runtime setting names stay the same. The development database and stored files stay in place. Production receives the new server's password, host and connection limit.

### Connections and a move back

On a dedicated server, both `APP_DATABASE_URL` and `APP_DATABASE_DIRECT_URL` use the direct port, 5432. Set each process's client-pool maximum from `APP_DATABASE_CONNECTION_LIMIT`. The move's redeploy injects the limit for the new size; keep reading that setting rather than fixing a number in the code.

A move back to shared keeps the direct address initially. The pooled address, port 6432, returns at the next promote or production deploy of a version that recorded the pooled port. A restart alone does not establish that condition.

The shared transaction pooler holds a server connection for one transaction. Before moving back, check code that relies on [one server session](/cloud/guides/add-a-database/#work-that-needs-one-server-session). Features that worked through the direct address may not work through transaction pooling.

## Before your AI starts

You need a signed-in Turn Zero Cloud connection and the application you want to change. Tell your AI tool which size you choose and when production can be interrupted. Read the approval page yourself; approving it starts the move.

Changing the size starts another copy of the database. If an earlier move left a kept copy, starting the next move removes that earlier copy first.

## What your AI does

You confirm the application and the owner's chosen size, request its browser approval, then follow that specific move until it ends. You do not pick another size or start a second move to recover from an uncertain response.

## Steps

These steps are for your AI tool.

### 1. Confirm the application and size

Use `tzcloud_list_applications` to identify the application and `tzcloud_read_status` to read its production state. Confirm that it is a server application with a provisioned production database. Ask the owner to choose a size if they have not named one, and confirm the interruption is acceptable. If nobody answers, leave the database unchanged and report that choice is needed.

Check for an unfinished database move or production deploy. Follow an existing move rather than requesting another. The size argument is one of the three dedicated names above, or `database-shared` for a move back.

### 2. Request approval

Call `tzcloud_set_database_size` with `application`, the chosen `size` and a fresh `request_id`. Make this request only when the owner asks for the change. Hand the returned approval URL to the owner and wait for their decision in the browser.

A pending action means approval is needed. A decline or expiry leaves the database unchanged. Use `tzcloud_read_approval_status` to follow the decision. Its successful result confirms that the move started; it does not confirm that the database finished moving. Keep the returned move ID.

If a response is lost, read the approval and application state before repeating anything. The same `request_id` returns the same pending action while it is live; after it ends, using that ID starts a new pending action.

### 3. Follow the move to its end

Call `tzcloud_read_status` for the application with `wait_seconds: 45`. Read `application.environments.production.database_move` and match its ID to the move you started. An earlier completed move is not proof that this request succeeded.

Read its `phase`, `started_at`, `ended_at` and `outcome`. While `outcome` is null, continue reading status. The wait remains unsettled while a move is unfinished.

- `done`: the database moved and the production redeploy succeeded.
- `reverted`: the move did not complete; the source remains or has been restored. Report this result to the owner before considering another attempt.

The ended move stays in status until the next move starts. If status does not establish an outcome, report what you can read and keep following it. Do not infer success from approval or repeat the change merely because it took longer than expected.

### 4. Check the application

After `done`, use an existing read-only application check to confirm that production serves and can read its data. Confirm that the application's pool reads the injected connection limit. Report the chosen size and the final move outcome; do not create or change production records just to test the move.

## Expected result

The matching production move has an `ended_at` and `outcome: done`. Your application serves from the new database, its pool uses `APP_DATABASE_CONNECTION_LIMIT`, and its development database is unchanged.

## Refusals

| Code | Cause | Remedy |
| --- | --- | --- |
| `database_size_not_open` | This platform serves no dedicated size, or the requested size is not open to this billed account. | Read the sizes the answer names, or its statement that none are open. Report it to the owner; do not substitute a size. |
| `database_move_in_flight` | A move is unfinished, or an earlier move has ended but its work is still stopping. | Follow the move to its end. If its work is still stopping, repeat in a minute. A production deploy or promote also waits for the move's end. |
| `deploy_in_flight` | A production version is still in flight. | Follow the production deploy to its end before asking for a move. |
| `balance_short` | The usage balance is not more than the new charge. | Read the answer's charge and balance explanation with the owner before another request. |
| `dedicated_capacity` | The cell, region or concurrent-move bound is full. | Report the capacity bound named in the answer. |
| `invalid_request` | The size is outside the four allowed values, production already has that size, or a serverless application requested a dedicated size. | Check the size, whether it is already selected, and whether the application is serverless. |

This table covers common refusals. Read the [action reference](/cloud/reference/actions/set-database-size/) for the full contract and [Refusals](/cloud/reference/refusals/) for the returned refusal.

## Related

- [Add a database](/cloud/guides/add-a-database/) for declaring the database and connecting your code.
- [Database package](/cloud/backend-packages/database/) for the pool and migration helpers.
