Use the command line

Procrastinate installs a command-line tool, which allows to do some operations:

• Prepare your database for procrastinate (apply the database schema)

• Launch a worker

• Defer a task

• …

The command-line tool can be launched using:

$ procrastinate

or:

$ python -m procrastinate

Please read the included help to get familiar with its commands and parameters:

$ procrastinate --help
usage: procrastinate [-h] [-a APP] [-v] [--log-format LOG_FORMAT]
                     [--log-format-style {%,{,$}] [-V]
                     {worker,defer,schema,healthchecks,shell} ...

Interact with a Procrastinate app. See subcommands for details.

positional arguments:
  {worker,defer,schema,healthchecks,shell}
    worker              Launch a worker, listening on the given queues (or all
                        queues). Values default to App.worker_defaults and
                        then App.run_worker() defaults values.
    defer               Create a job from the given task, to be executed by a
                        worker. TASK should be the name or dotted path to a
                        task. JSON_ARGS should be a json object (a.k.a
                        dictionary) with the job parameters
    schema              Apply SQL schema to the empty database. This won't
                        work if the schema has already been applied.
    healthchecks        Check the state of procrastinate
    shell               Administration shell for procrastinate

options:
  -h, --help            show this help message and exit
  -a APP, --app APP     Dotted path to the Procrastinate app (env:
                        PROCRASTINATE_APP) (default: )
  -v, --verbose         Use multiple times to increase verbosity (env:
                        PROCRASTINATE_VERBOSE: set to desired verbosity level)
                        (default: 0)
  -V, --version         Print the version and exit

Logging:
  --log-format LOG_FORMAT
                        Defines the format used for logging (see https://docs.
                        python.org/3/library/logging.html#logrecord-
                        attributes) (env: PROCRASTINATE_LOG_FORMAT) (default:
                        %(levelname)s:%(name)s:%(message)s)
  --log-format-style {%,{,$}
                        Defines the style for the log format string (see
                        https://docs.python.org/3/howto/logging-
                        cookbook.html#use-of-alternative-formatting-styles)
                        (env: PROCRASTINATE_LOG_FORMAT_STYLE) (default: %)

Define your app

When using the Procrastinate CLI, you’ll almost always need to specify your app. This can be done in two ways:

• Using the --app parameter:

  $ procrastinate --app=dotted.path.to.app worker
  

• Using the PROCRASTINATE_APP environment variable:

  $ export PROCRASTINATE_APP=dotted.path.to.app
  $ procrastinate worker
  

As a general rule, all parameters have an environment variable equivalent, named PROCRASTINATE_SOMETHING or PROCRASTINATE_SUBCOMMAND_SOMETHING where SOMETHING is the uppercased long name of the option, with - replaced with _ (e.g. PROCRASTINATE_DEFER_UNKNOWN). procrastinate --help will show you the environment variable equivalent of each parameter.

In both case, the app you specify must have an asynchronous connector.

Logging

Three different options allow you to control how the command-line tool should log events:

• Verbosity controls the log level (you’ll see message of this level and above):

  Flags	Environment equivalent	Log level
  	PROCRASTINATE_VERBOSITY=0	warning
  -v	PROCRASTINATE_VERBOSITY=1	info
  -vv	PROCRASTINATE_VERBOSITY=2	debug

• Log format: --log-format= / PROCRASTINATE_LOG_FORMAT= lets you control how the log line will be formatted. It uses %-style placeholders by default.

• Log format style: --log-format-style= / PROCRASTINATE_LOG_FORMAT_STYLE= lets you choose different styles for the log-format, such as { or $.

For more information on log formats, refer to the Python documentation