JarCastingfacepalm
Database migration and management tool.
Usage
# Reinitialize the database using the database tarball from the latest QA drop.
facepalm -h hostname -U username -d database -q latest -f filename.tar.gz
# Explicitly fetch the database tarball from the QA drop on 6/15/2012.
facepalm -h hostname -U username -d database -q 2012-06-15 -f filename.tar.gz
# Reinitiaize the database using a local database tarball.
facepalm -h hostname -U username -d database -f /path/to/filename.tar.gz
# Obtain the database tarball from the latest build of a Jenkins job.
facepalm -h hostname -U username -d database -j jobname -f filename.tar.gz
# Upgrade the database from the existing version using the conversions in the
# database tarball from the latest QA drop.
facepalm -m update -h hostname -U username -d database -q latest -f filename.tar.gz
# Upgrade the database from the existing version using the conversions in the
# database tarball from the QA drop on 6/15/2012.
facepalm -m update -h hostname -U username -d database -q 2012-06-15 -f filename.tar.gz
# Upgrade the database from the existing version using the conversions in a
# local database tarball.
facepalm -m update -h hostname -U username -d database -f /path/to/filename.tar.gz
# Upgrade the database from the existing version using the conversions in the
# database tarball from the latest build of a Jenkins job.
facepalm -m update -h hostname -U username -d database -j jobname -f filename.tar.gz
# Obtaining help.
facepalm -?
Required Arguments
All of the arguments that are required have default values, so these arguments may not have to be explicitly defined on the command line unless the default settings won't work in your case.
-m --mode
Default value: init
This argument indicates whether facepalm should update or completely initialize the database. If the mode is set to update then the database schema will be updated without clobbering any data in the database (unless some database rows are supposed to be clobbered as part of a database conversion). If this mode is set to init then the database will be completely reinitialized.
-h --host
Default Value: localhost
This argument indicates the name of host where the database resides. If this argument is not specified, facepalm will attempt to connect to the database server on the local host.
-p --port
Default Value: 5432
This argument indicates which port number to use when attempting to connect to the datase. If this argument is not specified, facepalm will attempt to connect to port 5432 (the default listen port for PostgreSQL).
-d --database
Default Value: de
This argument indicates the name of the database to update. If this argument is not specified, faceplam will update the de database.
-U --user
Default Value: de
This argument indicates the username to use when authenticating to the database. If this argument is not specified, facepalm will use de for the username. Note that the database user must own both the database and the public schema in the database.
There is no command-line option to specify the password. Instead, facepalm will attempt to look up the password in the .pgpass file. If the password can't be obtained from .pgpass, facepalm will prompt the user for the password. Because facepalm uses JDBC to connect to the database, only one connection to the database is established per facepalm invocation. Because of this, there will be at most one password prompt per facepalm invocation.
Options
-j --job
This argument indicates the name of a Jenkins job from which the database initialization scripts can be obtained. At the time of this writing, valid job names are database and database-dev. This option is used in conjunction with the -f or --filename option to specify the name of the Jenkins job along with the name of the build artifact produced by the job. If the file name is not specified explicitly then facepalm assumes that it is database.tar.gz.
This argument is one of three command-line arguments that can be used to indicate where facepalm should obtain its database initialization files. The other two options are -q, which is equivalent to --qa-drop, and -f, which is equivalent to --filename.
-q --qa-drop
This argument indicates the QA drop from which the database initialization scripts should be obtained. This can either be the date of the QA drop in YYYY-MM-DD format (for example, 2012-06-12) or the literal string latest to indicate that facepalm should obtain the database initialization scripts from the most recent QA drop. This option is used in conjunction with the -f or --filename option to specify the location of the QA drop along with the name of the file containing the database initialization scripts. If the file name is not specified explicitly then facepalm assumes that it is database.tar.gz.
This argument is one of three command-line arguments that can be used to indicate where facepalm should obtain its database initialization files. The other two options are -j, which is equivalent to --job, and -f, which is equivalent to --filename.
-f --filename
Default Value: database.tar.gz
This argument is used to specify the name of the tarball containing the database initialization scripts. If this argument is used by itself (that is, without the -j or -q options) then facepalm will treat its value as the path to a tarball on the local file system. If this argument is used in conjunction with the -j or -q options then facepalm will treat its value as the name of the tarball containing the database initialization scripts on the remote server.
-? --help --no-help
The -? and --help options can be used to tell facepalm to display a help message. The --no-help message can be used to indicate that help should not be displayed, but this is the default behavior anyway.
--debug --no-debug
The --debug option can be used to tell facepalm to display additional debugging information, which can be helpful in troubleshooting database initialization problems. The --no-debug option can be used to disable debugging, but this is the default behavior anyway.
Diagnostics
::required-options-missing
No value was provided for a required option. This error is unlikely to occur in practice because all of the required arguments have default values. If this does occur, verify that the command line is correct.
::build-artifact-retrieval-failed
The utility attempted to get the database build artifact from a remote URL and a status that was less than 200 or greater than 299 was returned. Verify that the specified QA drop or Jenkins job name is correct.
::database-tarball-copy-failed
The utility was unable to copy the database tarball to the temporary directory. Verify that the file system is not full or write protected.
::command-execution-failed
The utility was unable to execute a subcommand. The subcommand should be listed in the error message. Verify that the required subcommand is installed on the system and that its location is in the PATH environment variable.
::build-artifact-expansion-failed
The utility attempted to extract the database initialization files from the database build artifact and tar returned a non-zero exit status. Verify that the build artifact is a valid tar file.
::temp-directory-creation-failure
The utility attempted and was unable to create a temporary directory within the current working directory. Verify that you have write permission to the current working directory.
::database-connection-failure
The utility was unable to connect to the database. Verify that the database connection settings are correct and, if applicable, that the .pgpass file is formatted correctly.
::unknown-mode
The specified mode is not recognized by the utility. Verify that the command line is correct.
::conversion-validation-error
Some database conversion scripts contain sanity checks; this is the error that is raised if one of the sanity checks fails. Gather the information requested in the error message and forward it to the Core Software team.
::no-password-supplied
The database authentication password could not be found in the '.pgpass' file and no terminal is attached to the utility (so the utility can't prompt for the password). Verify that the '.pgpass' file is formatted correctly and has an entry for the desired database. If you want the utility to prompt you for the password, be sure to run the utility in the foreground.
::incompatible-database-conversion
One of the database conversions in the database tarball has a version number that is greater than the maximum compatible database version defined in kameleon. Verify that the correct database tarball and facepalm version are being used. If everything appears to be correct, contact Core Software to ensure that kameleon has been updated correctly.
Other Errors
Other errors represent uncaught exceptions. The most likely cause of these errors is a failure to connect to or update the database. Verify that the command line is correct, paying close attention to the database connection settings. It might also be helpful to review the exception itself to find out if it contains any useful information. If you're unable to find the cause of the problem, please send a copy of the command line, the exception and the full stack trace, if there is one, to the Core Software group.
Bugs and Limitations
There are no known bugs in facepalm at this time. Please report problems to the Core Software group. Patches are welcome.
License and Copyright
Copyright (c) 2012, The Arizona Board of Regents on behalf of The University of Arizona
All rights reserved.
Developed by: iPlant Collaborative at BIO5 at The University of Arizona http://www.iplantcollaborative.org
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
-
Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
-
Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
-
Neither the name of the iPlant Collaborative, BIO5, The University of Arizona nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
