Kener Docs
llms.txt
Search Documentation
Search through all documentation pages
Setup Guide

Database Setup

Configure SQLite, PostgreSQL, or MySQL database for Kener

Kener stores monitor data, incidents, and subscriptions in a relational database.

Supported databases:

  • SQLite (default)
  • PostgreSQL (recommended for production)
  • MySQL

Quick configuration

Set DATABASE_URL in .env.

# Default (if omitted)
DATABASE_URL=sqlite://./database/kener.sqlite.db

# PostgreSQL
DATABASE_URL=postgresql://user:password@host:5432/kener

# MySQL
DATABASE_URL=mysql://user:password@host:3306/kener

Kener detects the database from the URL prefix:

  • sqlite://
  • postgresql://
  • mysql://

Minimum server sizing (CPU/RAM)

Note

Based on practical Kener v4 deployment patterns (app + Redis + relational DB). If you scale monitor count or retention, scale resources accordingly.

Kener app instance

Workload vCPU RAM Typical use
Minimum 1 512MB Testing, small personal setup
Recommended 1 1GB Small production (up to ~100 monitors)
Higher load 2 2GB+ 100+ monitors, higher request volume

Database service

Database Minimum Recommended
SQLite Uses app disk/RAM SSD storage, regular backups
PostgreSQL 1 vCPU / 512MB 1 vCPU / 1-2GB
MySQL 1 vCPU / 512MB 1 vCPU / 1-2GB

SQLite

Good for single-instance and simple deployments.

DATABASE_URL=sqlite://./database/kener.sqlite.db

Custom path example:

DATABASE_URL=sqlite:///var/lib/kener/kener.db

PostgreSQL

Recommended for production and multi-instance deployments.

DATABASE_URL=postgresql://kener:password@localhost:5432/kener

With SSL:

DATABASE_URL=postgresql://user:pass@host:5432/kener?sslmode=require

MySQL

Use when MySQL/MariaDB is your standard stack.

DATABASE_URL=mysql://kener:password@localhost:3306/kener

Connection pool tuning

For PostgreSQL and MySQL, Kener ships fail-fast, self-healing pool defaults: no permanently-idle connections, TCP keepalive on, and 15-second connection timeouts. This protects deployments on cloud networks (Railway, Docker Swarm overlays, Kubernetes) that silently drop idle TCP connections, which otherwise causes 500s after idle periods and can require a restart after a database outage.

Override only if your setup needs it:

Variable Description Default
DATABASE_POOL_MIN Minimum pool connections (0 lets idle connections be reclaimed) 0
DATABASE_POOL_MAX Maximum pool connections 10
DATABASE_ACQUIRE_TIMEOUT_MS How long a query waits for a free connection before failing 15000
DATABASE_CREATE_TIMEOUT_MS How long a new connection attempt waits before failing 15000
DATABASE_IDLE_TIMEOUT_MS How long a connection may sit idle before being closed 30000
DATABASE_KEEPALIVE TCP keepalive on connections (true/false) true

Tip

If your database is slow to accept connections (cold starts, cross-region), raise DATABASE_ACQUIRE_TIMEOUT_MS and DATABASE_CREATE_TIMEOUT_MS instead of disabling keepalive or raising DATABASE_POOL_MIN.

These variables have no effect on SQLite.

Switching databases

  1. Backup/export data.
  2. Update DATABASE_URL.
  3. Restart Kener.

Warning

Switching databases does not migrate existing data automatically.

Troubleshooting

  • Connection failed: verify host, port, credentials, firewall.
  • Migration failed: ensure DB exists and user can CREATE/ALTER.
  • SQLite write error: ensure directory exists and is writable.
  • KnexTimeoutError: Timeout acquiring a connection: the database is unreachable or too slow to accept connections — check database health first, then see Connection pool tuning.
  • Connection terminated unexpectedly after idle periods: the network dropped an idle connection; keepalive (on by default) prevents this — verify DATABASE_KEEPALIVE is not set to false.

Environment variables

Variable Description Default Required
DATABASE_URL Database connection string sqlite://./database/kener.sqlite.db No

Pool tuning variables are listed in Connection pool tuning.