PhyloSoC:phyinit

From NESCent Informatics Wiki
Jump to: navigation, search

NAME

phyinit.pl - Initialize a PhyloDB database.

VERSION

This documentation refers to phyinit version 1.0.

SYNOPSIS

 USAGE: phyinit.pl -d 'DBI:mysql:database=biosql;host=localhost' 
                   -u UserName -p dbPass
     REQUIRED ARGUMENTS:
       --dsn        # The DSN string for the DB connection
       --dbuser     # User name to connect with
       --dbpass     # User password to connect with
     ALTERNATIVE TO --dsn:
       --driver     # DB Driver "mysql", "Pg", "Oracle" 
       --dbname     # Name of database to use
       --host       # Host to connect with (ie. localhost)
     ADDITIONAL OPTIONS:
       --sqldir     # SQL Dir that contains the SQL to create tables
       --quiet      # Run the program in quiet mode.
       --verbose    # Run the program with maximum output
     ADDITIONAL INFORMATION:
       --version    # Show the program version     
       --usage      # Show program usage
       --help       # Show a short help message
       --man        # Show full program manual

DESCRIPTION

Initialize the PhyloDB table in a BioSQL database. All required tables and foreign keys will be created. The user will be warned before any existing data is deleted. This will initially only work with MySQL, but other databases drivers will later be made available with the driver argument.

COMMAND LINE ARGUMENTS

Required Arguments

-d, --dsn 
The DSN of the database to connect to; default is the value in the environment variable DBI_DSN. If DBI_DSN has not been defined and the string is not passed to the command line, the dsn will be constructed from --driver, --dbname, --host

DSN must be in the form: DBI:mysql:database=biosql;host=localhost

-u, --dbuser 
The user name to connect with; default is the value in the environment variable DBI_USER.

This user must have permission to create databases.

-p, --dbpass 
The password to connect with; default is the value in the environment variable DBI_PASSWORD. If this is not provided at the command line the user is prompted.

Alternative to --dsn

An alternative to passing the full dsn at the command line is to provide the components separately.

--host 
The database host to connect to; default is localhost.
--dbname 
The database name to connect to; default is biosql.
--driver 
The database driver to connect with; default is mysql. Options other then mysql are currently not supported.

Additional Options

-s, --sqldir 
Directory containing the sql code for PhyloDB initialization.
-q, --quiet 
Run the program in quiet mode. No output will be printed to STDOUT and the user will not be prompted for intput. CURRENTLY NOT IMPLEMENTED.
--verbose 
Execute the program in verbose mode.

Additional Information

--version 
Show the program version.
--usage 
Show program usage statement.
--help 
Show a short help message.
--man 
Show the full program manual.

EXAMPLES

The --dsn argument

Example initializing a database using the --dsn argument. You will be prompted for the user password when one is not provided at the command line. You would of course replace name with your user name.

   phyinit.pl -u name --dsn 'DBI:mysql:database=biosql;host=localhost'

Command line alternative to --dsn

Creating the same database as above using the dsn components passed at the comand line.

   phyinit.pl -u name --host localhost --dbname biosql --driver mysql

DIAGNOSTICS

The known error messages below are followed by possible descriptions of the error and possible solutions:

DBD::mysql::db do failed: Can't create table './biosql/#sql-d2_b.frm' (errno: 150) at ./phyinit.pl line 416, line 1. 
Description: MySQL Error messages that make reference to errno: 150 are related to problems with foreign keys. This will occur when you attempt to initialize the PhyloDB tables in a database database that does not already contain a BioSQL schema.

Solution: Run the proper SQL script to create the BioSQL database.

CONFIGURATION AND ENVIRONMENT

Many of the options passed at the command line can be set as options in the user's environment.

DBI_USER 
User name to connect to the database.
DBI_PASSWORD 
Password for the database connection
DBI_DSN 
DSN for database connection.

For example in the bash shell this would be done be editing your .bashrc file to contain:

   export DBI_USER=yourname
   export DBI_PASS=yourpassword
   export DBI_DSN='DBI:mysql:database=biosql;host-localhost'

When these are present in the environment, you can initialize a database with the above variables by simply typing phyinit.pl at the command line.

DEPENDENCIES

The phyinit program is dependent on the following PERL modules:

DBI - http://dbi.perl.org 
The PERL Database Interface (DBI) module allows for connections to multiple databases.
DBD_MySQL - http://search.cpan.org/~capttofu/DBD-mysql-4.005/lib/DBD/mysql.pm 
MySQL database driver for DBI module.
DBD_Pg - http://search.cpan.org/~rudy/DBD-Pg-1.32/Pg.pm 
PostgreSQL database driver for the DBI module.
Getopt - http://perldoc.perl.org/Getopt/Long.html 
The Getopt module allows for the passing of command line options to perl scripts.

A RDBMS is also required. This can be one of:

MySQL - http://www.mysql.com 
PostgreSQL - http://www.postgresql.org 

BUGS AND LIMITATIONS

Known Limitations:

  • Currently only stable with the MySQL Database driver.
  • DSN string must currently be in the form: DBI:mysql:database=biosql;host=localhost
  • Currently assumes that a valid BioSQL schema exists for the database named. There is currently not check for complience to this restriction.

Please report additional problems to James Estill <JamesEstill at gmail.com>

SEE ALSO

The program phyinit.pl is a component of a package of comand line programs for PhyloDB management. Additional programs include:

phyimport.pl 
Import common phylogenetic file formats.
phyexport.pl 
Export tree data in PhyloDB to common file formats.
phyopt.pl 
Compute optimization values for a PhyloDB database.
phyqry.pl 
Return a standard report of information for a given tree.
phymod.pl 
Modify an existing phylogenetic database by deleting, adding or copying branches.

LICENSE

This program may be used, distributed or modified under the same terms as Perl itself. Please consult the Perl Artistic License (http://www.perl.com/pub/a/language/misc/Artistic.html) for the terms under which you may use, modify, or distribute this script.

THIS SOFTWARE COMES AS IS, WITHOUT ANY EXPRESS OR IMPLIED WARRANTY. USE AT YOUR OWN RISK.

AUTHORS

James C. Estill <JamesEstill at gmail.com>

Hilmar Lapp <hlapp at gmx.net>

William Piel <william.piel at yale.edu>

HISTORY

Started: 05/30/2007

Updated: 08/17/2007