Running one-off tasks and dynos

In more traditional hosting environments, developers will often log in to servers to perform basic administrative tasks or debug an issue. With Heroku, we can do this by launching one-off dynos. These are dynos that contain our application code but do not serve web requests.

Note

For a Ruby on Rails application, one-off dynos are often used to run database migrations or launch a Rails console.

How to do it...

In this recipe, we will learn how to execute commands on our Heroku applications with the heroku run command. Let's launch a terminal now to get started with the following steps:

1. To have Heroku start a one-off dyno and execute any single command, we will use heroku run. Here, we can try it out by running a simple command to print some text to the screen:

   $ heroku run echo "hello heroku"
    Running `echo "hello heroku"` attached to terminal... up, run.7702
    "hello heroku"
   

   Note

   One-off dynos are automatically shut down after the command has finished running.

2. We can see that Heroku is running this command on a dyno with our application's code. Let's run ls to see a listing of the files on the dyno. They should look familiar:

   $ heroku run ls
    Running `ls` attached to terminal... up, run.5518
    app bin config config.ru db Gemfile Gemfile.lock lib log Procfile public Rakefile README README.md tmp
   

3. If we want to run multiple commands, we can start up a bash session. Type exit to close the session:

   $ heroku run bash
   Running `bash` attached to terminal... up, run.2331
   ~ $ ls
   app bin config config.ru db Gemfile Gemfile.lock lib log Procfile public Rakefile README README.md tmp
   ~ $ echo "hello"
   hello
   ~ $ exit
   exit
   

4. We can run tasks in the background using the detached mode. The output of the command goes to our logs rather than the screen:

   $ heroku run:detached echo "hello heroku"
   Running `echo hello heroku` detached... up, run.4534
   Use `heroku logs -p run.4534` to view the output.
   

5. If we need more power, we can adjust the size of the one-off dynos. This command will launch a bash session in a 2X dyno:

   $ heroku run --size=2X bash
   

6. If we are running one-off dynos in the detached mode, we can view their status and stop them in the same way we would stop any other dyno:

   $ heroku ps
   === run: one-off processes
   run.5927 (1X): starting 2014/03/29 16:18:59 (~ 6s ago)
   $ heroku ps:stop run.5927
   

How it works…

When we issue the heroku run command, Heroku spins up a new dyno with our latest slug and runs the command. Heroku does not start our application; the only command that runs is the command that we explicitly pass to it.

One-off dynos act a little differently than standard dynos. If we create one dyno in the detached mode, it will run until we stop it manually, or it will shut down automatically after 24 hours. It will not restart like a normal dyno will.

If we run bash from a one-off dyno, it will run until we close the connection or we reach an hour of inactivity.