mirror of
https://github.com/tiennm99/keepalive.git
synced 2026-10-13 16:15:01 +00:00
83 lines
3.2 KiB
Markdown
83 lines
3.2 KiB
Markdown
# keepalive
|
|
|
|
Pluggable Go daemon that periodically touches external services to prevent idle shutdowns, pauses, or cold starts.
|
|
|
|
The current adapters perform cheap datastore writes for Redis Cloud, Valkey, Aiven, Neon, Supabase, MongoDB Atlas, Couchbase Capella, and similar hosted services.
|
|
|
|
Successor to the `*-keepalive` family: one binary, one image, six datastore adapters.
|
|
|
|
## Supported adapters
|
|
|
|
| `DB_TYPE` | Driver | Env vars |
|
|
| ------------ | ----------------------------------- | -------- |
|
|
| `redis` | `github.com/redis/go-redis/v9` | `REDIS_URL` |
|
|
| `valkey` | `github.com/valkey-io/valkey-go` | `VALKEY_URL` |
|
|
| `postgresql` | `github.com/lib/pq` | `SERVICE_URI` |
|
|
| `mysql` | `github.com/go-sql-driver/mysql` | `DATA_SOURCE_NAME` |
|
|
| `mongodb` | `go.mongodb.org/mongo-driver/v2` | `MONGODB_URI`, `MONGODB_DATABASE`, `MONGODB_COLLECTION` |
|
|
| `couchbase` | `github.com/couchbase/gocb/v2` | `COUCHBASE_CONNECTION_STRING`, `COUCHBASE_USERNAME`, `COUCHBASE_PASSWORD`, `COUCHBASE_BUCKET_NAME`, `COUCHBASE_SCOPE_NAME`, `COUCHBASE_COLLECTION_NAME` |
|
|
|
|
Optional: `INTERVAL` (e.g. `30s`, `5m`; default `1m`), `COUNTER_KEY` (default `counter`).
|
|
|
|
## Quick start (Docker)
|
|
|
|
```bash
|
|
docker run -d --name keepalive --restart unless-stopped \
|
|
-e DB_TYPE=redis \
|
|
-e REDIS_URL='redis://default@host:6379' \
|
|
ghcr.io/tiennm99/keepalive:latest
|
|
```
|
|
|
|
## Quick start (local)
|
|
|
|
```bash
|
|
git clone https://github.com/tiennm99/keepalive
|
|
cd keepalive
|
|
cp .env.example .env # then edit DB_TYPE + the driver's env vars
|
|
go run .
|
|
```
|
|
|
|
## How it works
|
|
|
|
On every tick the chosen adapter performs the cheapest write that proves the cluster is alive:
|
|
|
|
- **Redis/Valkey** — `INCR counter`
|
|
- **PostgreSQL** — `UPDATE keepalive SET value = value + 1 WHERE key = 'counter' RETURNING value`
|
|
- **MySQL** — `UPDATE` + `SELECT` inside a transaction
|
|
- **MongoDB** — `FindOneAndUpdate({_id: "counter"}, {$inc: {count: 1}}, upsert)`
|
|
- **Couchbase** — `GET counter` → `++` → `UPSERT counter`
|
|
|
|
The PostgreSQL and MySQL adapters expect a table:
|
|
|
|
```sql
|
|
CREATE TABLE keepalive (key TEXT PRIMARY KEY, value BIGINT NOT NULL DEFAULT 0);
|
|
INSERT INTO keepalive (key, value) VALUES ('counter', 0);
|
|
```
|
|
|
|
(MySQL uses backticked identifiers — see `adapter/mysql.go`.)
|
|
|
|
## Adding a new adapter
|
|
|
|
1. Create `adapter/<name>.go`.
|
|
2. Implement the `Adapter` interface in `adapter/adapter.go` (`Connect`, `Increment`, `Close`).
|
|
3. Register the factory in `init()`:
|
|
```go
|
|
func init() { Registry["<name>"] = func() (Adapter, error) { return &myAdapter{}, nil } }
|
|
```
|
|
4. Add an `import _ "your driver"` if needed, and the env vars to `.env.example` and the table above.
|
|
|
|
## Migrated from
|
|
|
|
This repo replaces six single-datastore repos. All are archived with a pointer here:
|
|
|
|
- [redis-keepalive](https://github.com/tiennm99/redis-keepalive)
|
|
- [valkey-keepalive](https://github.com/tiennm99/valkey-keepalive)
|
|
- [postgresql-keepalive](https://github.com/tiennm99/postgresql-keepalive)
|
|
- [mysql-keepalive](https://github.com/tiennm99/mysql-keepalive)
|
|
- [mongodb-keepalive](https://github.com/tiennm99/mongodb-keepalive)
|
|
- [couchbase-keepalive](https://github.com/tiennm99/couchbase-keepalive)
|
|
|
|
## License
|
|
|
|
Apache-2.0 — see [LICENSE](LICENSE).
|