.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "LedgerSMB::Database 3pm"
.TH LedgerSMB::Database 3pm "2014-06-10" "perl v5.18.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
LedgerSMB::Database \- Provides the APIs for database creation and management.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
This module provides the APIs for database creation and management
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
This module is copyright (C) 2007, the LedgerSMB Core Team and subject to 
the \s-1GNU\s0 General Public License (\s-1GPL\s0) version 2, or at your option, any later
version.  See the \s-1COPYRIGHT\s0 and \s-1LICENSE\s0 files for more information.
.SH "METHODS"
.IX Header "METHODS"
.ie n .IP "LedgerSMB::Database\->new({dbname = $dbname, countrycode = $cc, chart_name = $name, company_name = $company, username = $username, password = $password})" 4
.el .IP "LedgerSMB::Database\->new({dbname = \f(CW$dbname\fR, countrycode = \f(CW$cc\fR, chart_name = \f(CW$name\fR, company_name = \f(CW$company\fR, username = \f(CW$username\fR, password = \f(CW$password\fR})" 4
.IX Item "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 \f(CW$dbname\fR is the name of the database. the countrycode
is the two-letter \s-1ISO\s0 code.  The company name is the friendly name for 
dropdown boxes on the Login screen.
.Sp
As some countries may have multiple available charts, you can also specify
a chart name as well.
.Sp
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).
.IP "base_backup" 4
.IX Item "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.
.Sp
The file is named roles_[date].sql by default where the date is in
yyyy-mm-dd format.
.Sp
It returns the full path of the resulting backup file on success, or undef on 
failure.
.IP "\fIdb_backup()\fR" 4
.IX Item "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.
.Sp
The resulting file is named backup_[dbname]_[date].bak with the date in
yyyy-mm-dd format.
.Sp
It returns the full path of the resulting backup file on success, or undef on 
failure.
.IP "\fIget_info()\fR" 4
.IX Item "get_info()"
This routine connects to the database using \s-1DBI\s0 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:
.RS 4
.IP "username" 4
.IX Item "username"
Set to the user of the current connection
.IP "appname" 4
.IX Item "appname"
Set to the current application name, one of:
.RS 4
.IP "ledgersmb" 4
.IX Item "ledgersmb"
.PD 0
.IP "sql-ledger" 4
.IX Item "sql-ledger"
.IP "undef" 4
.IX Item "undef"
.RE
.RS 4
.RE
.IP "version" 4
.IX Item "version"
.PD
The current version of the application.  One of:
.RS 4
.IP "legacy" 4
.IX Item "legacy"
SQL-Ledger 2.6 and below, and LedgerSMB 1.1 and below
.IP "1.2 (LedgerSMB only)" 4
.IX Item "1.2 (LedgerSMB only)"
.PD 0
.IP "1.3 (LedgerSMB only)" 4
.IX Item "1.3 (LedgerSMB only)"
.IP "1.3dev (LedgerSMB only)" 4
.IX Item "1.3dev (LedgerSMB only)"
.IP "2.7 (SQL-Ledger only)" 4
.IX Item "2.7 (SQL-Ledger only)"
.IP "2.8 (SQL-Ledger only)" 4
.IX Item "2.8 (SQL-Ledger only)"
.RE
.RS 4
.IP "full_version" 4
.IX Item "full_version"
.PD
The full version number of the database version
.IP "status" 4
.IX Item "status"
Current status of the db.  One of:
.IP "exists" 4
.IX Item "exists"
The database was confirmed to exist
.IP "does not exist" 4
.IX Item "does not exist"
The database was confirmed to not exist
.IP "undef" 4
.IX Item "undef"
The database could not be confirmed to exist, or not
.RE
.RS 4
.RE
.RE
.RS 4
.Sp
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:
.Sp
{    appname => undef, 
     version => undef, 
full_version => undef,
      status => 'does not exist'}
.Sp
or
.Sp
{    appname => 'sql\-ledger',
     version => '2.8',
full_version => '2.8.33',
      status => 'exists'}
.Sp
or
.Sp
{   appname => 'ledgersmb',
    version => '1.2'
fullversion => '1.2.0',
     status => 'exists' }
.Sp
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.
.Sp
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.
.RE
.ie n .IP "$db\->\fIserver_version()\fR;" 4
.el .IP "\f(CW$db\fR\->\fIserver_version()\fR;" 4
.IX Item "$db->server_version();"
Connects to the server and returns the version number in x.y.z format.
.ie n .IP "$db\->\fIlist()\fR" 4
.el .IP "\f(CW$db\fR\->\fIlist()\fR" 4
.IX Item "$db->list()"
Lists available databases except for those named \*(L"postgres\*(R" or starting with
\&\*(L"template\*(R"
.Sp
Returns a list of strings of db names.
.ie n .IP "$db\->\fIcreate()\fR;" 4
.el .IP "\f(CW$db\fR\->\fIcreate()\fR;" 4
.IX Item "$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.
.Sp
Returns true if successful, false of not.  Creates a log called dblog in the 
temporary directory with all the output from the psql files.
.Sp
In \s-1DEBUG\s0 mode, will show all lines to \s-1STDERR. \s0 In \s-1ERROR\s0 logging mode, will 
display only those lines containing the word \s-1ERROR.\s0
.ie n .IP "$db\->copy('new_name')" 4
.el .IP "\f(CW$db\fR\->copy('new_name')" 4
.IX Item "$db->copy('new_name')"
Copies the existing database to a new name.
.ie n .IP "$db\->load_modules($loadorder)" 4
.el .IP "\f(CW$db\fR\->load_modules($loadorder)" 4
.IX Item "$db->load_modules($loadorder)"
Loads or reloads sql modules from \f(CW$loadorder\fR
.ie n .IP "$db\->exec_script({script => 'path/to/file', logfile => 'path/to/log'})" 4
.el .IP "\f(CW$db\fR\->exec_script({script => 'path/to/file', logfile => 'path/to/log'})" 4
.IX Item "$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.
.ie n .IP "$db\->\fIcreate_and_load()\fR;" 4
.el .IP "\f(CW$db\fR\->\fIcreate_and_load()\fR;" 4
.IX Item "$db->create_and_load();"
Creates a database and then loads it.
.ie n .IP "$db\->process_roles($rolefile);" 4
.el .IP "\f(CW$db\fR\->process_roles($rolefile);" 4
.IX Item "$db->process_roles($rolefile);"
Loads database Roles templates.
.ie n .IP "$db\->\fIlsmb_info()\fR" 4
.el .IP "\f(CW$db\fR\->\fIlsmb_info()\fR" 4
.IX Item "$db->lsmb_info()"
This routine retrieves general stats about the database and returns the output
as a hashref with the following key/value pairs:
.RS 4
.IP "ar_rows" 4
.IX Item "ar_rows"
.PD 0
.IP "ap_rows" 4
.IX Item "ap_rows"
.IP "gl_rows" 4
.IX Item "gl_rows"
.IP "acc_trans_rows" 4
.IX Item "acc_trans_rows"
.IP "eca_rows" 4
.IX Item "eca_rows"
.IP "oe_rows" 4
.IX Item "oe_rows"
.IP "transactions_rows" 4
.IX Item "transactions_rows"
.IP "users_rows" 4
.IX Item "users_rows"
.RE
.RS 4
.RE
.ie n .IP "$db\->\fIdb_tests()\fR" 4
.el .IP "\f(CW$db\fR\->\fIdb_tests()\fR" 4
.IX Item "$db->db_tests()"
.PD
This routine runs general db tests.
.Sp
\&\s-1TODO\s0