This is the first of a multi-part series to leverage the Couchbase Eventing Service to run multiple scheduled tasks at specific recurring intervals in a cron like fashion completely inside the database without requiring additional infrastructure via a single general-purpose Eventing Function. In this installment, we will focus on running fixed user routines, JavaScript functions defined inside an Eventing Function. Later in subsequent articles we will extend the cron like Eventing Function to schedule and execute database driven dynamic N1QL statements and then finally in we will explore scheduling database driven dynamic JavaScript functions.
Background
The Couchbase Eventing Service provides a framework for writing your own routines, simple JavaScript functions, to process document changes. This service provides all the needed infrastructure to create scalable and robust cloud-based functions allowing you to focus on developing pure business logic to interact in near real-time to changes in your data. Your functions are able to access the Couchbase data service (KV), the Couchbase query service (N1QL), and REST endpoints external to the Couchbase system. 
The JSON data model in Couchbase came from JavaScript, thus it is only natural that the Eventing Service exposes the ability to write JavaScript code to analyze and manipulate JSON documents on any type of change events including Inserts, Updates, Merges, and Deletes (together referred to as mutations). Eventing Functions typically allow you to deploy and execute custom code fragments to that react to thousands and even millions of mutations per seconds in your documents. Several typical use cases are documented for developing high velocity at-scale Eventing Functions that respond to mutations of Couchbase documents. 
This article will focus instead on a very low velocity use case of the Eventing Service building a reliable “in database” distributed crontab, allowing you to execute JavaScript functions that interact with Couchbase services on a regular periodic schedule.
Scheduling Business Logic to Run at a Specified Date or Time
Cron, named after “Chronos,” the Greek word for time is one of the most useful utilities in a Linux system. In Linux the cron utility is driven by a crontab (cron table) file, a configuration file that specifies shell commands to run periodically on a given schedule. One drawback in running cron is that it is not designed to be a distributed service; it runs on single box, as such it presents a single point of failure. If the system is offline for several hours all scheduled tasks are missed.
Yes, there are some distributed cron implementations such as Google’s Cloud Service, AWS’ Scheduled Tasks, and Azure Functions / Time Triggers. But each cloud vendors offerings have their own idioms are not directly portable. In addition, the methodology of configuration and control needs to be secured, for example if you control a distributed cron system via a REST API over HTTP/S you need to account for this in your security plan.
Using the Couchbase Itself to Run Periodic Commands
With a minor amount of code and planning you can leverage Couchbase’s Eventing service to provide flexible cron like functionality for your scheduled database operations or maintenance. Building the scheduler into the database allows you to achieve the following benefits:
- Portability across Cloud providers, if you rehost your Couchbase cluster your scheduler is not impacted.
- Supportability, if you utilize Couchbase you have single vendor to provided support and other services.
- Distributed, no single point of failure and all Couchbase services support distributed replicas.
- Guaranteed execution, your task gets executed even after recovery from a node failure.
Couchbase Scheduling, Timers the Secret Sauce
Timers are Couchbase Eventing Service constructs by which developers can specify a routine (business logic) to be triggered at a future time. We will use this functionality to implement a pure Couchbase configurable crontab system that allows you the ability to trigger repetitive tasks as part of your workflows whether you need to execute a simple N1QL query or build a complex rules engine. In all of the subsequent designs we will limit our cron implementations to a resolution of 15 seconds or greater.
We have this limitation because although timers scale to the millions and are guaranteed to fire and execute, they are not wall-clock accurate currently have a bounded steady state delay of less than 14 seconds [1]. Of course, if you need a tighter schedule, i.e. less than 15 seconds, then you should merely process the mutation itself in Eventing logic without the use of a timer construct to schedule a call back in the future. As of this writing the current Couchbase release is version 6.5.1 which two limitations that we must work around when making a robust cron system.
- In the 5.5.x, 6.0.x and 6.5.x releases a function that is invoked by a timer callback cannot reliably create a fresh timer (a user space work around can be done via a second cooperative Function).
- In the 6.5.x releases creating timers in the future (as in one hour+) in an otherwise idle system can result in a growing number of metadata bucket operations which can eventually block mutations for a given Eventing function (in 6.5.X a user space work around can be accomplished via a second cooperative Function). The severity is governed by:
- The number of vBuckets holding an active timer. Therefore if there are only a few timers in the future the issue may not be noticeable or materialize. This is the case with just a few cron schedules but for completeness in case you add date functionality I put in a fix for this issue for the code supplied in this article.
- Whether an Eventing timer has fired recently on a vBucket (which clears the issue for the given vBucket on a per function basis). Therefore systems with lots of near term timer activity will not experience this issue even if timers are scheduled far into the future.
Fortunately in version 6.6.0 both of the above issues or restrictions are lifted and a scheduler can be made in a single simple unified Eventing Function. 
Prerequisites
In this article we will be using the latest GA version, i.e. Couchbase version 6.5.1 (you may need to make some changes to the Eventing Functions described for earlier Couchbase versions). The example in this article will run against the travel-sample data set which is delivered with the Couchbase server.
PRO TIP: For Advanced users only, if you are familiar with Couchbase Eventing and also our CLI / REST tools you can skip the bulk of this blog and download a ZIP file to quickly setup and run the scheduler system presented below. Right-click on the following link and choose Save Link As to download the file cron_impl_2func_CLI.zip, move it to an Eventing node, extract the ZIP file, and refer to the extracted README.txt file.
However, if you are not familiar with Couchbase or the Eventing service please walk through GET STARTED and one Eventing example specifically refer to the following:
-
Setup a working Couchbase 6.5.1 server as per the directions in Start Here!
-
Make sure you can run a N1QL query against the travel-sample data set as per the directions in Run Your First N1QL Query.
-
Understand how to deploy a basic Eventing function as per the directions in the Document Archival example that also uses the travel-sample data set.
-
Make sure you have the travel-sample bucket in the Buckets view of the UI.
-
Make sure you a bucket called metadata in the Buckets view of the UI it should have the minimum size of 200MB.
-
In the Buckets view of the UI create a bucket called crondata with the minimum size of 200MB. For detailed steps on how to create buckets, see Create a Bucket.
-
Set allow_interbucket_recursion to true in order to allow two (2) Eventing functions to alter the same KV document [2].
-
Java
-
1
curl -X POST -u "$CB_USERNAME:$CB_PASSWORD" 'http://localhost:8091/_p/event/api/v1/config' -d '{ "allow_interbucket_recursion":true }'
#database #tutorial #big data #couchbase #reactive programming #eventing #cron #scheduled tasks
