The zendhqctl jobqueue module

You use the zendhqctl jobqueue module to manage ZendHQ JobQueue queues and jobs.

Prerequisites

The ZendHQ daemon must be running.
The zendhq_sock extension must be loaded.
The local socket (the zendhqd.socket.listen directive in the ZendHQ daemon's configuration file) must be accessible to the zendhqctl command.

Terminology

Queue - A named queue that holds jobs. Queues are identified by their names or by their numeric IDs. Commands that accept queue names can also accept queue IDs. In case of ambiguity, prefix the queue identifier with name: or id: to specify the type of the identifier.
Job - A task that is executed by the JobQueue. Jobs are identified by their numeric IDs. Historical job runs are identified by their run IDs.
Cron Job - A job that is scheduled to run at specific times or intervals. For more information, see Specify dates and times using crontab syntax.

Commands

Command	Description
`queue`	Manages JobQueue queues
`job`	Manages JobQueue jobs

The `queue` command

Use the queue command to query, add, remove, suspend, activate, or modify JobQueue queues.

Use zendhqctl jobqueue queue --help to show help for the queue command.

The `queue list` subcommand

Copy

zendhqctl jobqueue queue list

Lists all the JobQueue queues in the following format:

<id>  <D(default)?> <name> <status> <jobs>

The `queue print` subcommand

Copy

zendhqctl jobqueue queue print [QUEUE]

Prints the details of the default queue or the queue with the name or ID QUEUE.

For example, to print the details of the queue 'Cron jobs':

zendhqctl jobqueue queue print 'Cron jobs'

The `queue suspend` subcommand

Copy

zendhqctl jobqueue queue suspend [QUEUE]

Suspends the default queue or the queue with the name or ID QUEUE.

For example, to suspend the queue Cron jobs:

zendhqctl jobqueue queue suspend 'Cron jobs'

The `queue activate` subcommand

Copy

zendhqctl jobqueue queue activate [QUEUE]

Activate the default queue or the queue with the name or ID QUEUE.

For example, to activate the queue 'Cron jobs':

zendhqctl jobqueue queue activate 'Cron jobs'

The `queue add` subcommand

Copy

zendhqctl jobqueue queue add NAME
           [-y,--yes]
           [-s,--suspended]
           [--job-type http|cli]
           [--job-priority urgent|high|normal|low]
           [--job-timeout <seconds>]
           [--job-max-retries <count>]
           [--job-retry-delay <seconds>]
           [--job-http-method get|post|put]
           [--job-http-content-type json|url-encoded|zend-server]
           [--job[-no]-validate-ssl]
           [--job[-no]-persist]
           [--job-persist-output yes|no|error]

Adds a new JobQueue queue with the name NAME and the following optional parameters.

```
--job-http-content-type json|url-encoded|zend-server
```
Default HTTP content type for HTTP PUT and POST jobs added to this queue:
- json - application/json
- url-encoded - application/x-www-form-urlencoded
- zend-server - compatible with Zend Server.
  
  The zend-server content type encodes the request body in JSON, but sets the 'Content-Type' header to 'application/x-www-form-urlencoded'.
```
--job-http-method get|post|put
```
Defines the default HTTP method for HTTP jobs added to this queue.
```
--job-max-retries <count>
```
Defines the default maximum retry count for jobs added to this queue. The value must be a positive integer value including zero.
```
--job[-no]-persist
```
Defines the default job persistence for jobs added to this queue.

Persisted jobs are never deleted during the database cleanup. Use this option with care.
```
--job-persist-output yes|no|error
```
Defines the default job output persistence mode for jobs added to this queue.
- yes - persist the job output
- no - do not persist the job output
- error - persist the job output only if the job fails
```
--job-priority urgent|high|normal|low
```
Defines the default priority for jobs added to this queue. The job priority is used to determine the order in which jobs are processed if all the other conditions are equal.
```
--job-retry-delay <seconds>
```
Defines the default retry delay in seconds for jobs added to this queue. The value must be a positive integer value including zero and less than 2147484.
```
--job-timeout <seconds>
```
Defines the default timeout in seconds for jobs added to this queue. The value must be a positive integer value greater than zero and less than 2147484.
```
--job-type http|cli
```
Defines the default type for jobs added to this queue, either HTTP or command line interface.
```
--job[-no]-validate-ssl
```
Defines the default SSL validation mode for HTTP jobs added to this queue:
- --job-validate-ssl - enable SSL validation and do not allow self-signed certificates
- --job-no-validate-ssl - allow self-signed certificates (other SSL errors are still reported)
```
-p,--priority urgent|high|normal|low
```
Defines the priority of the queue. Queue priority value affects operating system scheduling policies and the accuracy of the job execution timing. Higher priority queues are more likely executing jobs on time, but they also consume more system resources and may cause queue starvation if abused.
```
-s,--suspended
```
Creates the queue in the suspended state.
```
-y,--yes
```
Answers yes to all the prompts.

For example, to add a new queue with the name 'Cron jobs' and low priority:

zendhqctl jobqueue queue add 'Cron jobs' --priority low

The `queue update` subcommand

Copy

zendhqctl jobqueue queue update QUEUE
           [-n,--name <name>]
           [-y,--yes]
           [--job-type http|cli]
           [--job-priority urgent|high|normal|low]
           [--job-timeout <seconds>]
           [--job-max-retries <count>]
           [--job-retry-delay <seconds>]
           [--job-http-method get|post|put]
           [--job-http-content-type json|url-encoded|zend-server]
           [--job[-no]-validate-ssl]
           [--job[-no]-persist]
           [--job-persist-output yes|no|error]

Updates the queue with the name or ID QUEUE with the specified parameters.

```
-n,--name <name>
```
Defines the new name of the queue.

See the queue add subcommand for the description of the other parameters.

It is not possible to rename the default queue.

For example, to update the queue 'Cron jobs' to have the name Scheduled jobs:

zendhqctl jobqueue queue update 'Cron jobs' --name 'Scheduled jobs'

The `queue remove` subcommand

zendhqctl jobqueue queue remove QUEUE
           [-S,--suspend]
           [-y,--yes]

Removes the queue with the name or ID QUEUE.

You must use the -S,--suspend flag to suspend the queue before removing it. The default queue cannot be removed.

-S,--suspend

Suspends the queue before removing it.
-y,--yes

Answers yes to all the prompts.

For example, to remove the queue 'Cron jobs':

zendhqctl jobqueue queue remove 'Cron jobs'

The `job` command

Use the job command to query, add, remove, or modify JobQueue jobs.

Use zendhqctl jobqueue job --help to show help for the job command.

The `job list` subcommand

zendhqctl jobqueue job list [QUEUE]
            [-a,--all-queues]
            [-u,--utc]

Lists all the jobs in the default queue or in the queue with the name or ID QUEUE in the following format:

<id> <name> <queue> <priority> <R(ecurring)?> <status> <scheduled time>

Jobs are displayed in the order of their planned execution time grouped by the queue they belong to.

-a,--all-queues
Lists all the jobs in all the queues. Cannot be used with the QUEUE parameter.

-u,--utc

Displays scheduled time values in the UTC timezone.

This command displays time values in the local timezone, unless the -u,--utc flag is used to display the time in the UTC timezone. The local timezone is determined by the TZ environment variable in UNIX shell.

For example, to list all the jobs in the queue 'Cron jobs':

zendhqctl jobqueue job list 'Cron jobs'

The `job print` subcommand

zendhqctl jobqueue job print ID[:RUN-ID] [-u,--utc]

Prints the details of the job with the given ID or the historical job run with the given job ID and run ID.

-u,--utc

Displays time values in the UTC timezone.

This command displays time values in the local timezone, unless the -u,--utc flag is used to display the time in the UTC timezone. The local timezone is determined by the TZ environment variable in UNIX shell.

For example, to print the details of the job with the ID 123 using the Central Standard Time (CST) timezone:

TZ="America/Chicago" zendhqctl jobqueue job print 123

To print the details of the historical job run with the ID 123 and run ID 456:

zendhqctl jobqueue job print 123:456

The `job add` subcommand

Copy

add [QUEUE] --cli PATH-TO-SCRIPT|--http URL
            [-y,--yes]
            [-u,--utc]
            [--name NAME]
            [-n,--now|-c,--cron CRON|-t,--time TIME]
            [--priority PRIORITY]
            [--timeout SECONDS]
            [--max-retries COUNT]
            [--retry-delay SECONDS]
            [--[no-]persist]
            [--persist-output yes|no|error]
            [--[no-]validate-ssl]
            [--[http-]method get|post|put]
            [--[http-]content-type json|url-encoded|zend-server]
            [--[http-]raw-body BODY]
            [--[http-]headers KEY=VALUE[,...]]
            [--[http-]query-args KEY=VALUE[,...]]
            [--[http-]body-vars KEY=VALUE[,...]]
            [--env KEY=VALUE[,...]]

Adds a new job to the default queue or to the queue with the name or ID QUEUE. The type of the job must be specified using the --cli or --http flag. The job is scheduled to run immediately unless the --cron or --time flag is used.

```
--cli PATH-TO-SCRIPT
```
Defines the path to the command-line script to be executed by the CLI job.
```
-c,--cron CRON
```
Defines the cron expression for scheduling recurring jobs.
```
--env KEY=VALUE[,...]
```
Defines the environment variables in the form of key-value pairs for CLI jobs.
```
--http URL
```
Defines the HTTP request URL for the HTTP job.
```
--[http-]body-vars KEY=VALUE[,...]
```
Defines the HTTP request body variables in the form of key-value pairs for HTTP POST and PUT jobs.

The HTTP request body is generated from these key-value pairs using the given content type.
```
--[http-]content-type json|url-encoded|zend-server
```
Defines the HTTP request content type for HTTP PUT and POST jobs.
- json - application/json
- url-encoded - application/x-www-form-urlencoded
- zend-server - compatible with Zend Server
  The zend-server content type encodes the request body in JSON, but sets the 'Content-Type' header to 'application/x-www-form-urlencoded'.
```
--[http-]headers KEY=VALUE[,...]
```
Defines the HTTP request headers in the form of key-value pairs for HTTP jobs.
```
--[http-]method get|post|put
```
Defines the HTTP request method for HTTP jobs.
- get - HTTP GET
- post - HTTP POST
- put - HTTP PUT
```
--[http-]query-args KEY=VALUE[,...]
```
Defines the HTTP request query arguments in the form of key-value pairs.
```
--[http-]raw-body BODY
```
Defines the HTTP request body for HTTP POST and PUT jobs.

The raw body is used as the HTTP request body without any modifications.
```
--max-retries COUNT
```
Defines the maximum number of retries for the job. The value MUST be a positive integer value including zero.
```
--name NAME
```
(Optional) Defines the name of the job.
```
-n,--now
```
Schedules the job to run immediately (default).
```
--[no-]persist
```
Sets the job persistence flag.

Persisted jobs are never deleted during the database cleanup. Use this option with care.
```
--persist-output yes|no|error
```
Persists the job output in the job history.
- yes - Persist the output.
- no - Do not persist the output.
- error - Persist the output only when the job fails.
```
--priority urgent|high|normal|low
```
Sets the job priority.

The job priority is used to determine the order in which the jobs are processed if all the other conditions are equal.
```
--retry-delay SECONDS
```
Sets the delay between job retries in seconds.

The value MUST be a positive integer value including zero and less than 2147484.
```
t,--time TIME
```
Schedules the job to run at the specified date and time.

The time value can be specified in the following formats:
- +[[HH:]mm:]ss format for relative time from now
- ISO 8601 extended format for absolute time yyyy-MM-dd HH:mm:ss[<TZ>]
The time zone specifier <TZ> is optional and MUST be in the format +HH:mm or Z for UTC.

Uses the local time zone by default, which can be overridden by setting the TZ environment variable.
```
--timeout SECONDS
```
Defines the job timeout in seconds.

The value must be a positive integer value greater than zero and less than 2147484.
```
-u,--utc
```
Displays time values in the UTC timezone.

The flag does not affect time values given in the command.
```
--[no-]validate-ssl
```
Sets the SSL validation flag for HTTP jobs.
- validate-ssl - validate SSL certificates and do not allow self-signed certificates
- no-validate-ssl - allow self-signed certificates (other SSL errors are still reported)
```
-y,--yes
```
Answers yes to the confirmation prompt.

For example, to add a new CLI job to the default queue that runs the script script.php with the environment variable ENV_VAR set to value after 5 minutes:

zendhqctl jobqueue job add \
            --cli script.php \
            --env ENV_VAR=value \
            --time '+05:00'

To add a new HTTP job to the queue 'Cron jobs' that sends a GET request to the URL http://example.com/api with the HTTP headers "authorization": "bearer 123" once a day at 3:00 UTC time:

zendhqctl jobqueue job add 'Cron jobs' \
            --http http://example.com/api \
            --http-method get \
            --http-headers authorization=bearer \
            --cron '0 0 3 * * *'

The `job update` subcommand

Copy

update ID   [--cli PATH-TO-SCRIPT|--http URL]
            [-y,--yes]
            [-u,--utc]
            [--name NAME]
            [-n,--now|-c,--cron CRON|-t,--time TIME]
            [--priority PRIORITY]
            [--timeout SECONDS]
            [--max-retries COUNT]
            [--retry-delay SECONDS]
            [--[no-]persist]
            [--persist-output yes|no|error]
            [--[no-]validate-ssl]
            [--[http-]method get|post|put]
            [--[http-]content-type json|url-encoded|zend-server]
            [--[http-]raw-body BODY]
            [--[http-]headers KEY=VALUE[,...]]
            [--[http-]query-args KEY=VALUE[,...]]
            [--[http-]body-vars KEY=VALUE[,...]]
            [--env KEY=VALUE[,...]]

Updates the job with the given ID with the specified parameters. See the job add subcommand for the description of the parameters.

For example, to update the job with the ID 123 to have a name "Test job":

zendhqctl jobqueue job update 123 --name 'Test job'

The `job remove` subcommand

```
remove ID [-y,--yes]
```
Removes the job with the given ID.
```
-y,--yes
```
Answers yes to the confirmation prompt.

For example, to remove the job with the ID 123:

zendhqctl jobqueue job remove 123

The `job history` subcommand

Copy

history [QUEUE]
            [-a,--all-queues]
            [-j,--job ID]
            [-u,--utc]
            [--completed]
            [--failed]
            [--deleted]
            [--unknown]
            [--limit COUNT]
            [--last-id ID]

Lists the job history for the default queue or for the queue with the name or ID QUEUE in the following format:

<job-id>:<run-id> <queue> <status> <time>

Job history records are displayed in the order of their completion time with the most recent job runs first.

```
-a,--all-queues
```
Lists the job history for all the queues.

Cannot be used with the QUEUE and --job options.
```
--completed
```
Lists only completed jobs.
```
--deleted
```
Lists only deleted jobs.
```
--failed
```
Lists only failed jobs.
```
-j,--job ID
```
Lists the job history for the job with the given ID.

Cannot be used with the QUEUE and --all-queues options.
```
--limit COUNT
```
Limits the number of displayed job history entries. The value must be a positive integer value greater than zero and less than 1000.
```
--last-id ID
```
Returns the last seen oldest (smallest) job history run ID value for pagination.
```
--unknown
```
Lists only jobs with unknown status.

The status is set to unknown when the job status cannot be determined, for example, when a job is started, but the ZendHQ daemon is shut down before the job is completed or has failed.
```
-u,--utc
```
Displays time values in the UTC timezone.

For example, to list all the failed jobs in the queue 'Cron jobs':

zendhqctl jobqueue job history 'Cron jobs' --failed

The zendhqctl jobqueue module

Prerequisites

Terminology

Commands

The queue command

The queue list subcommand

The queue print subcommand

The queue suspend subcommand

The queue activate subcommand

The queue add subcommand

The queue update subcommand

The queue remove subcommand

The job command

The job list subcommand

The job print subcommand

The job add subcommand

The job update subcommand

The job remove subcommand

The job history subcommand

The `queue` command

The `queue list` subcommand

The `queue print` subcommand

The `queue suspend` subcommand

The `queue activate` subcommand

The `queue add` subcommand

The `queue update` subcommand

The `queue remove` subcommand

The `job` command

The `job list` subcommand

The `job print` subcommand

The `job add` subcommand

The `job update` subcommand

The `job remove` subcommand

The `job history` subcommand