NAME

       LedgerSMB::Database - Provides the APIs for database creation and management.

SYNOPSIS

       This module provides the APIs for database creation and management

COPYRIGHT

       This module is copyright (C) 2007, the LedgerSMB Core Team and subject to the GNU General
       Public License (GPL) version 2, or at your option, any later version.  See the COPYRIGHT
       and LICENSE files for more information.

METHODS

       LedgerSMB::Database->new({dbname = $dbname, countrycode = $cc, chart_name = $name,
       company_name = $company, username = $username, password = $password})
           This function creates a new database management object with the specified
           characteristics.  The $dbname is the name of the database. the countrycode is the two-
           letter ISO code.  The company name is the friendly name for dropdown boxes on the
           Login screen.

           As some countries may have multiple available charts, you can also specify a chart
           name as well.

           Note that the arguments can be any hashref. If it is a LedgerSMB object, however, it
           will attempt to copy all attributes beginning with _ into the current object (_user,
           _locale, etc).

       base_backup
           This routine connects to the database using pg_dumpall and returns a plain text,
           roles-only dump of the current database cluster.  This is left uncompressed for
           readability and ease of troubleshooting.  Base backups are advised to be taken
           frequently and in conjunction with single database backups.  The single database
           backups will backup all data but no roles.  Restoring a new database onto a new server
           post-crash with only the single-database backup thus means recreating all users.

           The file is named roles_[date].sql by default where the date is in yyyy-mm-dd format.

           It returns the full path of the resulting backup file on success, or undef on failure.

       db_backup()
           This routine connects to the database using pg_dump and creates a Pg-native database
           backup of the selected db only.  There is some redundancy with the base backup but the
           overlap is minimal.  You can restore your database and data with the db_bakup, but not
           the users and roles.  You can restore the users and roles with the base_backup but not
           your database.

           The resulting file is named backup_[dbname]_[date].bak with the date in yyyy-mm-dd
           format.

           It returns the full path of the resulting backup file on success, or undef on failure.

       get_info()
           This routine connects to the database using DBI and attempts to determine if a related
           application is running in that database and if so what version.  It returns a hashref
           with the following keys set:

           username Set to the user of the current connection
           appname Set to the current application name, one of:
               ledgersmb
               sql-ledger
               undef
           version The current version of the application.  One of:
               legacy SQL-Ledger 2.6 and below, and LedgerSMB 1.1 and below
               1.2 (LedgerSMB only)
               1.3 (LedgerSMB only)
               1.3dev (LedgerSMB only)
               2.7 (SQL-Ledger only)
               2.8 (SQL-Ledger only)
               full_version The full version number of the database version
               status Current status of the db.  One of:
               exists The database was confirmed to exist
               does not exist The database was confirmed to not exist
               undef The database could not be confirmed to exist, or not

           It is worth noting that this is designed to be informative and helpful in determining
           whether automatic upgrades can in fact occur or other administrative tasks can be run.
           Sample output might be:

           {    appname => undef,
                version => undef, full_version => undef,
                 status => 'does not exist'}

           or

           {    appname => 'sql-ledger',
                version => '2.8', full_version => '2.8.33',
                 status => 'exists'}

           or

           {   appname => 'ledgersmb',
               version => '1.2' fullversion => '1.2.0',
                status => 'exists' }

           It goes without saying that status will always equal 'exists' if appname is set.
           However the converse is not true.  If the status is 'exists' and appname is not set,
           this merely means that the database exists but is not used by a recognized
           application.  So administrative functions are advised to check both the appname and
           status values.

           Finally, it is important to note that LedgerSMB 1.1 and prior, and SQL-Ledger 2.6.x
           and prior are lumped under appname => 'ledgersmb' and version => 'legacy', though the
           fullversion may give you an idea of what the actual version is run.

       $db->server_version();
           Connects to the server and returns the version number in x.y.z format.

       $db->create();
           Creates a database and loads the contrib files.  This is done from template0, meaning
           nothing added to template1 will be found in this database.  This was necessary as a
           workaround for issues on some Debian systems.

           Returns true if successful, false of not.  Creates a log called dblog in the temporary
           directory with all the output from the psql files.

           In DEBUG mode, will show all lines to STDERR.  In ERROR logging mode, will display
           only those lines containing the word ERROR.

       $db->load_modules($loadorder)
           Loads or reloads sql modules from $loadorder

       $db->exec_script({script => 'path/to/file', logfile => 'path/to/log'})
           Executes the script.  Returns 0 if successful, 1 if there are errors suggesting that
           types are already created, and 2 if there are other errors.

       $db->create_and_load();
           Creates a database and then loads it.

       $db->process_roles($rolefile);
           Loads database Roles templates.

       $db->log_from_logfile();
           Process log file and log relevant pieces via the log classes.