========================================================================
== About the scripts here                                             ==
========================================================================

==> update_database_list.pl

  - Purpose

    Updates the 'db' table in the production database on ens-staging1
    with new databases found on the staging servers.  It will discover
    new databases and will set the 'is_current' flag for all found
    databases to 1 (true).  It will also notice when databases goes away
    from one reason or another.

  - Who runs this and when?

    The release coordinator runs this script whenever a new database or
    a set of new databases has been copied onto the staging servers.
    This means that this script may be run many times during the release
    process.

  - How to run it?

    In the simplest case, this is how it's done (release NN):

      ./update_database_list.pl -r NN -wp PASSWORD

    Run the script with no options to see a short usage info text.  Run
    with -a to get a description of the script.

  - What to look out for?

    Running this script with the wrong release will mark all databases
    of the current release as "not current".  Just running it again,
    specifying the correct release, will sort this out.

    Running it twice will have no adverse effects.


==> populate_production_db_tables.pl

  - Purpose

    Takes the data from the four views 'attrib_type', 'external_db',
    'misc_set', and 'unmapped_reason' views in the production database
    and copies them to one or several other Core-like databases.  These
    views are supported by the 'master_%' tables.

  - Who runs this and when?

    This script may be used by the genebuilders to populate a new
    database with the data of these four tables, but the release
    coordinator may also use it during the release process, before the
    handover to the web-team, to synchronise them over all Core-like
    databases on the staging servers.

  - How to run it?

    Running the script without any options will display usage info.

    To insert the four tables into one single database:

      populate_production_db_tables.pl -h HOST \
        -u USER -p PASSWORD -d DATABASE

    To only pick the 'external_db' table:

      populate_production_db_tables.pl -h HOST \
        -u USER -p PASSWORD -d DATABASE -t external_db

    To update all database on a server with all four tables (release
    NN):

      populate_production_db_tables.pl -h HOST \
        -u USER -p PASSWORD --core=NN

  - What to look out for?

    The script creates a backup of the tables that it replaces.  These
    backups should be deleted.  This is done simply like this (for all
    Core-like databases on a server):

      populate_production_db_tables.pl -h HOST \
        -u USER -p PASSWORD --core=NN --cleanup

    Running the script twice will make it complain about already
    existing backup tables.  These may be automatically dropped by using
    the -D flag, but you need to be sure you actually want to drop all
    backups.

    The script will notify you of any new or deleted entries (compared
    to the entries in the backed up tables) and will give you an SQL
    statement that may be use to study these.


==> populate_analysis_description.pl

  - Purpose

    Populates the 'analysis_description' table in all
    Core-like databases on the staging servers from the
    'full_analysis_description' view in the production database.
    This view is supported by various other views and tables in the
    production database.

  - Who runs this and when?

    This script will be run by the release coordinator before handover
    to the web-team.  Since the script relies on the database names
    stored in the production database, one can only run it on databases
    detected by the update_database_list.pl script (see above).

  - How to run it?

    Running the script without any options will display usage info.

    The options are very similar to those of the
    populate_production_db_tables.pl script (see above), and the mode of
    operation is likewise similar to that script.

  - What to look out for?

    As for the populate_production_db_tables.pl script, this script also
    creates a backup of the analysis_description table which needs to be
    removed.

    The script will also warn about analyses that it expected to find
    in the database but didn't (they are expected since they are linked
    to the database in the production database, but might have gone out
    of use since the last update, so this is not a big deal), and will
    flag as errors any analysis that is found but that does not have a
    corresponding analysis description in the production database.  If
    this happens, the release coordinator must either add a new analysis
    description to the production database, or connect an existing
    analysis description to the target database.
