.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "oar-database 1"
.TH oar-database 1 2024-04-10 oar-database "OAR commands"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
oar\-database \- manage OAR database.
.SH SYNOPSIS
.IX Header "SYNOPSIS"
\&\fBoar-database\fR \fI\-\-create\fR [\fIOPTIONS\fR]
.PP
\&\fBoar-database\fR \fI\-\-drop\fR [\fIOPTIONS\fR]
.PP
\&\fBoar-database\fR \fI\-\-upgrade\fR [\fIOPTIONS\fR]
.PP
\&\fBoar-database\fR \fI\-\-reset\fR [\fIOPTIONS\fR]
.PP
\&\fBoar-database\fR \fI\-\-check\fR [\fIOPTIONS\fR]
.SH DESCRIPTION
.IX Header "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.
.SH ACTIONS
.IX Header "ACTIONS"
.IP \fB\-\-create\fR 4
.IX Item "--create"
Create an OAR database: inject schema and default data and create users/roles.
.IP \fB\-\-drop\fR 4
.IX Item "--drop"
Drop an existing OAR database and associated users/roles.
.IP \fB\-\-upgrade\fR 4
.IX Item "--upgrade"
Upgrade an existing OAR database.
.IP \fB\-\-reset\fR 4
.IX Item "--reset"
Reset an existing OAR database to the state of the fresh new one.
.IP \fB\-\-check\fR 4
.IX Item "--check"
Check that OAR database is accessible and up to date (schema version).
.SH OPTIONS
.IX Header "OPTIONS"
.SS "General parameters"
.IX Subsection "General parameters"
.IP \fB\-\-conf\fR=\fIOAR_CONF_FILE\fR 4
.IX Item "--conf=OAR_CONF_FILE"
Define the OAR configuration file to use. By default \fI/etc/oar/oar.conf\fR is used. If this file doesn't exist, the default parameters for each value are used.
.IP \fB\-\-update\-conf\fR 4
.IX Item "--update-conf"
The database parameters given in the command line are written to the OAR_CONF_FILE
.IP \fB\-f,\-\-force\-sql\fR 4
.IX Item "-f,--force-sql"
Force to continue the execution even if a SQL command fails
.IP \fB\-y,\-\-force\-yes\fR 4
.IX Item "-y,--force-yes"
Force oar-database to continue without prompt even if it could be harmful.
.SS "Database backend parameters"
.IX Subsection "Database backend parameters"
These parameters are only required by the \fI\-\-create\fR and \fI\-\-drop\fR actions.
.IP \fB\-\-db\-is\-local\fR 4
.IX Item "--db-is-local"
PostgreSQL: use local admin account to execute admin commands. MySQL: use the unix socket connection to execute admin commands.
.IP \fB\-\-db\-admin\-user\fR=\fIDB_ADMIN_USER\fR 4
.IX Item "--db-admin-user=DB_ADMIN_USER"
Set database backend admin username.
.IP \fB\-\-db\-admin\-pass\fR=\fIDB_ADMIN_PASS\fR 4
.IX Item "--db-admin-pass=DB_ADMIN_PASS"
Set database backend admin password.
.SS "OAR database parameters"
.IX Subsection "OAR database parameters"
If not specified, OAR database parameters are taken from \fIOAR_CONF_FILE\fR. Please prefer setting the configurations in that file instead of using these options.
.IP \fB\-\-db\-type\fR=\fIDB_TYPE\fR 4
.IX Item "--db-type=DB_TYPE"
Database backend to use, \fImysql\fR or \fIPg\fR (for PostgreSQL).
.IP \fB\-\-db\-user\fR=\fIDB_USER\fR 4
.IX Item "--db-user=DB_USER"
Set OAR username to access the database. Override the one set in OAR_CONF_FILE.
.IP \fB\-\-db\-pass\fR=\fIDB_PASS\fR 4
.IX Item "--db-pass=DB_PASS"
Set OAR user password to access the database. Override the one set in OAR_CONF_FILE.
.IP \fB\-\-db\-host\fR=\fIDB_HOST\fR 4
.IX Item "--db-host=DB_HOST"
Set the database backend hostname. Override the one set in OAR_CONF_FILE.
.IP \fB\-\-db\-port\fR=\fIDB_PORT\fR 4
.IX Item "--db-port=DB_PORT"
Set the database backend TCP port. Override the one set in OAR_CONF_FILE.
.IP \fB\-\-db\-name\fR=\fIDB_NAME\fR 4
.IX Item "--db-name=DB_NAME"
Set OAR database name. Override the one set in OAR_CONF_FILE.
.IP \fB\-\-db\-ro\-user\fR=\fIDB_RO_USER\fR 4
.IX Item "--db-ro-user=DB_RO_USER"
Set OAR username for read-only access the database. Override the one set in OAR_CONF_FILE.
.IP \fB\-\-db\-ro\-pass\fR=\fIDB_RO_PASS\fR 4
.IX Item "--db-ro-pass=DB_RO_PASS"
Set OAR user password for read-only access the database. Override the one set in OAR_CONF_FILE.
.IP \fB\-d,\-\-debug\fR 4
.IX Item "-d,--debug"
Activate the display of debugging information.
.IP \fB\-h,\-\-help\fR 4
.IX Item "-h,--help"
Display this help.
.SH EXAMPLES
.IX Header "EXAMPLES"
.SS MySQL
.IX Subsection "MySQL"
First you need to specify the database parameters in /etc/oar/oar.conf. These parameters will be used by \fBoar-database\fR.
.PP
To create a new database (assuming that the MySQL root password is \fBPASS\fR):
.PP
\&\fBoar-database \-\-create \-\-db\-admin\-user root \-\-db\-admin\-pass PASS\fR
.PP
Or if the MySQL server is local and accessible using the unix socket:
.PP
\&\fBoar-database \-\-create \-\-db\-is\-local\fR
.PP
To upgrade an existing database:
.PP
\&\fBoar-database \-\-upgrade\fR
.SS PostgreSQL
.IX Subsection "PostgreSQL"
First you need to specify the database parameters in /etc/oar/oar.conf. These parameters will be used by \fBoar-database\fR. If your PostgreSQL database is on the local system, you can use the \fB\-\-db\-is\-local\fR option which will use PostgreSQL unix account (needs root privileges).
.PP
To create a new database:
.PP
\&\fBoar-database \-\-create \-\-db\-is\-local\fR
.PP
To upgrade an existing database:
.PP
\&\fBoar-database \-\-upgrade\fR
.SS "Advanced usages"
.IX Subsection "Advanced usages"
To make some tests or to administrate several databases, you can also specify the sql parameters on the command line. For example:
.PP
\&\fBoar-database \-\-create \-\-db\-type=Pg \-\-db\-host=HOST \e
               \-\-db\-user=oar \-\-db\-pass=PASS \e
               \-\-db\-admin\-user=ADMIN_USER \-\-db\-admin\-pass=ADMIN_PASS\fR
