Update to README

Added some more information and examples about Azure and setting up
recovery.

Editorialized by Daniel Farina.

CONTRIBUTORS

@@ -61,3 +61,4 @@ Timothée Peignier <[email protected]>
 Toby Collier <[email protected]>
 Tuomas Silen <[email protected]>
 https://github.com/earsdown
+https://github.com/tvarsis <[email protected]>

README.rst

@@ -75,13 +75,21 @@ Optional:
 * Pass ``--aws-instance-profile`` to gather credentials from the
   Instance Profile.  See `Using AWS IAM Instance Profiles`.
 
+
 Azure Blob Store
 ''''''''''''''''
+Example below is based on the following blob storage in Azure in the
+resource group ``resgroup`` :
+https://store1.blob.core.windows.net/container1/nextpath
+
+* WALE_WABS_PREFIX (e.g. ``wabs://container1/nextpath``)
+* WABS_ACCOUNT_NAME (e.g. ``store1``)
+* WABS_ACCESS_KEY (Use key1 from running ``azure storage account keys
+  list store1 --resource-group resgroup`` You will need to have the
+  Azure CLI installed for this to work.)
+* WABS_SAS_TOKEN (You only need this if you have not provided an
+  WABS_ACCESS_KEY)
 
-* WALE_WABS_PREFIX (e.g. ``wabs://container/path/optionallymorepath``)
-* WABS_ACCOUNT_NAME
-* WABS_ACCESS_KEY or
-* WABS_SAS_TOKEN
 
 Google Storage
 ''''''''''''''
@@ -211,7 +219,7 @@ continuous archiving, one needs to edit ``postgresql.conf`` and
 restart the server.  The important settings to enable continuous
 archiving are related here::
 
-  wal_level = archive # hot_standby in 9.0 is also acceptable
+  wal_level = archive # hot_standby and logical in 9.x is also acceptable
   archive_mode = on
   archive_command = 'envdir /etc/wal-e.d/env wal-e wal-push %p'
   archive_timeout = 60
@@ -225,48 +233,13 @@ Every segment archived will be noted in the PostgreSQL log.
 
 A base backup (via ``backup-push``) can be uploaded at any time, but
 this must be done at least once in order to perform a restoration.  It
-must be done again if any WAL segment was not correctly uploaded:
-point in time recovery will not be able to continue if there are any
-gaps in the WAL segments.
+must be done again if you decided to skip archiving any WAL segments:
+replication will not be able to continue if there are any gaps in the
+stored WAL segments.
 
 .. _envdir: http://cr.yp.to/daemontools/envdir.html
 .. _daemontools: http://cr.yp.to/daemontools.html
 
-Pulling a base backup from S3::
-
-    $ sudo -u postgres bash -c                          \
-    "envdir /etc/wal-e.d/pull-env wal-e                 \
-    --s3-prefix=s3://some-bucket/directory/or/whatever  \
-    backup-fetch /var/lib/my/database LATEST"
-
-This command makes use of the "LATEST" pseudo-name for a backup, which
-queries S3 to find the latest complete backup.  Otherwise, a real name
-can be used::
-
-    $ sudo -u postgres bash -c                          \
-    "envdir /etc/wal-e.d/pull-env wal-e                 \
-    --s3-prefix=s3://some-bucket/directory/or/whatever  \
-    backup-fetch                                        \
-    /var/lib/my/database base_LONGWALNUMBER_POSITION_NUMBER"
-
-One can find the name of available backups via the experimental
-``backup-list`` operator, or using one's remote data store browsing
-program of choice, by looking at the ``PREFIX/basebackups_NNN/...``
-directory.
-
-It is also likely one will need to provide a ``recovery.conf`` file,
-as documented in the PostgreSQL manual, to recover the base backup, as
-WAL files will need to be downloaded to make the hot-backup taken with
-backup-push.  The WAL-E's ``wal-fetch`` subcommand is designed to be
-useful for this very purpose, as it may be used in a ``recovery.conf``
-file like this::
-
-    restore_command = 'envdir /etc/wal-e.d/env wal-e wal-fetch "%f" "%p"'
-
-.. WARNING::
-   If the archived database contains user defined tablespaces please review
-   the ``backup-fetch`` section below before utilizing that command.
-
 
 Primary Commands
 ----------------
@@ -286,47 +259,82 @@ WAL-E's tablespace restoration behavior.
 backup-fetch
 ''''''''''''
 
-There are two possible scenarios in which ``backup-fetch`` is run:
+Use ``backup-fetch`` to restore a base backup from storage.
+
+This command makes use of the ``LATEST`` pseudo-backup-name to find a
+backup to download::
+
+    $ envdir /etc/wal-e.d/fetch-env wal-e               \
+    --s3-prefix=s3://some-bucket/directory/or/whatever  \
+    backup-fetch /var/lib/my/database LATEST
+
+Also allowed is naming a backup specifically as seen in
+``backup-list``, which can be useful for restoring older backups for
+the purposes of point in time recovery::
+
+    $ envdir /etc/wal-e.d/fetch-env wal-e               \
+    --s3-prefix=s3://some-bucket/directory/or/whatever  \
+    backup-fetch                                        \
+    /var/lib/my/database base_LONGWALNUMBER_POSITION_NUMBER
+
+One will need to provide a `recovery.conf`_ file to recover WAL
+segments associated with the backup.  In short, `recovery.conf`_ needs
+to be created in the Postgres's data directory with content like::
+
+    restore_command = 'envdir /etc/wal-e.d/env wal-e wal-fetch %f %p'
+    standby_mode = on
+
+.. _recovery.conf: https://www.postgresql.org/docs/current/static/recovery-config.html
+
+A database with such a `recovery.conf` set will poll WAL-E storage for
+WAL indefinitely.  You can exit recovery by running `pg_ctl promote`_.
+
+If you wish to perform Point In Time Recovery (PITR) can add `recovery
+targets`_ to `recovery.conf`_, looking like this::
+
+    recovery_target_time = '2017-02-01 19:58:55'
+
+There are several other ways to specify recovery target,
+e.g. transaction id.
 
-No User Defined Tablespaces Existed in Backup
-*********************************************
+Regardless of recovery target, the result by default is Postgres will
+pause recovery at this time, allowing inspection before promotion.
+See `recovery targets`_ for details on how to customize what happens
+when the target criterion is reached.
 
-If the archived database *did not* contain any user defined tablespaces
-at the time of backup it is safe to execute ``backup-fetch`` with no
-additional work by following previous examples.
+.. _pg_ctl promote: https://www.postgresql.org/docs/current/static/app-pg-ctl.html
+.. _recovery targets: https://www.postgresql.org/docs/current/static/recovery-target-settings.html
 
-User Defined Tablespaces Existed in Backup
-******************************************
+Tablespace Support
+******************
 
-If the archived database *did* contain user defined tablespaces at the
-time of backup there are specific behaviors of WAL-E you must be aware of:
+If and only if you are using Tablespaces, you will need to consider
+additional issues on how run ``backup-fetch``.  The options are:
 
-User-directed Restore
-"""""""""""""""""""""
+* User-directed Restore
 
-WAL-E expects that tablespace symlinks will be in place prior to a
-``backup-fetch`` run. This means prepare your target path by insuring
-``${PG_CLUSTER_DIRECTORY}/pg_tblspc`` contains all required symlinks
-before restoration time. If any expected symlink does not exist
-``backup-fetch`` will fail.
+  WAL-E expects that tablespace symlinks will be in place prior to a
+  ``backup-fetch`` run. This means prepare your target path by
+  insuring ``${PG_CLUSTER_DIRECTORY}/pg_tblspc`` contains all required
+  symlinks before restoration time. If any expected symlink does not
+  exist ``backup-fetch`` will fail.
 
-Blind Restoration
-"""""""""""""""""
+* Blind Restore
 
-If you are unable to reproduce tablespace storage structures prior to
-running ``backup-fetch`` you can set the option flag ``--blind-restore``.
-This will direct WAL-E to skip the symlink verification process and place
-all data directly in the ``${PG_CLUSTER_DIRECTORY}/pg_tblspc`` path.
+  If you are unable to reproduce tablespace storage structures prior
+  to running ``backup-fetch`` you can set the option flag
+  ``--blind-restore``.  This will direct WAL-E to skip the symlink
+  verification process and place all data directly in the
+  ``${PG_CLUSTER_DIRECTORY}/pg_tblspc`` path.
 
-Automatic Storage Directory and Symlink Creation
-""""""""""""""""""""""""""""""""""""""""""""""""
+* Restoration Specification
 
-Optionally, you can provide a restoration specification file to WAL-E
-using the ``backup-fetch`` ``--restore-spec RESTORE_SPEC`` option.
-This spec must be valid JSON and contain all contained tablespaces
-as well as the target storage path they require, and the symlink
-postgres expects for the tablespace. Here is an example for a
-cluster with a single tablespace::
+  You can provide a restoration specification file to WAL-E using the
+  ``backup-fetch`` ``--restore-spec RESTORE_SPEC`` option.  This spec
+  must be valid JSON and contain all contained tablespaces as well as
+  the target storage path they require, and the symlink postgres
+  expects for the tablespace. Here is an example for a cluster with a
+  single tablespace::
 
     {
         "12345": {
@@ -338,8 +346,9 @@ cluster with a single tablespace::
         ],
     }
 
-Given this information WAL-E will create the data storage directory
-and symlink it appropriately in ``${PG_CLUSTER_DIRECTORY}/pg_tblspc``.
+  Given this information WAL-E will create the data storage directory
+  and symlink it appropriately in
+  ``${PG_CLUSTER_DIRECTORY}/pg_tblspc``.
 
 .. WARNING::
    ``"link"`` properties of tablespaces in the restore specification