For my pet project I’ve needed to write a simple application, which checks if there is any data in specific table in my database and if there is, it sends me an email. After a few minutes of research I’ve decided to use Heroku service for it. This was my first meeting with Heroku and I was curious how easy it would be to write an app.
Heroku supports Ruby, Node.js, Python and Java. From this list I feel quite comfortable with Node.js, so I’ve chosen it.
In this blog post I guide you how to create a simple Node.js app, that can be used as a Heroku Scheduler task.
Before starting I suggest reading those articles from Heroku documentation:
Let’s create a project directory:
with an empty git repository in it:
Now we need to tell Heroku that we created Node.js app – this should be done by creating
package.json file. This file describes our application and defines all dependencies for it. To do this let’s invoke command:
and answer to the questions. As the result the
package.json file is generated.
This is good time to do our first commit:
Now we are ready to create Heroku application. First we need to login to the service:
then we can create the app:
If you want to use European server then you should add
--region eu parameter to the
If all is set up, let’s do a deploy by pushing all our code from the git repository to Heroku server:
That’s it! Our first, still empty app is ready to go – except there is no code ;)
Our application will use three add-ons:
- Heroku Postgres – for storing data and retrieving them
- Heroku Scheduler – for running job every hour
- SendGrid – for sending emails
we need to add them to Heroku. This can be done by invoking:
1 2 3
One important note: to install add-ons you need to verify your Heroku account by providing information about valid credit card.
npm packages for them:
--save argument adds those packages as a dependency to the
package.json file – this helps installing/updating them in future.
You can find documentation for the scheduler here, but it lacks details about Node.js and it can take some time to figure out everything on your own.
First thing, a task should be placed in the
bin folder in the root project directory:
Second, the task should be written in a file without any extension (in our case it’s
The last important thing is that the first line in the script file must contain shebang that defines which interpreter program is used to run the script (here: node.js):
Finally we are ready to write real code!
Let’s open the
checkItems file with our favorite editor. The file should contain only the shebang line.
1 2 3 4 5 6 7
process.env.SENDGRID_PASSWORD contains your SendGrid account information. Those environment variables are set by Heroku itself.
To connect to Postgres database we need to invoke code:
An important notice, to be able to use
DATABASE_URL variable you need to promote your database. First we need to establish the exact URL of our database, to do it we need to execute command in the root folder:
It lists all available databases for you program, with values of URLs. The output should be similar to this:
1 2 3 4 5 6 7 8 9 10 11
now we can execute command:
DATABASE_URL variable to the value of
I won’t describe how to create tables and import data into them, you can read about this here.
Let’s return to
pg module. There is one important thing to remember. When you finish your work with database, you have to invoke
done() callback – otherwise the client will never be returned to the connection pool and you will leak clients.
Before writing a query, lets write a function for error handling. We can use for that the code from
1 2 3 4 5 6 7 8
To query a table (I assume that there is
todos table) in a database we can write such code:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19
The idea here is to send an notification email only if there are any rows in
todos table. Please pay attention that we invoke
done() method when the query is done. I also invoke
pg.end(); to immediately close any connections to PostgreSQL server – I do this to save dynos and close the app as fast as possible.
The last part is to write code that will send email with SendGrid module:
1 2 3 4 5 6 7 8 9 10
so the whole code looks like this:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36
Please notice, that I’ve moved
done(); pg.end(); code to the callback of
To run and test the code we should deploy it on the server and run:
1 2 3 4
If everything is OK, the code should run without any errors.
This is very simple code, that illustrate only the way of doing such task. For a production ready it should be extended and more tested.
Now when we have a code of our scheduler task, we can set scheduler on Heroku site.
Setting Heroku scheduler
To configure scheduler we need to go to its dashboard page by invoking command:
On the page click
Add Job... link, in the text box write the name of the file (without any extension) that defines the task and is located in the
bin folder (in our case it is:
checkItems). From the drop-down list select the frequency and adjust next run time. Commit you changes by clicking the
This is it, you defined your scheduler task. From now on it will run every defined period.
I hope this article will help you create your own, custom task for Heroku scheduler. Enjoy!
You can clone this code from my GitHub repository