Websites
Managed Addons: Postgres and Redis
The Addons tab lets you attach a managed PostgreSQL database or a managed Redis instance to a site without building or maintaining a server for it. Kapsule provisions it, gives you a connection string, and tears it down cleanly when you remove it.
Where Addons Live
Open Websites, click the site, open the Settings menu in the site tab strip, and choose Addons. The page is titled Managed addons.
Two options are in the catalogue:
| Addon | Typical use |
|---|---|
| PostgreSQL | The primary datastore for an application that is not on MySQL |
| Redis | Caching, session storage and background job queues |
These are separate from the MySQL database that ships with a standard hosting site. That one is on the Files, then Database tab and needs no provisioning: see Connecting To Your Database Over an SSH Tunnel.
Requesting an Addon
- Find the addon in the Add a managed database section.
- Click Add to site.
The request is recorded immediately and the addon appears in Your addons with a PENDING badge and the note Waiting for provisioner. The page refreshes itself every fifteen seconds, so you can leave it open.
A background job picks up pending requests every few minutes, creates a dedicated database and a dedicated user for your site, and writes back an encrypted connection string. The status then moves to ACTIVE.
Requesting or removing an addon needs the sites:write permission. Read-only team members can see which addons exist and their status, but the buttons are hidden.
One Of Each, Per Site
A site can hold one PostgreSQL addon and one Redis addon. Asking for a second of the same type is refused with a message saying it is already provisioned, and the catalogue hides an option once it is installed. When both are installed the catalogue section reads All available addons are installed.
Reading the Status
| Status | Meaning |
|---|---|
| PENDING | Requested, queued for the provisioner |
| PROVISIONING | Being created now |
| ACTIVE | Ready to use |
| FAILED | Provisioning did not complete; the reason is shown on the row |
| DELETED | Removed, no longer listed |
A FAILED row shows the actual error text underneath it rather than a generic message. If the reason is not something you can act on, quote it verbatim in a support ticket: see Opening a Support Ticket.
Getting the Connection String
Once an addon is ACTIVE, its row shows a masked connection string with the password replaced by dots, so you can confirm the host and database name at a glance without exposing the credential.
Click Copy connection to put the full connection string on your clipboard. It is decrypted server-side for that one request and never printed on the page, so screen shares and screenshots do not leak it. Every reveal is written to the site's audit trail and shows up in the Site Activity Log.
The string is in the usual URL form for each engine, carrying the host, port, user, password and database name that were created for this site.
Using It In Your Application
Paste the connection string into wherever your application reads its configuration. On a Node.js site, the right home for it is the Secrets tab, under a key such as DATABASE_URL or REDIS_URL, in the production environment.
Do not hard-code the connection string into a file you commit. It contains a live password. If it reaches a git remote it has to be treated as leaked, and the only real fix is to delete the addon and request a fresh one, because the credential cannot be rotated in place from the panel.
Removing an Addon
Click Delete on the row. KPanel asks you to confirm and is blunt about what happens: this removes the managed database, and the data is unrecoverable.
The row is marked deleted immediately and the provisioner tears down the underlying database and user on its next pass. Existing connections are terminated as part of that tear-down.
There is no backup taken of a managed addon on deletion, and no undo. If there is anything in it you want to keep, dump it first with pg_dump or redis-cli --rdb while the addon is still active and the connection string still works.
Choosing Between the Options
Use PostgreSQL when your application needs a relational database and is written against Postgres: strong constraints, transactions, JSON columns, and full-text search that you would otherwise have to bolt on.
Use Redis for things that are allowed to disappear: cached fragments, rate-limit counters, session storage, and job queues. Treat it as fast and volatile, not as a system of record.
Use the built-in MySQL database for WordPress and for anything already written against MySQL. Adding a Postgres addon to a WordPress site does nothing useful, because WordPress cannot talk to it.
Troubleshooting
The addon has been PENDING for a long time. The provisioner runs on a schedule rather than instantly. Leave the page open, since it refreshes itself, and check back. If it has not moved after a few passes, open a support ticket with the site domain and the addon type.
Provisioning FAILED. Read the error on the row. Delete the failed addon and request it again, which is safe: a failed row never had a live database behind it.
Copy connection does nothing. Some browsers block clipboard writes when the tab is not focused. Click on the page first, then click the button again.
The application cannot connect. Check three things in order: that the addon status is ACTIVE, that you copied the string rather than retyping it, and that your application is reading the value you actually set rather than a stale one from a previous deploy. A restart is usually needed before new configuration is picked up.
Connections are refused after a redeploy. Confirm the connection string in your configuration still matches the one on this page. Deleting and re-requesting an addon creates a new user and a new password, so an old string will not work.
Where To Go Next
- Storing App Secrets For a Site, the right place to keep the connection string.
- Connecting To Your Database Over an SSH Tunnel for the built-in MySQL database.
- Site Settings for the rest of the site-level configuration.