Databases

Koyeb Database Services allow you to deploy serverless PostgreSQL databases alongside your Apps and Services on the Koyeb platform. You can use databases to store data independent from your application deployment lifecycle, allowing you to maintain persistence while still benefiting from a serverless experience.

Koyeb Database Services are managed PostgreSQL database clusters (opens in a new tab). Each Database Service can define multiple logical databases (opens in a new tab) that contain tables, indexes, views, and more.

Create a Database Service

To create a new Database Service in the Koyeb control panel (opens in a new tab), click the Databases tab in the top navigation ribbon.

On the following page, click Create Database Service. In the Database Service creation form, configure the following options:

• Name: The name of the Database Service in Koyeb.
• Region: The region to deploy your database to. Currently, the following regions are available for Database Services: Frankfurt (Germany), Washington, D.C. (USA), and Singapore (Singapore).
• Engine: The database type and version to deploy. Currently PostgreSQL database versions 14, 15, and 16 are available.
• Default role: The default role (username) that will be created to manage your database. This role owns the default logical database and has administrative privileges allowing it to create databases, create other roles, and manage PostgreSQL extensions.

When you are finished, click Create Database Service to deploy your new PostgreSQL database. You will be taken to the Database Service's detail page where you can view connection information, see usage statistics, and manage the database lifecycle.

Within the Database Service, a logical database called koyebdb will be created owned by the default role you configured above.

Manage databases within a Database Service

To manage logical databases within your Database Service in the Koyeb control panel (opens in a new tab), click the Databases tab in the top navigation ribbon and then select the Database Service you want to manage. On the Database Service's detail page, click the Databases tab.

To create a new logical database, click Create Database. In the database creation form, select a name for the new logical database and select an owner from the list of roles. Click Create to create the new logical database.

To delete an existing logical database, click the trashcan icon associated with the logical database. On the form that appears, confirm the operation by entering the name of the logical database you wish to delete. Click the Delete button to delete the database.

Manage database roles

In PostgreSQL, Database roles (opens in a new tab) fulfill the functions of both users and groups. They are used to authenticate to the system, can own or be granted permissions on various database objects, and can confer privileges through membership relationships.

When you create a new Database Service on Koyeb, a default role is created as well. If you do not choose an alternative during the initial configuration, this role will be called koyeb-adm. The default role is assigned the credentials to authenticate to the system and owns the initial database (called koyebdb) created within the Database Service.

You can create, delete, and manage other roles from the Database Services tab within the Koyeb control panel (opens in a new tab). Click on your Database Service and then click the Roles tab to view or modify the roles for your Database Service.

To create a new role, click Create Role. In the role creation form, provide a name for the new role and click Create Role again. The new role will be created and a password will be automatically generated for it, allowing you to authenticate.

To authenticate with a role, log in with your database client using the role name and the generated password. You can reveal the role password by clicking the view icon.

If you need to reset a role's password, click the password reset icon associated with the role. Confirm the operation by typing the role's name in the reset form and clicking Reset. A new password will be generated and the previous value will no longer be valid.

To delete a role, click the trash icon associated with the role. In the role deletion form, type the name of the role to confirm the operation and then click Delete.

Delete a Database Service

To delete a Database Service in the Koyeb control panel (opens in a new tab), click the Databases tab in the top navigation ribbon and then select the Database Service you wish to delete.

On the Database Service's detail page, click the Settings tab. In the Danger Zone section of the settings page, click the Delete button. A prompt will appear asking you to confirm the operation by typing the name of your Database Service. To delete your Database Service, type its name and click Delete.

You will be redirected back to the Database Services overview page (opens in a new tab) and your Database Service and the deletion process will begin.

Understanding database connection strings

The database's connection string (sometimes called the connection URL) contains details about how to connect to the database and authenticate using a username and its credentials.

You can find your database's connection string by visiting the Connection Details tab of your Database Service and selecting the appropriate database from the Database drop down menu. The psql option shows a standard connection string that will look something like this:

