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.
• Instance type: The database Instance type to deploy. The Instance type determines the amount of CPU and RAM available and what limitations the Database Service may have.

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.

Database Instance types

A Database Service's instance type determines the resources it has available, its cost, and limitations. All plans can deploy a single Instance of the free type, which lets you deploy a Database Service with .25 vCPU and 1GB RAM at no cost. Instances are charged for usage by the second.

The following instance types are currently available:

Additionally, the free instance type has the following limitations:

• Active compute time per month: 50 hours
• Maximum size of stored data: 1 GB
• Maximum amount of data written per month: 1 GB
• Maximum amount of egress data per month: 1 GB

Connection limits

The Database Service's Instance type determines its connection limits. Specifically, the connection limit is derived from the Instance's RAM in bytes, divided by 9531392 bytes, rounded down.

For example, for Instances with 1 GB of RAM, the formula would look like this:

RAM: 1 GB = 1073741824 bytes
          ÷    9531392 bytes
          ------------------
                 ~ 112.653

  floor(112.653) = 112 connections

You can view a Database Service's maximum number of connections at any time by connecting with a client and executing:

SHOW max_connections;

Changing a Database Service's Instance type

To change a Database Service's Instance type 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 Settings tab.

In the General section of the settings page, select the Instance type you wish to use for your Database Service. Click Apply to confirm the procedure and alter the Instance type used by the Database Service.

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 bidirectional synchronization

Koyeb automatically detects and synchronizes changes between the Database Services management interface and the underlying PostgreSQL instances.

New logical databases or roles created directly in PostgreSQL will be reflected in Koyeb once synchronization completes. Changes made with the Koyeb Control Panel, CLI, or API will be reflected in the PostgreSQL instance as well.

How database bidirectional synchronization works

Understanding how the synchronization process works may help you avoid unexpected surprises.

Koyeb records the state of each Database Service within a deployment definition. Along with other pieces of metadata, the deployment definition describes the logical databases and roles that should be present within the Database Service. We create a new deployment definition whenever you change logical databases, roles, or role passwords with the Koyeb control panel, CLI, or API.

Approximately every ten minutes, we perform a synchronization check for each Database Service. This check compares the state of the most recent deployment definition against the actual state of the Database Service's PostgreSQL instance. If the actual state of the instance's logical databases and roles differ from the state described by the latest deployment definition, a new deployment definition is created.

Each time a new deployment definition is created, the regular synchronization schedule is temporarily suspended for 20 to 30 minutes. This "settling" time helps bundle multiple changes into a batch to reduce the number of new deployment definitions that need to be created when changes are actively being introduced. Once the settling time has elapsed, the regular synchronization cadence will begin again to pick up any additional changes.

Minimizing synchronization inconsistencies

The best way to avoid the inconsistencies that can arise between synchronization cycles is to exclusively use the Koyeb control panel, CLI, or API when managing roles or logical databases. These methods act directly on the Database Service management interface, so they can generate up-to-date deployment definitions immediately.

Whether you choose to manage logical databases and roles through Koyeb or directly with a PostgreSQL client, we recommend using the same method consistently. This will minimize the possibility of receiving outdated information since you will only be querying a single system.

Bidirectional synchronization and role passwords

It is important to note that role passwords that have been altered directly in PostgreSQL cannot be synchronized. This means that password information displayed in the Koyeb control panel, CLI, and API will remain inaccurate if you modify role passwords with a PostgreSQL client.

To avoid this problem, we recommend using Koyeb's interfaces for resetting role passwords. If you have previously managed role passwords with a PostgreSQL client, you can reset the password using the Koyeb control panel or CLI to generate new credentials that will be reflected in the Database Service's configuration.

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.pg.koyeb.app/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.pg.koyeb.app/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>

Resolve database connection errors

If you have problems connecting to your database, take a look at Neon's connection errors documentation (opens in a new tab). There, you can find detailed information about how to identify and resolve specific connection errors.

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.