oar-database(8)

📦
version 2.6.1 · 3 versions
, in debian trixie, ubuntu questing

✨ oar-database(8) — the OAR commands glow-up ✨

okay bestie, gather round, because this is the manual page for oar-database, part of the OAR commands family, and it's lowkey the most important little tool in your whole OAR setup. it manages the OAR database. that's it, that's the vibe. 💅

🌸 NAME 🌸

oar-database — manage OAR database.

like. literally what it says. it's the database babysitter. 👑

🎀 SYNOPSIS 🎀

oar-database --create [OPTIONS]

oar-database --drop [OPTIONS]

oar-database --upgrade [OPTIONS]

oar-database --reset [OPTIONS]

oar-database --check [OPTIONS]

five actions, five moods, pick your fighter. 🦋

💖 DESCRIPTION 💖

OAR keeps its persistent data in a database, and that database is either the MySQL backend or the PostgreSQL backend (peep oar.conf to see which one you're rocking). oar-database is the whole reason you exist here — it's the tool that manages that database for you. no cap.

🔥 ACTIONS 🔥

  • --create — create an OAR database: inject the schema and the default data, and create the users/roles. baby's first database. 🍼
  • --drop — drop an existing OAR database and its associated users/roles. it's giving destructive. say goodbye fr fr. 💀
  • --upgrade — upgrade an existing OAR database. glow-up, but for schemas. ✨
  • --reset — reset an existing OAR database back to the state of a fresh new one. factory reset, but make it OAR. 🧚
  • --check — check that the OAR database is accessible and up to date (schema version). the vibe check. 🫶

✨ OPTIONS ✨

💅 General parameters

  • --conf=OAR_CONF_FILE — define the OAR configuration file to use. by default /etc/oar/oar.conf is the one. and if that file doesn't even exist? no stress, the default parameters for each value get used instead. iconic behavior honestly.
  • --update-conf — the database parameters you gave on the command line get written to the OAR_CONF_FILE. so it remembers. main character energy. 🎀
  • -f, --force-sql — force it to keep going even if a SQL command fails. bold. reckless. respect. 😭
  • -y, --force-yes — force oar-database to continue without prompting you, even if it could be harmful. 🚨
⚠️ bestie, that one literally says "even if it could be harmful". it will NOT ask. it will NOT hesitate. know what you're doing before you type it.

🐘 Database backend parameters

these are only required by the --create and --drop actions. iykyk.

  • --db-is-local — for PostgreSQL: use the local admin account to execute admin commands. for MySQL: use the unix socket connection to execute admin commands. local queen. 🏠
  • --db-admin-user=DB_ADMIN_USER — set the database backend admin username.
  • --db-admin-pass=DB_ADMIN_PASS — set the database backend admin password.

💜 OAR database parameters

if you don't specify these, the OAR database parameters get taken from OAR_CONF_FILE. and honestly? please prefer setting your config in that file instead of using these options. do it for me. 🥺

  • --db-type=DB_TYPE — the database backend to use: mysql, or Pg (which is for PostgreSQL).
  • --db-user=DB_USER — set the OAR username used to access the database. overrides the one set in OAR_CONF_FILE.
  • --db-pass=DB_PASS — set the OAR user password used to access the database. overrides the one set in OAR_CONF_FILE.
  • --db-host=DB_HOST — set the database backend hostname. overrides the one set in OAR_CONF_FILE.
  • --db-port=DB_PORT — set the database backend TCP port. overrides the one set in OAR_CONF_FILE.
  • --db-name=DB_NAME — set the OAR database name. overrides the one set in OAR_CONF_FILE.
  • --db-ro-user=DB_RO_USER — set the OAR username for read-only access to the database. overrides the one set in OAR_CONF_FILE.
  • --db-ro-pass=DB_RO_PASS — set the OAR user password for read-only access to the database. overrides the one set in OAR_CONF_FILE.
  • -d, --debug — activate the display of debugging information. we love receipts. 🔍
  • -h, --help — display this help.

🌈 EXAMPLES 🌈

🐬 MySQL

first, you need to specify the database parameters in /etc/oar/oar.conf. these parameters will be used by oar-database.

to create a new database (assuming the MySQL root password is PASS):

oar-database --create --db-admin-user root --db-admin-pass PASS

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

oar-database --create --db-is-local

to upgrade an existing database:

oar-database --upgrade

🐘 PostgreSQL

first, you need to specify the database parameters in /etc/oar/oar.conf. these parameters will be used by oar-database. if your PostgreSQL database is on the local system, you can use the --db-is-local option, which will use the PostgreSQL unix account (needs root privileges, so bring your sudo energy 👑).

to create a new database:

oar-database --create --db-is-local

to upgrade an existing database:

oar-database --upgrade

🚀 Advanced usages

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

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

this will create the oar database and the oar user on the postgresql system hosted by HOST. the user ADMIN_USER must have the right to create new databases and new roles on this system. no shortcuts, no exceptions. ⭐

🍓 FILES 🍓

  • /usr/lib/oar/database/mysql_structure.sql, /usr/lib/oar/database/pg_structure.sql — SQL instructions for creating the structure of the oar database.
  • /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.
  • /usr/lib/oar/database/default_data.sql — SQL instructions for inserting the default data in the oar database.
  • /usr/lib/oar/database/mysql_reset_structure.sql, /usr/lib/oar/database/pg_reset_structure.sql — SQL instruction for emptying an existing oar database.
  • /usr/lib/oar/database/mysql_structure_upgrade_*.sql, /usr/lib/oar/database/pg_structure_upgrade_*.sql — SQL instructions for upgrading an existing database.

👑 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.

and that's the whole page, bestie!! 🫶 this was oar-database from the OAR commands set, dated 2025-03-24, and you can find it again under oar-database(8) whenever you need it. go manage that database, you absolute legend. mwah. 💖✨

📦 where this page comes from