First cut of the pgAgent docs.

docs/en_US/pgagent.rst

@@ -0,0 +1,19 @@
+.. _pgagent:
+
+
+pgAgent
+======= 
+
+pgAgent is a job scheduling agent for Postgres databases, capable of running multi-step batch/shell and SQL tasks on complex schedules.
+
+pgAgent is distributed independently of pgAdmin.  You can download pgAgent from the `download area <http://www.pgadmin.org/download>`_ of the pgAdmin website.
+
+Contents:
+
+.. toctree::
+   :maxdepth: 2
+
+   using_pgagent
+   pgagent_install
+   pgagent_jobs
+  

docs/en_US/pgagent_install.rst

@@ -0,0 +1,72 @@
+.. _pgagent_install:
+
+
+***************************
+`Installing pgAgent`:index:
+***************************
+
+pgAgent runs as a daemon on Unix systems, and a service on Windows systems.  In most cases it will run on the database server itself - for this reason, pgAgent is not automatically configured when pgAdmin is installed. In some cases however, it may be preferable to run pgAgent on multiple systems, against the same database; individual jobs may be targeted at a particular host, or left for execution by any host. Locking prevents execution of the same instance of a job by multiple hosts.
+
+Database setup
+==============
+
+Before using pgAdmin to manage pgAgent, you must create the pgAgent extension in the maintenance database registered with pgAdmin.  To install pgAgent on a PostgreSQL host, connect to the *postgres* database, and navigate  through the *Tools* menu to open the Query tool.  For server versions 9.1 or later, and pgAgent 3.4.0 or later, enter the following command in the query window, and click the *Execute* icon::
+
+    CREATE EXTENSION pgagent;
+
+This command will create a number of tables and other objects in a schema called 'pgagent'.
+
+The database must also have the pl/pgsql procedural language installed - use the PostgreSQL CREATE LANGUAGE command to install pl/pgsql if necessary.  To install pl/pgsql, enter the following command in the query window, and click the *Execute* icon::
+
+	CREATE LANGUAGE plpgsql;
+
+If you are using an earlier version of PostgreSQL or pgAgent, use the *Open file* icon on the Query Tool toolbar to open a browser window and locate the *pgagent.sql* script. The installation script is installed by pgAdmin, and the installation location varies from operating system to operating system:
+ * On Windows, it is usually located under *C:\Program files\pgAdmin III* (or *C:\Program files\PostgreSQL\8.x\pgAdmin III* if installed with the PostgreSQL server installer).  
+ * On Linux, it is usually located under */usr/local/pgadmin3/share/pgadmin3* or */usr/share/pgadmin3*. 
+
+After loading the file into the Query Tool, click the *Execute* icon to execute the script.  The script will create a number of tables and other objects in a schema named *pgagent*.
+
+Daemon installation on Unix
+===========================
+
+To install the pgAgent daemon on a Unix system, you will normally need to have root privileges to modify the system startup scripts.  Modifying system startup scripts is quite system-specific so you should consult your system documentation for further information.
+
+The program itself takes few command line options, most of which are only needed for debugging or specialised configurations::
+
+  Usage:
+    /path/to/pgagent [options] <connect-string>
+  
+  options:
+    -f run in the foreground (do not detach from the terminal)
+    -t <poll time interval in seconds (default 10)>
+    -r <retry period after connection abort in seconds (>=10, default 30)>
+    -s <log file (messages are logged to STDOUT if not specified)>
+    -l <logging verbosity (ERROR=0, WARNING=1, DEBUG=2, default 0)>
+
+The connection string is a standard PostgreSQL libpq connection string (see the `PostgreSQL documentation on the connection string <http://www.postgresql.org/docs/current/static/libpq.html#libpq-connect>`_ for further details). For example, the following command line will run pgAgent against a server listening on the localhost, using a database called 'pgadmin', connecting as the user 'postgres'::
+
+  /path/to/pgagent hostaddr=127.0.0.1 dbname=postgres user=postgres
+
+Service installation on Windows
+===============================
+
+pgAgent can install itself as a service on Windows systems.  The command line options available are similar to those on Unix systems, but include an additional parameter to tell the service what to do::
+
+  Usage:
+    pgAgent REMOVE <serviceName>
+    pgAgent INSTALL <serviceName> [options] <connect-string>
+    pgAgent DEBUG [options] <connect-string>
+
+    options:
+      -u <user or DOMAIN\user>
+      -p <password>
+      -d <displayname>
+      -t <poll time interval in seconds (default 10)>
+      -r <retry period after connection abort in seconds (>=10, default 30)>
+      -l <logging verbosity (ERROR=0, WARNING=1, DEBUG=2, default 0)>
+
+The service may be quite simply installed from the command line as follows (adjust the path as required)::
+
+  "C:\Program Files\pgAdmin III\pgAgent" INSTALL pgAgent -u postgres -p secret hostaddr=127.0.0.1 dbname=postgres user=postgres
+
+You can then start the service at the command line using *net start pgAgent*, or from the *Services* control panel applet. Any logging output or errors will be reported in the Application event log. The DEBUG mode may be used to run pgAgent from a command prompt. When run this way, log messages will output to the command window.

