Databases are currently available in public preview. Please use with caution and do not rely on it for critical operations.
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.
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.
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.
Warning: Database deletion is a permanent, destructive action. We cannot assist you in recovering data from a deleted database, so make sure that your database data is backed up or unnecessary before proceeding.
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.
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.
Note: New roles will not have permission to use existing database objects by default. To use your new role, either:
- Create a new database owned by the role, or
- Grant privileges on an existing database object to the new role. You can do this using the
GRANTcommand (opens in a new tab) when authenticated as the owner of the database or database object.
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.
Warning: Resetting a role password invalidates the previous password, preventing it from being used to authenticate new sessions. Be aware that existing sessions will not be affected by the change in credentials. Remember to adjust the credentials for any clients or applications configured to use the previous password.
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.
Note: You cannot delete roles that own databases. You must first delete any databases owned by the role before you can delete the role itself.
Warning: Database Service deletion is a permanent, destructive action. We cannot assist you in recovering data from a deleted Database Services, so make sure that your database data is backed up or unnecessary before proceeding.
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.
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:
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:email@example.com/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:
postgresql://: The schema identifier that indicates that the connection string is for a PostgreSQL database. Most clients accept both
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 (
- 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.
You can connect to your databases with any PostgreSQL-compatible library or client. Below are some examples using popular clients and database connectors:
You can manage PostgreSQL extensions using the administrative role created with your database (by default
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;
You can view currently installed extensions by typing:
\x\g\x line termination sequence instead of the semicolon (
;) turns on vertical output for the
current command. This can help improve readability over the default display for long lines of text.
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.
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.
To remove a currently installed extension, type:
DROP EXTENSION <extension_name>
The extension will be removed from your database.
Koyeb's PostgreSQL databases support the following extensions:
Be aware of the following limitations when using Koyeb Database Services.
In the current preview release state, Database Services are available in the following regions: Frankfurt (Germany), Washington, D.C. (USA), and Singapore (Singapore).
Currently, PostgreSQL versions 14, 15, and 16 are supported.
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.