.PP
will create the oar database and the oar user on the postgresql system hosted by \fBHOST\fR. The user \fBADMIN_USER\fR must have the right to create new databases and new roles on this system.
.SH FILES
.IX Header "FILES"
.IP "/usr/lib/oar/database/mysql_structure.sql, /usr/lib/oar/database/pg_structure.sql" 4
.IX Item "/usr/lib/oar/database/mysql_structure.sql, /usr/lib/oar/database/pg_structure.sql"
SQL instructions for creating the structure of the oar database.
.IP "/usr/lib/oar/database/mysql_default_admission_rules.sql, /usr/lib/oar/database/pg_default_admission_rules.sql" 4
.IX Item "/usr/lib/oar/database/mysql_default_admission_rules.sql, /usr/lib/oar/database/pg_default_admission_rules.sql"
SQL instructions for inserting the default admission rules in the oar database.
.IP /usr/lib/oar/database/default_data.sql 4
.IX Item "/usr/lib/oar/database/default_data.sql"
SQL instructions for inserting the default data in the oar database.
.IP "/usr/lib/oar/database/mysql_reset_structure.sql, /usr/lib/oar/database/pg_reset_structure.sql" 4
.IX Item "/usr/lib/oar/database/mysql_reset_structure.sql, /usr/lib/oar/database/pg_reset_structure.sql"
SQL instruction for emptying an existing oar database.
.IP "/usr/lib/oar/database/mysql_structure_upgrade_*.sql, /usr/lib/oar/database/pg_structure_upgrade_*.sql" 4
.IX Item "/usr/lib/oar/database/mysql_structure_upgrade_*.sql, /usr/lib/oar/database/pg_structure_upgrade_*.sql"
SQL instructions for upgrading an existing database.
.SH COPYRIGHTS
.IX Header "COPYRIGHTS"
.Vb 1
\& Copyright 2003\-2018 Laboratoire d\*(AqInformatique 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.
.Ve