0 Fork 0

mirror of https://github.com/tiennm99/keepalive.git synced 2026-10-11 03:13:31 +00:00

Files

T

tiennm99 e445b5cbc5 docs: move reference material from the README into docs

The README now covers what keepalive is, a quick start, the adapter table,
and links. Reference material moves to docs/: configuration (every option,
per-adapter keys, validation), deployment (Compose, Coolify, Docker, source),
how it works (writes, retries, timeouts, logging), known issues (PostgreSQL
public-schema permissions and Aiven's ACL key-pattern tilde, by log line),
and adding an adapter (now including ConfigKeys registration).

.gitignore also excludes config.yaml, matching .dockerignore.

2026-10-09 12:37:52 +07:00

2.9 KiB

Raw Blame History

keepalive

Stop free-tier databases from pausing. keepalive is a tiny Go daemon that writes to each of your hosted datastores on a schedule, so idle-shutdown policies never trigger.

One config, many services. Keep Redis, PostgreSQL, MySQL, MongoDB, and Couchbase instances alive from a single process.
Cheapest possible write. Each tick increments one counter; nothing else in your database is touched.
Self-healing. Failed services retry every minute and recreate their counter if it disappears, without affecting the others.
Small and safe. A static, distroless, non-root image with no ports, and connection strings are kept out of logs.

Works with Redis Cloud, Upstash, Aiven (PostgreSQL, MySQL, Valkey), Supabase, YugabyteDB, CockroachDB, MongoDB Atlas, Couchbase Capella, and any self-hosted Redis-, Valkey-, PostgreSQL-, MySQL-, MongoDB-, or Couchbase-compatible server.

Quick start

Write a config.yml:

interval: 1h

services:
  - name: upstash
    adapter: redis
    config:
      url: rediss://default:PASSWORD@example.upstash.io:6379

  - name: supabase
    adapter: postgresql
    config:
      url: postgresql://USER:PASSWORD@aws-0-region.pooler.supabase.com:5432/postgres?sslmode=require

  - name: atlas
    adapter: mongodb
    config:
      uri: mongodb+srv://USER:PASSWORD@cluster0.example.mongodb.net
      database: keepalive
      collection: counter

Run it:

git clone https://github.com/tiennm99/keepalive && cd keepalive
# put your config.yml here (see config.example.yml for every adapter)
docker compose up -d --build
docker compose logs -f

Each service logs a line like [upstash] counter: 42 on every tick.

Adapters

`adapter`	Use it for
`redis`	Redis, Valkey, Dragonfly, KeyDB, Garnet, Upstash, Redis Cloud
`postgresql` / `postgres`	PostgreSQL, Supabase, Aiven, YugabyteDB, CockroachDB
`mysql`	MySQL, MariaDB, Aiven for MySQL, TiDB
`mongodb` / `mongo`	MongoDB Atlas, Azure DocumentDB, FerretDB, Cosmos DB for MongoDB
`couchbase`	Couchbase Capella and self-hosted Couchbase

Documentation

Configuration: every option, per-adapter keys, and validation rules.
Deployment: Docker Compose, Coolify, plain Docker, and running from source.
How it works: what each adapter writes, retries, timeouts, and shutdown.
Known issues: permission errors and other setup problems, by log line.
Adding an adapter: plug in a new datastore.

License

Apache-2.0. See LICENSE.