Module reahl.component.dbutils

Utilities to manipulate underlying databases - sometimes via an ORM tool.

' Copyright 2017, 2018, 2022 Reahl Software Services (Pty) Ltd. All rights reserved. @startuml !include ../../../base.iuml title Database components note as N1 Use the system-wide SystemControl to control any database related operations. It keeps an ORMControl for the ORM in use, and a DatabaseControl for the database in use. The ReahlSystemConfig specifies which ORMControl to use and from its connection_uri we deduce which DatabaseControl to use. Subclasses are written for supporting specific ORMs or Database backends. Find the SystemControl from the current ExecutionContext. end note class ExecutionContext class "<b>SystemControl</b>" as SystemControl class Configuration class ReahlSystemConfig class "<b>ORMControl</b>" as ORMControl class "<b>DatabaseControl</b>" as DatabaseControl ExecutionContext -down- SystemControl SystemControl -down- DatabaseControl SystemControl -down- ORMControl Configuration <|-- ReahlSystemConfig ReahlSystemConfig -- ORMControl @enduml

SystemControl

class reahl.component.dbutils.SystemControl(config)

Bases: object

Used to control all aspects relating to the underlying database as per the configuration of the system.

Any Reahl system is assumed to have a database backing it. Our dealings with a databases vary in two dimentions. The first of these dimantions is the different database backends that can be used. How one controls the backend itself (such as creating users, dropping databases, etc) differs depending on the particular backend used.

Regardless of which backend is used, one can also use an ORM layer on top of the database. Things like instrumenting classes, creating database tables of dealing with database transactions are dependent on the ORM implementation used.

The SystemControl allows you to control all these aspects of the database. It does so by delegating methods relating to the database backend to a DatabaseControl of the correct kind, and by delegating the methods relating to ORM operations to an ORMControl of the correct kind.

The type of DatabaseControl used is inferred from the configured reahlsystem.connection_uri in reahl.config.py. The actual ORMControl used is configured as the reahlsystem.orm_control in reahl.config.py.

A programmer should use the SystemControl of the system as programmatic interface to the database without regard for which technology-specific classes it delegates to in order to do its work.

connect(auto_commit=False)

Connects and logs into the database.

property connected

Returns True if the system is currently connected to the database.

disconnect()

Disconnects from the database.

commit()

Commits the database.

rollback()

Rolls back the database.

size_database()

Returns the current size of the database.

create_db_tables()

Creates the underlying database schema.

drop_db_tables()

Removes the underlying database schema.

initialise_database()

Ensures a new clean database exists, with a schema created. This drops an existing database if one is present.

migrate_db(explain=False)

Runs the database migrations relevant to the current system.

diff_db(output_sql=False)

Computes the changes in schema between the current database and what the current system expects.

do_daily_maintenance()

Runs the all the scheduled jobs relevant to the current system.

create_db_user(super_user_name=None, create_with_password=True)

Creates the database user.

drop_db_user(super_user_name=None)

Drops the database user.

drop_database(super_user_name=None)

Drops the database (if it exists).

create_database(super_user_name=None)

Creates the database.

backup_database(directory, super_user_name=None)

Backs up the database.

backup_all_databases(directory, super_user_name=None)

Backs up all databases on the current machine.

restore_database(filename, super_user_name=None)

Restores a databases from the given backup.

restore_all_databases(filename, super_user_name=None)

Restores all databases from the given backup.

DatabaseControl

class reahl.component.dbutils.DatabaseControl(url, config)

Bases: object

An interface to the underlying database backend technology used.

This class has the responsibility to manage the low-level backend operations, such as creating/dropping databases or users.

In order to support a new type of database, subclass this class and implement its methods appropriately for that backend.

Don’t use this class directly, rather call the methods on the SystemControl. It delegates to the appropriate underlying ORMControl and/or DatabaseControl as appropriate.

ORMControl

class reahl.component.dbutils.ORMControl

Bases: object

An interface to higher-level database operations that may be dependent on the ORM technology used.

This class has the responsibility to manage the higher-level backend operations, such as instrumenting persisted classes, creating database schemas, migration, etc.

In order to support a new type of ORM, subclass this class and implement its methods appropriately for that ORM.

Don’t use this class directly, rather call the methods on the SystemControl. It delegates to the appropriate underlying ORMControl and/or DatabaseControl as appropriate.

nested_transaction()

A context manager for code that needs to run in a nested transaction.

Changed in version 5.0: Changed to yield a TransactionVeto which can be used to override when the transaction will be committed or not.

commit()

Commits the current transaction. Programmers should not need to deal with such transaction management explicitly, since the framework already manages transactions itself.

rollback()

Rolls back the current transaction. Programmers should not need to deal with such transaction management explicitly, since the framework already manages transactions itself.

NullDatabaseControl

class reahl.component.dbutils.NullDatabaseControl(url, config)

Bases: DatabaseControl

A stubbed-out DatabaseControl for systems that do not have any database at all.