Node.js Cron: Scheduled Cleanup & Renewal Deadlines

Node.js applications often need to run periodic tasks like cleaning up old database records or checking renewal deadlines. The standard way to schedule these tasks is with a cron-like library such as node-cron or node-schedule, which lets you define a time pattern and a function to execute. You can also trigger the same logic over HTTP by exposing a protected endpoint and calling it from an external cron service (like a CI/CD pipeline or a cloud scheduler). This article explains both approaches, how to choose between them, and how to handle the common pitfalls.

Background: What Cron Means in Node.js

Cron is a time-based job scheduler originally from Unix. A cron expression has five fields: minute, hour, day of month, month, and day of week. For example, 0 2 * * * means “run at 2:00 AM every day.” Node.js doesn’t have a built-in cron, but libraries like node-cron (the most popular) and node-schedule implement the same syntax. They keep a timer in the process and fire the callback when the pattern matches.

For cleanup tasks, you typically write a function that deletes records older than a certain date or marks them as expired. For renewal deadlines, you might send reminder emails or update status fields when a subscription or license is about to expire. Both are perfect cron jobs because they are periodic, idempotent (safe to run more than once), and usually run outside user requests.

How to Schedule a Cleanup Job in Node.js

Here is a minimal example using node-cron:

const cron = require('node-cron');
const { deleteOldRecords } = require('./cleanup');

// Run every day at 3:30 AM
cron.schedule('30 3 * * *', async () => {
  console.log('Running cleanup...');
  await deleteOldRecords();
});

The deleteOldRecords function might run a query like DELETE FROM sessions WHERE last_used < NOW() - INTERVAL '30 days' (PostgreSQL) or db.collection.deleteMany({ createdAt: { $lt: cutoffDate } }) (MongoDB). The key is to compute the cutoff date inside the job so it always reflects the current time.

For renewal deadlines, you might query for records where renewal_date is between now and now + 7 days, then send a reminder. That is also a cron job, but the query is a SELECT rather than a DELETE.

HTTP Cron: Exposing an Endpoint for External Schedulers

Sometimes you don’t want the Node.js process to keep its own timer, especially if you run multiple instances behind a load balancer. If each instance runs the same cron, you’ll get duplicate executions. A common solution is to expose a protected HTTP endpoint (e.g., POST /api/cron/cleanup) that runs the job, and then call that endpoint from an external scheduler like AWS CloudWatch Events, Google Cloud Scheduler, or even a simple cron on a separate server.

Example using Express:

app.post('/api/cron/cleanup', async (req, res) => {
  // Verify a secret token to prevent unauthorized calls
  if (req.headers['x-cron-secret'] !== process.env.CRON_SECRET) {
    return res.status(401).send('Unauthorized');
  }
  await deleteOldRecords();
  res.status(200).send('Cleanup done');
});

Then your external scheduler hits that URL with the secret header. This pattern is often called “HTTP cron” or “webhook cron.” It centralizes scheduling and avoids duplicate runs.

Choosing Between In-Process Cron and HTTP Cron

There is no single right answer; it depends on your deployment and reliability needs.

• In-process cron (node-cron) is simpler and works well for a single instance or when duplicates are acceptable (e.g., the job is idempotent). It requires no extra infrastructure.
• HTTP cron is better for multi-instance deployments, because only the external scheduler triggers the job once. It also gives you visibility (you can log the HTTP call) and lets you use cloud-native schedulers with retry policies.
• Hybrid: you can keep an in-process cron but add a distributed lock (e.g., using Redis) so only one instance runs it. That is more complex but gives you the best of both.

For a small project on a single VPS, in-process cron is usually fine. For a production service with auto-scaling, HTTP cron is safer.

Common Problems and How to Avoid Them

Here are the typical pitfalls developers hit when scheduling cleanup or renewal jobs:

• Duplicate runs – as mentioned, multiple instances each run the same cron. Fix: use HTTP cron or a distributed lock.
• Timezones – cron expressions are evaluated in the server’s local time by default. If you want 2 AM UTC, set the timezone explicitly in the cron library (e.g., cron.schedule('0 2 * * *', fn, { timezone: 'UTC' })).
• Missed executions – if the process is down at the scheduled time, the job doesn’t run. In-process cron does not catch up. External schedulers often have a “catch-up” or “run now” option.
• Long-running jobs – if your cleanup takes longer than the interval, you’ll overlap. Add a flag or use a mutex to prevent concurrent runs.
• Error handling – wrap the job in try/catch and log errors. Unhandled promise rejections can crash the process.
• Database load – deleting millions of rows in one query can lock tables. Batch the deletion (e.g., delete 1000 rows at a time with a delay).

Security and Safety of HTTP Cron Endpoints

Exposing an endpoint that deletes data is dangerous if not protected. Always require a secret token, preferably in a header, and use HTTPS. Do not put the secret in the URL (it gets logged in access logs). Also, consider IP allowlisting if your scheduler has a fixed IP. For extra safety, make the endpoint idempotent and log every call with a timestamp and IP.

Another safety measure is to run the job in a transaction or with a dry-run mode first. For example, you can add a query parameter ?dryRun=true that logs what would be deleted but does not delete. Test it in staging before enabling in production.

Alternatives to Cron for Scheduled Tasks

If you need more advanced features, consider these alternatives:

• Message queues with delayed delivery – e.g., RabbitMQ or SQS with a delay, but these are more for one-off tasks than recurring schedules.
• Job queues like Bull (Redis-based) – they support repeatable jobs and are more robust than plain cron because they persist state and can retry failures.
• Cloud-native schedulers – AWS EventBridge, Google Cloud Scheduler, Azure Scheduler – these are the external schedulers for HTTP cron, but they can also invoke Lambda functions directly.
• System cron – you can write a shell script that runs node script.js and schedule it with the system cron. That works but is less portable.

For most cases, a simple cron library or HTTP cron is sufficient. Only move to a job queue when you need retries, persistence, or complex workflows.

Frequently Asked Questions

Can I use cron in a serverless function?

Yes, but you would not use node-cron inside the function because the function is ephemeral. Instead, use the cloud provider’s scheduler to invoke the function on a schedule (e.g., AWS EventBridge rule triggering a Lambda).

How do I test a cron job without waiting for the scheduled time?

Most libraries let you trigger the callback manually. With node-cron, you can call task.now() if you store the scheduled task. For HTTP cron, just call the endpoint manually with the correct secret.

What happens if my server is off during the scheduled time?

In-process cron will not run the missed job. External schedulers may have a “catch-up” feature (e.g., AWS EventBridge has a “retry” policy, but not a catch-up). You can also run a startup check to catch up on missed jobs.

Is it safe to delete old records automatically?

Yes, if you have a backup and the deletion is idempotent. Always test with a dry run first. Also, consider soft-deleting (setting a flag) instead of hard-deleting for compliance or audit reasons.

How do I handle timezone differences for renewal deadlines?

Store all dates in UTC in your database. When computing the cutoff for “expiring in 7 days,” use UTC. When sending reminders, convert to the user’s timezone for display, but the cron schedule itself should be in UTC to avoid DST issues.

Can I run multiple cron jobs in one Node.js process?

Yes, you can call cron.schedule as many times as you want. Each schedule creates its own timer. Be mindful of the event loop – if jobs are heavy, they might block other requests. Use async functions and consider worker threads for CPU-intensive tasks.

Related

• How to Hide Your Caller ID: Step-by-Step Guide
• Disney Plus Chromecast: How to Cast & Fix Issues
• AI Recruitment Tools: Match to Hiring Task