Kaal

Kaal is in early development until v1.0.0. Expect breaking changes, and please reach out if you’d like to help or have feedback!

Kaal is a distributed cron scheduler for Ruby — a core engine plus datastore and framework integration gems that coordinates recurring jobs across processes or nodes without changing how your app enqueues work. For Redis, Postgres, and MySQL-backed deployments, it guarantees at-most-once dispatch per (key, fire_time) under the documented crash-and-restart model.

Install the right package

• kaal Plain Ruby with memory or redis.
• kaal-sequel Plain Ruby with Sequel-backed SQL persistence.
• kaal-activerecord Plain Ruby with Active Record-backed SQL persistence.
• kaal-rails Rails with generators, rake tasks, and Active Record-backed persistence.
• kaal-hanami Hanami integration across memory, Redis, and Sequel-backed SQL.
• kaal-roda Roda integration across memory, Redis, and Sequel-backed SQL.
• kaal-sinatra Sinatra integration across memory, Redis, and Sequel-backed SQL.

Quick start for plain Ruby with memory:

gem "kaal"

bundle install
bundle exec kaal init --backend=memory
bundle exec kaal start

kaal init currently supports memory and redis only.

Common commands

bundle exec kaal status
bundle exec kaal tick
bundle exec kaal explain "*/15 * * * *"
bundle exec kaal next "0 9 * * 1" --count 3

Production model

Run the scheduler in a dedicated process when possible.

Procfile:

web: bundle exec puma -C config/puma.rb
scheduler: bundle exec kaal start

systemd:

[Unit]
Description=Kaal scheduler
After=network.target

[Service]
ExecStart=/usr/bin/bash -lc 'bundle exec kaal start'
ExecStartPre=/usr/bin/bash -lc 'bundle exec kaal status'

[Install]
WantedBy=multi-user.target

Kubernetes:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app-scheduler
  labels:
    app: my-app-scheduler
spec:
  replicas: 1
  selector:
    matchLabels:
      app: my-app-scheduler
  template:
    metadata:
      labels:
        app: my-app-scheduler
    spec:
      containers:
        - name: scheduler
          image: my-app:latest
          command: ["bundle", "exec", "kaal", "start"]

Links

• Overview & Motivation
• Installation & Setup
• Configuration
• Usage
• At-Most-Once Dispatch Guarantee
• Idempotency Guidance
• FAQ / Troubleshooting
• Become a contributor

Monorepo

Name	Gem	RubyDocs
core/kaal/
core/kaal-sequel/
core/kaal-activerecord/
gems/kaal-hanami/
gems/kaal-rails/
gems/kaal-roda/
gems/kaal-sinatra/