# Database operations

## Supported databases

Rucio uses SQLAlchemy as the object-relational mapper between Python and SQL. Rucio is extensively tested against SQLite, MySQL/MariaDB, PostgreSQL, and Oracle and should work with them out of the box. The appropriate connection string has to be set in the `etc/rucio.cfg`, for example:

Oracle: `oracle://rucio:rucio@(DESCRIPTION=(ADDRESS=(PROTOCOL=TCP)(HOST=localhost)(PORT=10121))(ENABLE=BROKEN)(CONNECT_DATA=(SERVICE_NAME=localhost)))`

MySQL/MariaDB: `mysql://rucio:rucio@localhost/rucio`

PostgreSQL: `postgresql://rucio:rucio@localhost:6601/rucio`

SQLite: `sqlite:////tmp/rucio.db`

Please ensure correct UNIX permissions on the SQLite file, such that the webserver process can read and write to it.

## Upgrading and downgrading the database schema

Rucio uses Alembic as a database migration tool, which works hand-in-hand with SQLAlchemy. Ensure that the `alembic.ini` is set to the same database string as the `etc/rucio.cfg` and issue the following command to upgrade the schema:

`alembic upgrade head`

In case of problems, you can always downgrade back with

`alembic downgrade head`

If you just want to output the SQL statements of the upgrade operation, without actually applying them automatically, issue the following command:

`alembic upgrade head --sql`

Notabene, schema upgrades are reserved for feature releases and will not happen with patch releases.

## Creating a new version as a developer

If you want to create an upgrade path for the schema, you need to generate a schema upgrade+downgrade file:

`alembic revision -m 'schema change message'`

This will output the name of the file that has been generated with two functions `def upgrade()` and `def downgrade()` that need to be implemented. These should reflect the changes to the `lib/rucio/db/sqla/models.py` SQLAlchemy mapping.