Choose a dedicated database #

View this page as Markdown

On this page

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 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. 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 for the full contract and Refusals for the returned refusal.