=head1 NAME

oar-database - manage OAR database.

=head1 SYNOPSIS

B<oar-database> I<--create> [I<OPTIONS>] 

B<oar-database> I<--drop> [I<OPTIONS>] 

B<oar-database> I<--upgrade> [I<OPTIONS>] 

B<oar-database> I<--reset> [I<OPTIONS>] 

B<oar-database> I<--check> [I<OPTIONS>] 

=head1 DESCRIPTION

OAR uses a database for it's persitent data either using the MySQL or PostgreSQL backend (see oar.conf). oar-database is provided to manage that database.

=head1 ACTIONS

=over

=item B<--create>

Create an OAR database: inject schema and default data and create users/roles.

=item B<--drop>

Drop an existing OAR database and associated users/roles.

=item B<--upgrade>

Upgrade an existing OAR database.

=item B<--reset>

Reset an existing OAR database to the state of the fresh new one.

=item B<--check>

Check that OAR database is accessible and up to date (schema version).

=back

=head1 OPTIONS

=head2 General parameters

=over

=item B<--conf>=I<OAR_CONF_FILE>

Define the OAR configuration file to use. By default I<%%OARCONFDIR%%/oar.conf> is used. If this file doesn't exist, the default parameters for each value are used.

=item B<--update-conf>

The database parameters given in the command line are written to the OAR_CONF_FILE

=item B<-f,--force-sql>

Force to continue the execution even if a SQL command fails

=item B<-y,--force-yes>

Force oar-database to continue without prompt even if it could be harmful.

=back

=head2 Database backend parameters

These parameters are only required by the I<--create> and I<--drop> actions.

=over

=item B<--db-is-local>

PostgreSQL: use local admin account to execute admin commands. MySQL: use the unix socket connection to execute admin commands.

=item B<--db-admin-user>=I<DB_ADMIN_USER>

Set database backend admin username.

=item B<--db-admin-pass>=I<DB_ADMIN_PASS>

Set database backend admin password.

=back

=head2 OAR database parameters

If not specified, OAR database parameters are taken from I<OAR_CONF_FILE>. Please prefer setting the configurations in that file instead of using these options. 

=over

=item B<--db-type>=I<DB_TYPE>

Database backend to use, I<mysql> or I<Pg> (for PostgreSQL).

=item B<--db-user>=I<DB_USER>

Set OAR username to access the database. Override the one set in OAR_CONF_FILE.

=item B<--db-pass>=I<DB_PASS>

Set OAR user password to access the database. Override the one set in OAR_CONF_FILE.

=item B<--db-host>=I<DB_HOST>

Set the database backend hostname. Override the one set in OAR_CONF_FILE.

=item B<--db-port>=I<DB_PORT>

Set the database backend TCP port. Override the one set in OAR_CONF_FILE.

=item B<--db-name>=I<DB_NAME>

Set OAR database name. Override the one set in OAR_CONF_FILE.

=item B<--db-ro-user>=I<DB_RO_USER>

Set OAR username for read-only access the database. Override the one set in OAR_CONF_FILE.

=item B<--db-ro-pass>=I<DB_RO_PASS>

Set OAR user password for read-only access the database. Override the one set in OAR_CONF_FILE.

=item B<-d,--debug>

Activate the display of debugging information.

=item B<-h,--help>

Display this help.

=back

=head1 EXAMPLES

=head2 MySQL

First you need to specify the database parameters in %%OARCONFDIR%%/oar.conf. These parameters will be used by B<oar-database>.

To create a new database (assuming that the MySQL root password is B<PASS>):

B<oar-database --create --db-admin-user root --db-admin-pass PASS>

Or if the MySQL server is local and accessible using the unix socket:

B<oar-database --create --db-is-local>

To upgrade an existing database:

B<oar-database --upgrade>

=head2 PostgreSQL

First you need to specify the database parameters in %%OARCONFDIR%%/oar.conf. These parameters will be used by B<oar-database>. If your PostgreSQL database is on the local system, you can use the B<--db-is-local> option which will use PostgreSQL unix account (needs root privileges).

To create a new database:

B<oar-database --create --db-is-local>

To upgrade an existing database:

B<oar-database --upgrade>

=head2 Advanced usages

To make some tests or to administrate several databases, you can also specify the sql parameters on the command line. For example:

B<oar-database --create --db-type=Pg --db-host=HOST \
               --db-user=oar --db-pass=PASS \
               --db-admin-user=ADMIN_USER --db-admin-pass=ADMIN_PASS>

will create the oar database and the oar user on the postgresql system hosted by B<HOST>. The user B<ADMIN_USER> must have the right to create new databases and new roles on this system.

=head1 FILES

=over 

=item %%OARDIR%%/database/mysql_structure.sql, %%OARDIR%%/database/pg_structure.sql

SQL instructions for creating the structure of the oar database.

=item %%OARDIR%%/database/mysql_default_admission_rules.sql, %%OARDIR%%/database/pg_default_admission_rules.sql

SQL instructions for inserting the default admission rules in the oar database.

=item %%OARDIR%%/database/default_data.sql

SQL instructions for inserting the default data in the oar database.

=item %%OARDIR%%/database/mysql_reset_structure.sql, %%OARDIR%%/database/pg_reset_structure.sql

SQL instruction for emptying an existing oar database.

=item %%OARDIR%%/database/mysql_structure_upgrade_*.sql, %%OARDIR%%/database/pg_structure_upgrade_*.sql

SQL instructions for upgrading an existing database.

=back
 
=cut

=head1 COPYRIGHTS

 Copyright 2003-2018 Laboratoire d'Informatique de Grenoble (http://www.liglab.fr). This software is licensed under the GNU General Public License Version 2 or above. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

