Databases

Cloud runs PostgreSQL, MySQL, MariaDB, MongoDB and Redis as services of their own, each at a major version you choose. A database sits in a project beside the applications that use it, and they connect to it at its internal address. It has no public address until you turn public access on, and its password is what protects it either way.

1. Choose the engine

   Open the project and press Add a service. Under Databases, press Create on the engine you want.

2. Fill in the form

   The form is titled after the engine, such as "A PostgreSQL database", and asks for:

   • Version: the major version it runs. The newest is chosen for you.

   • Name: the service's name in the project, up to 40 characters. It starts as the engine's own name, such as postgres.

   • Size: the CPU and memory the database may use, and its rate. A database is charged by the data it holds, so the list shows each size's rate per GB-month.

   • Database name: PostgreSQL, MySQL and MariaDB only. app unless you change it.

   • Username: every engine except Redis. app unless you change it.

   • Password: generated in your browser when the page opens, 32 letters and digits. Generate another draws a new one, or type your own within the password rules.

   • Automatic backup: Daily, Weekly, Monthly or No automatic backup. Daily is the default. Redis has no backups, and the form says "Automatic database backups are not available for Redis." instead.

   The Order summary beside the form shows the size, its rate per GB-month, that it is charged by the data it holds for each hour it runs, and the backup cadence, before anything is created. On the nano size it also says how much data your first nano database across all your organizations holds free.

3. Create it

   Press Create service. The browser opens the new database's page. Nothing is running yet: the database is created without being started, so its name, user, version and password can still change.

4. Start it

   Press Deploy. The deployment's page opens and ends Done once the database is running, or Failed with "The database did not start within two minutes."

When the platform has no backup storage configured, Automatic backup is greyed out with "Automatic backups unavailable" and "Platform backup storage is not configured. You can still create this resource without automatic backups." Backups explains what a schedule covers and where the dumps go.

Until the database is deployed for the first time, the Connection card on its Overview reads "Choose its name, user, version and password now: the database writes them into its data the first time it starts, and they are fixed after that." It holds a small form:

• Database name and Username, for the engines that have them.

• New password, empty to keep the current one, with a button that generates one.

• Version, from the versions Cloud offers for that engine.

Press Save. The console answers "Saved. The database starts with these the first time it is deployed."

A name or a user is a lowercase letter followed by up to 31 lowercase letters, digits or underscores. MySQL and MariaDB keep root for themselves and refuse it as a user name.

From the first deploy on, even one that failed, the database name, the user and the version are written into the database's data and cannot change. The card then reads "The name, the user and the version were written into the database when it first started, and are fixed now." A change sent through the API is refused with "The name, the user and the version are written into the database's data when it first starts, and this one has. They can no longer change."

Moving to another version means a new database at that version and a copy of the data. The console's Restore is not available yet, so the copy is made by hand: Back up a database and restore it walks through it.

The eye button at the top of the card, Show the password, reveals the password and puts it into both addresses. The copy buttons always copy the real value, password included, even while the card shows dots.

The console describes the internal address as the one that "Services in this project reach it on". Copy it from Internal address and put it in the application's environment under the name your code reads, such as DATABASE_URL:

postgresql://app:<password>@<internal host>:5432/app

The internal host is the database's engine name, which the facts on its Overview also list. Each engine's page shows its address form.

Cloud keeps a password to letters, digits, dots, hyphens, underscores and tildes, so every address works exactly as the card shows it, with nothing to escape.

Once the database has started, the Password row has two buttons:

• Generate asks "Generate a new password?" and warns that "Services that connect with the old one stop connecting until their environment has the new one." Confirm with Generate.

• Set my own opens Set the password with a New password field. Press Change password. Left empty, it generates one.

A password is 12 to 128 letters, digits, dots, hyphens, underscores or tildes. The console answers "Password changed. Services that connect with the old one need the new one in their environment."

The password is changed inside the running database, so both buttons are disabled while it is stopped, and the card adds "The password changes inside the running database, so start it first." A change is also refused while a backup of the database is still running, with "This service has unfinished backup work."

Public access opens the database on a port of the platform's public address, for a tool on your own machine or a service outside Cloud.

1. On the Public address row, press Turn on. The confirmation says the database "opens a port on the internet, reached with its password alone. It restarts to open the port."

2. Confirm with Turn on. Cloud takes the lowest free port from 20000 to 29999 and restarts the database.

3. Copy the address from Public address once it appears.

Change port moves it to a port of your choosing, from 20000 to 29999 and free on the node, and restarts the database again. Turn off closes the port and restarts the database; anything connected through the public address loses its connection.

Stop is offered while the database is running or in error, and Start while it is stopped. Its data stays on its volume either way. Cloud charges a database for each hour it runs, so a stopped database adds nothing to your bill; Billing explains the metering.

A database is charged by the data it holds, not by the hour for its size. Once an hour Cloud measures its volume, the same figure the Storage screen shows, and for each hour the database runs charges the GB it held at its size's rate per GB-month, over 730 hours. The Overview section shows the figure under Data held, with when it was measured, and Charged says how the database is charged. Each month's statement has a line for the data it was charged for.

Your first nano database, counted across all your organizations, holds a set amount of data free, and is marked Free beside its state. Each GB past that is charged at the nano database rate. Billing explains the free allowance.

A database's size, under Settings, sets its rate and the CPU and memory Cloud holds it to. A new size is charged from the next hourly charge, and its limits apply at the database's next deploy. Sizes and replicas covers the sizes.

A database keeps its data on a volume of its own, named Data, which the Storage page lists with the database's data directory and the chip Managed by service. It survives deploys, stops and restarts, and it cannot be detached. Volumes explains the table.

• Logs, Metrics and a shell from Terminal work as they do for an application.

• Domains is absent: a database is reached by its address, never by a domain.

• Environment appears on a database's page, but a database takes no environment. What you save there is not kept.

Delete a database from Settings, under Delete this service, or from the project's table. The confirmation reads "Copy out any data you need first: no backup is taken." Type the service's name under Service name and press Delete service.

Before you delete, take a last dump: Back up now on its schedule, then Download it, as Backups describes.

• The automatic schedule is archived with the database. Dumps already in Backup history stay there, marked as belonging to a deleted service, and can still be downloaded.

• A schedule you added yourself must be archived first, and a backup still running must finish. Until then the delete is refused with "This service still has backup schedules or unfinished backups."

Delete refused lists every refusal and its fix.