Module reahl.component.dbutils

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

' Copyright 2017, 2018 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)

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()

Connects and logs into the database.

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(yes=False)

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

migrate_db()

Runs the database migrations relevant to the current system.

diff_db()

Computes the changes in schema iwetween 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, yes=False)

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 thexs 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)

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

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.

NullDatabaseControl

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

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