Merge pull request #1728

docs: fix Pool explanation for migration jobs

CHANGELOG.md

@@ -58,6 +58,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Documentation
 - docs: improvements for droplet, jobdefs [PR #1581]
+- docs: fix Pool explanation for migration jobs [PR #1728]
 
 ### Fixed
 - dird: fix `purge oldest volume` [PR #1628]
@@ -117,4 +118,5 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 [PR #1717]: https://github.com/bareos/bareos/pull/1717
 [PR #1718]: https://github.com/bareos/bareos/pull/1718
 [PR #1719]: https://github.com/bareos/bareos/pull/1719
+[PR #1728]: https://github.com/bareos/bareos/pull/1728
 [unreleased]: https://github.com/bareos/bareos/tree/master

docs/manuals/source/TasksAndConcepts/MigrationAndCopy.rst

@@ -32,7 +32,7 @@ Jobs can be selected for migration based on a number of criteria such as:
 
 The details of these selection criteria will be defined below.
 
-To run a Migration job, you must first define a Job resource very similar to a Backup Job but with :config:option:`dir/job/Type`\  = Migrate instead of :config:option:`dir/job/Type`\  = Backup. One of the key points to remember is that the Pool that is specified for the migration job is the only pool from which jobs will be migrated, with one exception noted below. In addition, the Pool to which the selected Job or Jobs will be migrated is defined by the
+To run a Migration job, you must first define a Job resource very similar to a Backup Job but with :config:option:`dir/job/Type`\  = Migrate. One of the key points to remember is that the Pool that is specified for the migration job is the only pool from which jobs will be migrated. In addition, the Pool to which the selected Job or Jobs will be migrated is defined by the
 :config:option:`dir/pool/NextPool`\  = ... in the Pool resource specified for the Migration Job.
 
 Bareos permits Pools to contain Volumes of different Media Types. However, when doing migration, this is a very undesirable condition. For migration to work properly, you should use Pools containing only Volumes of the same Media Type for all migration jobs.
@@ -100,7 +100,7 @@ Job Resource
    :config:option:`dir/job/SelectionPattern`\
 
 -  | :config:option:`dir/job/Pool`\
-   | For :config:option:`dir/job/SelectionType`\  other than SQLQuery, this defines what Pool will be examined for finding JobIds to migrate
+   | Defines the Pool that will be examined for finding JobIds to migrate. This Pool also sets the storage for reading the volumes containing the jobs.
 
 -
 

docs/manuals/source/include/config/DirSelectionPatterns-sql1.conf

@@ -7,6 +7,7 @@ Job {
     Name = "<name>"
     JobDefs = "DefaultJob"
     Type = Migrate
+    Pool = Full
     Selection Type = SQL Query
     # Multiple lines instructions is available since version 21.0.0
     Selection Pattern = "WITH pids AS

docs/manuals/source/manually_added_config_directive_descriptions/dir-job-Pool.rst.inc

@@ -1,4 +1,4 @@
 The Pool directive defines the pool of Volumes where your data can be backed up. Many Bareos installations will use only the Default pool. However, if you want to specify a different set of Volumes for different Clients or different Jobs, you will probably want to use Pools. For additional details, see the :ref:`DirectorResourcePool` of this chapter. This directive is required.
 
-In case of a Copy or Migration job, this setting determines what Pool will be examined for finding JobIds to migrate. The exception to this is when :config:option:`dir/job/SelectionType`\  = SQLQuery, and although a Pool directive must still be specified, no Pool is used, unless you specifically include it in the SQL query. Note, in any case, the Pool resource defined by the Pool directive must contain a :config:option:`dir/pool/NextPool`\  = ...
+In case of a Copy or Migration job, this setting determines which Pool is examined to find JobIds to migrate. If :config:option:`dir/job/SelectionType`\  is SQLQuery, the Pool directive is still used to determine the Storage to read from. Accordingly, the SQL query must only return JobIds from that pool. In any case, the Pool resource defined by the Pool directive must contain a :config:option:`dir/pool/NextPool`\  = ...
 directive to define the Pool to which the data will be migrated.

docs/manuals/source/manually_added_config_directive_descriptions/dir-job-SelectionPattern.rst.inc

@@ -4,10 +4,9 @@ For the OldestVolume and SmallestVolume, this Selection pattern is not used (ign
 
 For the Client, Volume, and Job keywords, this pattern must be a valid regular expression that will filter the appropriate item names found in the Pool.
 
-For the SQLQuery keyword, this pattern must be a valid :command:`SELECT` SQL statement that returns JobIds.
+For the SQLQuery keyword, this pattern must be a valid :command:`SELECT` SQL statement that returns JobIds. The returned JobIds must be from the pool specified in the Pool statement. This is because Bareos will always use the storage associated with that pool when reading a job that is to be copied or migrated. If you want to copy or migrate jobs from different pools with the SQLQuery selection type, use separate Jobs and matching SQL statements for each pool.
 
 Example:
 
 .. literalinclude:: /include/config/DirSelectionPatterns-sql1.conf
    :language: bareosconfig
-