ePages 6.17.43 - DE_EPAGES/Database/API/Connection.pm

Package DE_EPAGES::Database::API::Connection

This package provides an interface to make, get and close connections.

@EXPORT_OK
GetCurrentDBHandle
ConnectToSite
ConnectSite
ConnectTestSite
GetTestSite
DisconnectSite
Connect
RunOnStore
RunOnSystem
Transaction
EncryptDBPassword
StoreConnectionDefaults
CreateStoreConf

Functions

Connect
ConnectSite
ConnectTestSite
ConnectToSite
CreateStoreConf
DisconnectSite
EncryptDBPassword
GetCurrentDBHandle
GetTestSite
RunOnStore
RunOnSystem
SetCurrentDBHandle
StoreConnectionDefaults
Transaction

Connect

Connects to any database via the connection string (defined at DBI). Username and password are required. The correct DBI interface will be selected to make connection. Use SetCurrentDBHandle to make the database handle accessible from DAL functions.

Syntax
my $dbh = Connect($DataSource, $Login, $Password, $CacheKey)
Example
my $dbh = Connect('dbi:mysql:admindb', 'admin', 'geheim', 'admindb')
Input
$DataSource (string)
DBI connection string, see "perldoc DBI" for details
$Login (string)
database user name
$Password (string)
database password (optional)
$CacheKey (string)
key to identify the connection
Return
$dbh (object)
database handle

ConnectSite

Connects to any database with config file Database.d/$Store.conf. The password is not required if it is defined in the config file. Throws an error if the connection is not active. This function sets the current database handle to make the database handle accessable from DAL functions.

Syntax
ConnectSite($Store);
ConnectSite($Store, $Password);
Example
ConnectSite('Site');
Input
$Store (string)
store name with database ini file $Store.conf
$Password (string)
database password (optional, default read from $Store.conf)

ConnectTestSite

Connects to the test database (see GetTestSite). The password must be set in Database.d/$TestSite.conf.

Syntax
ConnectTestSite();

ConnectToSite

Connects to site database (section [Site.Default] at Database.d/Site.conf). The password is not required if it is set in the config file.

Syntax
ConnectToSite();
ConnectToSite($Password);
Input
$Password (string)
database password (optional)

CreateStoreConf

creates (unless exists) Shared/Config/Database.d/$hSettings->{Store}.conf

Syntax
CreateStoreConf($hSettings, $hFlags);
Input
$hSettings (ref.hash)
settings (defaults in parenthesis)
  • Store - business unit name (required)
  • Database - store name (\L$hSettings->{Store}\Q)
  • active - is database active? (1)
  • login - user alias (usr_\L$hSettings->{Store}\Q)
  • passwd - user password (epages)
  • encpasswd - encrypted user password ()
  • datasource - datasource (derived from Backup.conf)
  • Backup - connection for creating the database (Backup)
  • BackupHost - backup database on BackupHost ()
  • DumpDir - dumps can be found in DumpDir ()
  • StoreType - store type ()
  • Key - store key ()

$hFlags (ref.hash)
flags
  • connect - if set, dies unless can connect to $hSettings->{Backup}

DisconnectSite

Disconnect current site connection and reset global current database handle site alias.

Syntax
DisconnectSite();

EncryptDBPassword

Crypt the plain password to save it at Database.d/$Store.conf. Enter the crypted password at the Database.d/$Store.conf so that passwords are hidden for users which have file system access.

Syntax
$EncPassword = EncryptDBPassword($Password);
Input
$Password (string)
database password (ini keyword is passwd)
Return
$EncPassword (string)
crypted database password (ini keyword is encpasswd)

GetCurrentDBHandle

Returns the current database handle.

Syntax
$dbh = GetCurrentDBHandle();
Return
$dbh (object)
database handle

GetTestSite

Returns the connection name of the test database. The name can be specified by the EPAGES_TESTSITE environment variable. The default value is 'Site'.

Syntax
my $StoreName = GetTestSite();
Example
RunOnStore( 'Store'=> GetTestSite(), 'Sub' => sub {
    print LoadRootObject()->get('StoreName');
});
Return
$StoreName (string)
database connection name

RunOnStore

Runs the main function in the context of the Error module and enables detailed error information.

Syntax
RunOnStore( %Options );
Example
RunOnStore(
    'Store'=> $Store,
    'DBPassword'=> $DBPassword,
    'Sub' => $Sub,
);
Input
%Options (hash)
parameter
  • Sub - a code reference of the main function - code ref
  • Store - store name - string
  • DBPassword - store password (default read from Database.d/$Store.conf) - string

RunOnSystem

Runs the given sub on the system db. DB password is read from the conf.

Syntax
RunOnSystem($cSub);
Example
RunOnSystem(sub { ... });
Input
$cSub (ref.code)
sub reference (closure)

SetCurrentDBHandle

Sets the current database handle.

Syntax
SetCurrentDBHandle($dbh);
Input
$dbh (object)
database handle

StoreConnectionDefaults

returns a hash of default values for section [Connection] in Database.d/Store.conf depending on $hSettings and (for $hDefault->{datasource}) envvar EPAGES_MYSQL_CONNECTION.

Syntax
$hDefault = StoreConnectionDefaults($hSettings, $hFlags);
Input
$hSettings (ref.hash)
settings
  • Store - business unit name (required)
  • Database - store name
  • Backup - connection for creating the database

$hFlags (ref.hash)
flags
  • connect - if set, dies unless can connect to $hSettings->{Backup}

Return
$hDefault (ref.hash)
settings (defaults in parenthesis)
  • Database - store name (\L$hSettings->{Store}\Q)
  • active - is database active? (1)
  • login - user alias (usr_\L$hSettings->{Store}\Q)
  • passwd - user password (epages)
  • Backup - connection for creating the database (Backup)
  • datasource - datasource (derived from Backup.conf)

Transaction

Runs a code block in a transaction using the current database handle. In this transaction is no cache reset involved.

Syntax
Transaction( $cCode, $cRollback);
Example
Transaction( sub {
    ProcessSql( ... );
    ProcessSql( ... );
} );
Input
$cCode (code reference)
code block
$cRollback (code reference)
roll back code block (optional)