postgres://koyeb-adm:********@ep-falling-star-29440178.eu-central-1.aws.neon.tech/koyebdb

The connection string is displayed with the password field shielded by default.

From here, you can click the copy icon associated with the connection string to copy the value to your clipboard. You can also click the view icon within the connection string to reveal the role password.

Many clients and libraries accept connection strings directly, but some require each property to be given discretely. If your client or language is not one of the options show, you can find the relevant individual properties by viewing the .env option or by looking within the connection string itself.

postgres://koyeb-adm:somepassword@ep-falling-star-29440178.eu-central-1.aws.neon.tech/koyebdb
└───┬─────┘└───┬───┘ └────┬─────┘ └─────────────────────┬───────────────────────────┘ └──┬──┘
    │          │          │                             │                                └── The name of the database to connect to
    │          │          │                             └── The database service's hostname
    │          │          └── The password for the given PostgreSQL role
    │          └── The PostgreSQL role (username) to connect with
    └── Identifies this as a PostgreSQL connection string

The connection string contains the following fields:

• postgres:// or postgresql://: The schema identifier that indicates that the connection string is for a PostgreSQL database. Most clients accept both postgres:// or postgresql://, but check your library's documentation to be sure.
• role / username: The PostgreSQL role or username to authenticate with. This field begins after the :// delimiter until the colon character (:) that begins the password field.
• password: The password for the given PostgreSQL role. This field begins with the colon character (:) and ends at the at-symbol (@) delimiter.
• hostname: The hostname where the database service is running. This field begins with the at-symbol (@) and continues until a forward slash (/) or colon (:).
• port: The port where the database service is running. This field is absent from Koyeb's connection strings because Koyeb's database services run on PostgreSQL's default port: 5432. For connection strings that contain port information, the field follows the hostname and begins with a colon character (:) and continues until a forward slash (/).
• database: The name of the individual database to connect to on the database service.

Connecting to your databases

You can connect to your databases with any PostgreSQL-compatible library or client. Below are some examples using popular clients and database connectors:

psql postgres://<DB_ROLE>:<DB_PASSWORD>@<DB_HOSTNAME>/<DB_DATABASE_NAME>

Managing PostgreSQL extensions

You can manage PostgreSQL extensions using the administrative role created with your database (by default koyeb-adm).

View available extensions

This page includes a list of supported extensions for various PostgreSQL versions and notes that might affect their installation and use.

You can also query your database itself for a list of the extensions that it is able to install. To do so, type:

SELECT * FROM pg_available_extensions;

View installed extensions

You can view currently installed extensions by typing:

SELECT * FROM pg_extension;

The output will look something like this:

  oid  | extname | extowner | extnamespace | extrelocatable | extversion | extconfig | extcondition
-------+---------+----------+--------------+----------------+------------+-----------+--------------
 12753 | plpgsql |       10 |           11 | f              | 1.0        |           |
(1 row)

Here, you can see the extensions currently installed on your database, as well as information about their version and configuration.

Install a new extension

To install an extension, type:

CREATE EXTENSION <extension_name>

The results will display the extension name, the default and installed versions, as well as a comment field describing the primary function of the extension.

Remove an extension

To remove a currently installed extension, type:

DROP EXTENSION <extension_name>

The extension will be removed from your database.

Supported extensions

Koyeb's PostgreSQL databases support the following extensions:

Limitations

Be aware of the following limitations when using Koyeb Database Services.

Regions

In the current preview release state, Database Services are available in the following regions: Frankfurt (Germany), Washington, D.C. (USA), and Singapore (Singapore).

Database engine support

Currently, PostgreSQL versions 14, 15, and 16 are supported.

Database sleep and idle behavior

Databases follow the serverless pattern by freeing resources that are not being actively used. After 5 minutes of inactivity, your database's compute resources will automatically sleep. They wake up at the first new query with only a minor delay.