docs/en_US/pgagent_jobs.rst

@@ -0,0 +1,116 @@
+.. _pgagent_jobs:
+
+
+*********************
+`pgAgent Jobs`:index:
+*********************
+
+pgAgent is a scheduling agent that runs and manages jobs; each job consists of steps and schedules.  
+
+To create or manage a job, use the pgAdmin tree control to browse to the server on which the pgAgent database objects were created. The tree control will display a *pgAgent Jobs* node, under which currently defined jobs are displayed. To change the properties of an existing job, right click on the name of the job, and select *Properties*.  To add a new job, right click on the *pgAgent Jobs* node, and select *Create pgAgent Job...* from the context menu.  
+
+When the pgAgent dialog opens, use the tabs on the *pgAgent Job* dialog to define the steps and schedule that make up a pgAgent job.
+
+.. image:: images/pgagent_general.png
+
+Use the fields on the *General* tab to provide general information about a job:
+
+ * Provide a name for the job in the *Name* field.
+ * Move the *Enabled* switch to the *Yes* position to enable a job, or *No* to disable a job.
+ * Use the *Job Class* drop-down to select a class (for job categorization).  
+ * Use the *Host Agent* field to specify the name of a machine that is running pgAgent to indicate that only that machine may execute the job.  Leave the field blank to specify that any machine may perform the job.  
+ 
+   **Note:** It is not always obvious what value to specify for the Host Agent in order to target a job step to a specific machine. With pgAgent running on the required machines and connected to the scheduler database, you can use the following query to view the hostnames as reported by each agent::
+
+    SELECT jagstation FROM pgagent.pga_jobagent
+
+   Use the hostname exactly as reported by the query in the Host Agent field.
+
+ * Use the *Comment* field to store notes about the job.
+
+.. image:: images/pgagent_steps.png
+
+Use the *Steps* tab to define and manage the steps that the job will perform.  Click the Add icon (+) to add a new step; then click the compose icon (located at the left side of the header) to open the step definition dialog:
+
+.. image:: images/pgagent_step_definition.png
+
+Use fields on the step definition dialog to define the step:
+
+ * Provide a name for the step in the *Name* field; please note that steps will be performed in alphanumeric order by name.
+ * Use the *Enabled* switch to include the step when executing the job (*True*) or to disable the step (*False*).
+ * Use the *Kind* switch to indicate if the job step invokes SQL code (*SQL*) or a batch script (*Batch*).  
+ 
+  * If you select *SQL*, use the *Code* tab to provide SQL code for the step.  
+  * If you select *Batch*, use the *Code* tab to provide the batch script that will be executed during the step.
+ 
+ * Use the *Connection type* switch to indicate if the step is performed on a local server (*Local*) or on a remote host (*Remote*).  If you specify a remote connection should be used for the step, the *Connection string* field will be enabled, and you must provide a libpq-style connection string.
+ * Use the *Database* drop-down to select the database on which the job step will be performed.
+ * Use the *Connection string* field to specify a libpq-style connection string to the remote server on which the step will be performed. For more information about writing a connection string, please see the `PostgreSQL documentation <http://www.postgresql.org/docs/current/static/libpq.html#libpq-connect>`_.
+ * Use the *On error* drop-down to specify the behavior of pgAgent if it encounters an error while executing the step.  Select from:
+ 
+  * *Fail* - Stop the job if you encounter an error while processing this step.
+  * *Success* - Mark the step as completing successfully, and continue.    
+  * *Ignore* - Ignore the error, and continue.
+
+ * Use the *Comment* field to provide a comment about the step.
+
+.. image:: images/pgagent_step_definition_code.png
+
+Use the context-sensitive field on the step definition dialog's *Code* tab to provide the SQL code or batch script that will be executed during the step:
+
+ * If the step invokes SQL code, provide one or more SQL statements in the *SQL query* field.
+ * If the step performs a batch script, provide the script in the *Script* field.  If you are running on a Windows server, standard batch file syntax must be used.  When running on a *nix server, any shell script may be used, provided that a suitable interpreter is specified on the first line (e.g. *#!/bin/sh*).
+
+When you've provided all of the information required by the step, click the compose icon to close the step definition dialog.  Click the add icon (+) to add each additional step, or select the *Schedules* tab to define the job schedule.
+
+.. image:: images/pgagent_schedules.png
+
+Click the Add icon (+) to add a schedule for the job; then click the compose icon (located at the left side of the header) to open the schedule definition dialog:
+
+.. image:: images/pgagent_schedule_definition.png
+
+Use the fields on the schedule definition tab to specify the days and times at which the job will execute.
+
+ * Provide a name for the schedule in the *Name* field.  
+ * Use the *Enabled* switch to indicate that pgAgent should use the schedule (*Yes*) or to disable the schedule (*No*).
+ * Use the calendar selector in the *Start* field to specify the starting date and time for the schedule.
+ * Use the calendar selector in the *End* field to specify the ending date and time for the schedule.
+ * Use the *Comment* field to provide a comment about the schedule.
+ 
+Select the *Repeat* tab to define the days on which the schedule will execute.  
+ 
+.. image:: images/pgagent_schedule_repeat.png
+
+Use the fields on the *Repeat* tab to specify the details about the schedule in a cron-style format.  The job will execute on each date or time element selected on the *Repeat* tab.
+ 
+Click within a field to open a list of valid values for that field; click on a specific value to add that value to the list of selected values for the field.  To clear the values from a field, click the X located at the right-side of the field.
+
+Use the fields within the *Days* box to specify the days on which the job will execute:
+
+ * Use the *Week Days* field to select the days on which the job will execute.
+ * Use the *Month Days* field to select the numeric days on which the job will execute.  Specify the *Last Day* to indicate that the job should be performed on the last day of the month, irregardless of the date.
+ * Use the *Months* field to select the months in which the job will execute.
+
+Use the fields within the *Times* box to specify the times at which the job will execute:
+
+ * Use the *Hours* field to select the hour at which the job will execute.
+ * Use the *Minutes* field to select the minute at which the job will execute.  
+ 
+Select the *Exceptions* tab to specify any days on which the schedule will *not* execute.  
+ 
+.. image:: images/pgagent_schedule_exceptions.png
+
+Use the fields on the *Exceptions* tab to specify days on which you wish the job to not execute; for example, you may wish for jobs to not execute on national holidays.
+
+Click the Add icon (+) to add a row to the exception table, then:
+
+ * Click within the *Date* column to open a calendar selector, and select a date on which the job will not execute.    Specify *<Any>* in the *Date* column to indicate that the job should not execute on any day at the time selected.
+ * Click within the *Time* column to open a time selector, and specify a time on which the job will not execute.  Specify *<Any>* in the *Time* column to indicate that the job should not execute at any time on the day selected.
+
+When you've finished defining the schedule, you can use the *SQL* tab to review the code that will create or modify your job.
+
+.. image:: images/pgagent_sql.png
+ 
+The *Properties* tab in the main pgAdmin window will display the details of the selected job, and the Statistics tab will show the details of each run of the job.
+
+.. image:: images/pgagent_properties.png

docs/en_US/using_pgagent.rst

@@ -0,0 +1,24 @@
+.. _using_pgagent:
+
+
+**********************
+`Using pgAgent`:index:
+**********************
+
+pgAgent is a scheduling agent that runs and manages jobs; each job consists of one or more steps and schedules.  If two or more jobs are scheduled to execute concurrently, pgAgent will execute the jobs in parallel (each with it's own thread).
+
+A step may be a series of SQL statements or an operating system batch/shell script. Each step in a given job is executed when the previous step completes, in alphanumeric order by name.  Switches on the *pgAgent Job* dialog (accessed through the *Properties* context menu) allow you to modify a job, enabling or disabling individual steps as needed.
+
+Each Job is executed according to one or more schedules. Each time the job or any of its schedules are altered, the next runtime of the job is re-calculated. Each instance of pgAgent periodically polls the database for jobs with the next runtime value in the past. By polling at least once every minute, all jobs will normally start within one minute of the specified start time. If no pgAgent instance is running at the next runtime of a job, it will run as soon as pgAgent is next started, following which it will return to the normal schedule.
+
+When you highlight the name of a defined job in the pgAdmin tree control, the *Properties* tab of the main pgAdmin window will display details about the job, and the *Statistics* tab will display details about the job's execution.
+
+Security concerns
+=================
+
+pgAgent is a very powerful tool, but does have some security considerations that you should be aware of:
+
+**Database password** - *DO NOT* be tempted to include a password in the pgAgent connection string - on Unix systems it may be visible to all users in 'ps' output, and on Windows systems it will be stored in the registry in plain text. Instead, use a libpq *~/.pgpass* file to store the passwords for every database that pgAgent must access. Details of this technique may be found in the `PostgreSQL documentation on .pgpass file <http://www.postgresql.org/docs/current/static/libpq-pgpass.html>`_.
+
+**System/database access** - all jobs run by pgAgent will run with the security privileges of the pgAgent user. SQL steps will run as the user that pgAgent connects to the database as, and batch/shell scripts will run as the operating system user that the pgAgent service or daemon is running under.  Because of this, it is essential to maintain control over the users that are able to create and modify jobs. By default, only the user that created the pgAgent database objects will be able to do this - this will normally be the PostgreSQL superuser.
+