Add a database to your app
Give your app a PostgreSQL, MongoDB or Redis database without installing anything. You manage a project's databases in the portal: open Projects, pick the project, then go to Data.
Cairn runs the databases on your server. Each project environment gets its own database and its own user, so one project cannot read another project's data.
The quickest way: ask the SDK
Add databases when your app starts the Cairn SDK. Cairn creates whatever is missing and connects for you:
import platform from '@mpratyush54/sdk-node';
await platform.init({
projectName: 'shop',
platformUrl: process.env.PLATFORM_URL,
sdkToken: process.env.PLATFORM_SDK_TOKEN, // a server token
environmentName: 'development',
databases: ['postgres', 'mongo', 'redis'],
});
const { rows } = await platform.db.postgres.query('SELECT 1 AS ok');
await platform.db.redis.set('hello', 'world', 60); // expires after 60 seconds
Python works the same way with databases=["postgres", "mongo", "redis"]. See the Python quickstart.
You need a server SDK token. Create one in the project's Settings, under SDK tokens. See Your first project.
Without the SDK: create a PostgreSQL database in the portal
You need the DevOps role.
- Open the project and go to Data.
- Under Provision database, choose the environment: Production, Staging or Preview.
- Select Provision database and confirm.
- Copy the credentials that appear. The password is shown only once.
The credentials are also saved as secrets of that environment, so your app can read them without you pasting anything.
Where the credentials are
Cairn saves the credentials as secrets of the project environment. Your app reads them like any other setting:
| Database | Secrets |
|---|---|
| PostgreSQL | POSTGRES_HOST, POSTGRES_PORT, POSTGRES_USER, POSTGRES_PASSWORD, POSTGRES_DB |
| MongoDB | MONGO_URI, MONGO_USER, MONGO_PASSWORD, MONGO_DB |
| Redis | REDIS_HOST, REDIS_PORT, REDIS_USERNAME, REDIS_PASSWORD, REDIS_KEY_PREFIX |
Redis is shared between projects. Each project can only use keys that start with its REDIS_KEY_PREFIX.
To see these values, open the project and go to Configuration. See Secrets for how secrets reach your app.
Check on your databases
The project's Data section shows:
- Database insights: the slowest PostgreSQL queries, slow MongoDB operations and Redis key counts. This needs the
fullinstall profile. See Database monitoring. - Database connections: each saved connection, with a Test connection button.
- Database backups (DevOps role): back up and restore the project's PostgreSQL database. See Back up one project database.
Keep the data safe
- Back up the whole server with encrypted, off-site backups. See Backups and restore.
- Run on several servers for automatic failover. See High availability.
How it works
- The databases run in the cluster's
databasesnamespace. Project databases and users are namedplat_<project>_<environment>andplat_<project>_<environment>_user. - The portal's Provision database button creates PostgreSQL only. MongoDB and Redis are created when the SDK asks for them.
- Each project gets its own Redis user. Its access rules allow only keys and channels that start with the project's prefix, and block admin and dangerous commands.
- On a high availability install (
haprofile), the Redis secrets also includeREDIS_SENTINELS,REDIS_SENTINEL_MASTER,REDIS_SENTINEL_USERNAMEandREDIS_SENTINEL_PASSWORD, so clients can find the current Redis primary.
For developers / API
- Provision from the API:
POST /api/projects/<projectId>/databases/provisionwith{ "environment": "production" }. DevOps role required. See the Databases API. - SDK database clients: Node.js PostgreSQL, MongoDB, Redis; Python PostgreSQL, MongoDB, Redis.
- File storage instead of a database: File storage providers.