Setup Parameters¶

All parameters starting with an '!' are only recognized at setup time. If you specify them in later function calls they will be ignored. You can also preset these parameters with the TableAttr method of DBIx::Database. This allows you to presetup most parameters for the whole database and they will be use every time you create a new DBIx::Recordset object, without specifying it every time.

!DataSource

Specifies the database to which to connect. This information can be given in the following ways:

!Table

Tablename. Multiple tables are comma-separated.

!Username

Username. Same as the second parameter to the DBI connect function.

!Password

Password. Same as the third parameter to the DBI connect function.

!DBIAttr

Reference to a hash which holds the attributes for the DBI connect function. See perldoc DBI for a detailed description.

!Fields

Fields which should be returned by a query. If you have specified multiple tables the fieldnames should be unique. If the names are not unique you must specify them along with the tablename (e.g. tab1.field).

NOTE 1: Fieldnames specified with !Fields can't be overridden. If you plan to use other fields with this object later, use $Fields instead.

NOTE 2: The keys for the returned hash normally don't have a table part. Only the fieldname part forms the key. (See !LongNames for an exception.)

NOTE 3: Because the query result is returned in a hash, there can only be one out of multiple fields with the same name fetched at once. If you specify multiple fields with the same name, only one is returned from a query. Which one this actually is depends on the DBD driver. (See !LongNames for an exception.)

NOTE 4: Some databases (e.g. mSQL) require you to always qualify a fieldname with a tablename if more than one table is accessed in one query.

!TableFilter

The TableFilter parameter specifies which tables should be honoured when DBIx::Recordset searches for links between tables (see below). When given as parameter to DBIx::Database it filters for which tables DBIx::Database retrieves metadata. Only thoses tables are used which starts with prefix given by "!TableFilter". Also the DBIx::Recordset link detection tries to use this value as a prefix of table names, so you can leave out this prefix when you write a fieldname that should be detected as a link to another table.

!LongNames

When set to 1, the keys of the hash returned for each record not only consist of the fieldnames, but are built in the form table.field.

!Order

Fields which should be used for ordering any query. If you have specified multiple tables the fieldnames should be unique. If the names are not unique you must specify them among with the tablename (e.g. tab1.field).

NOTE 1: Fieldnames specified with !Order can't be overridden. If you plan to use other fields with this object later, use $order instead.

!TabRelation

Condition which describes the relation between the given tables (e.g. tab1.id = tab2.id) (See also !TabJoin.)

  Example
  '!Table'       => 'tab1, tab2',
  '!TabRelation' => 'tab1.id=tab2.id',
  'name'         => 'foo'
  This will generate the following SQL statement:
  SELECT * FROM tab1, tab2 WHERE name = 'foo' and tab1.id=tab2.id ;
    

!TabJoin

!TabJoin allows you to specify an INNER/RIGHT/LEFT JOIN which is used in a SELECT statement. (See also !TabRelation.)

  Example
  '!Table'   => 'tab1, tab2',
  '!TabJoin' => 'tab1 LEFT JOIN tab2 ON (tab1.id=tab2.id)',
  'name'     => 'foo'
  This will generate the following SQL statement:
  SELECT * FROM tab1 LEFT JOIN tab2 ON  (tab1.id=tab2.id) WHERE name = 
'foo' ;
    

!PrimKey

Name of the primary key. When this key appears in a WHERE parameter list (see below), DBIx::Recordset will ignore all other keys in the list, speeding up WHERE expression preparation and execution. Note that this key does NOT have to correspond to a field tagged as PRIMARY KEY in a CREATE TABLE statement.

!Serial

Name of the primary key. In contrast to "!PrimKey" this field is treated as an autoincrement field. If the database does not support autoincrement fields, but sequences the field is set to the next value of a sequence (see "!Sequence" and "!SeqClass") upon each insert. If a "!SeqClass" is given the values are always retrived from the sequence class regardless if the DBMS supports autoincrement or not. The value from this field from the last insert could be retrieved by the function "LastSerial".

!Sequence

Name of the sequence to use for this table when inserting a new record and "!Serial" is defind. Defaults to <tablename>_seq.

!SeqClass

Name and Parameter for a class that can generate unique sequence values. This is a string that holds comma separated values. The first value is the class name and the following parameters are given to the new constructor. See also DBIx::Recordset::FileSeq and DBIx::Recordset::DBSeq.

Example: '!SeqClass' => 'DBIx::Recordset::FileSeq, /tmp/seq'

!WriteMode

!WriteMode specifies which write operations to the database are allowed and which are disabled. You may want to set !WriteMode to zero if you only need to query data, to avoid accidentally changing the content of the database.

NOTE: The !WriteMode only works for the DBIx::Recordset methods. If you disable !WriteMode, it is still possible to use do to send normal SQL statements to the database engine to write/delete any data.

!WriteMode consists of some flags, which may be added together:

!StoreAll

If present, this will cause DBIx::Recordset to store all rows which will be fetched between consecutive accesses, so it's possible to access data in a random order. (e.g. row 5, 2, 7, 1 etc.) If not specified, rows will only be fetched into memory if requested, which means that you will have to access rows in ascending order. (e.g. 1,2,3 if you try 3,2,4 you will get an undef for row 2 while 3 and 4 is ok) see also DATA ACCESS below.

!HashAsRowKey

By default, the hash returned by the setup function is tied to the current record. You can use it to access the fields of the current record. If you set this parameter to true, the hash will by tied to the whole database. This means that the key of the hash will be used as the primary key in the table to select one row. (This parameter only has an effect on functions which return a typglob.)

!IgnoreEmpty

This parameter defines how empty and undefined values are handled. The values 1 and 2 may be helpful when using DBIx::Recordset inside a CGI script, because browsers send empty formfields as empty strings.

!Filter

Filters can be used to pre/post-process the data which is read from/written to the database. The !Filter parameter takes a hash reference which contains the filter functions. If the key is numeric, it is treated as a type value and the filter is applied to all fields of that type. If the key if alphanumeric, the filter is applied to the named field. Every filter description consists of an array with at least two elements. The first element must contain the input function, and the second element must contain the output function. Either may be undef, if only one of them are necessary. The data is passed to the input function before it is written to the database. The input function must return the value in the correct format for the database. The output function is applied to data read from the database before it is returned to the user.

 Example:
     '!Filter'   => 
        {
        DBI::SQL_DATE     => 
            [ 
                sub { shift =~ /(\d\d)\.(\d\d)\.(\d\d)/ ; "19$3$2$1"},
                sub { shift =~ /\d\d(\d\d)(\d\d)(\d\d)/ ; "$3.$2.$1"}
            ],
        'datefield' =>
            [ 
                sub { shift =~ /(\d\d)\.(\d\d)\.(\d\d)/ ; "19$3$2$1"},
                sub { shift =~ /\d\d(\d\d)(\d\d)(\d\d)/ ; "$3.$2.$1"}
            ],
        }
    

Both filters convert a date in the format dd.mm.yy to the database format 19yymmdd and vice versa. The first one does this for all fields of the type SQL_DATE, the second one does this for the fields with the name datefield.

The !Filter parameter can also be passed to the function TableAttr of the DBIx::Database object. In this case it applies to all DBIx::Recordset objects which use these tables.

A third parameter can be optionally specified. It could be set to "DBIx::Recordset::rqINSERT", "DBIx::Recordset::rqUPDATE", or the sum of both. If set, the InputFunction (which is called during UPDATE or INSERT) is always called for this field in updates and/or inserts depending on the value. If there is no data specified for this field as an argument to a function which causes an UPDATE/INSERT, the InputFunction is called with an argument of undef.

During UPDATE and INSERT the input function gets either the string 'insert' or 'update' passed as second parameter.

!LinkName

This allows you to get a clear text description of a linked table, instead of (or in addition to) the !LinkField. For example, if you have a record with all your bills, and each record contains a customer number, setting !LinkName DBIx::Recordset can automatically retrieve the name of the customer instead of (or in addition to) the bill record itself.

!Links

This parameter can be used to link multiple tables together. It takes a reference to a hash, which has - as keys, names for a special "linkfield" and - as value, a parameter hash. The parameter hash can contain all the Setup parameters. The setup parameters are taken to construct a new recordset object to access the linked table. If !DataSource is omitted (as it normally should be), the same DataSource (and database handle), as the main object is taken. There are special parameters which can only occur in a link definition (see next paragraph). For a detailed description of how links are handled, see WORKING WITH MULTIPLE TABLES below.

Link Parameters¶

!MainField

The !MailField parameter holds a fieldname which is used to retrieve a key value for the search in the linked table from the main table. If omitted, it is set to the same value as !LinkedField.

!LinkedField

The fieldname which holds the key value in the linked table. If omitted, it is set to the same value as !MainField.

!NameField

This specifies the field or fields which will be used as a "name" for the destination table. It may be a string or a reference to an array of strings. For example, if you link to an address table, you may specify the field "nickname" as the name field for that table, or you may use ['name', 'street', 'city'].

Look at !LinkName for more information.

!DoOnConnect

You can give an SQL Statement (or an array reference of SQL statements), that will be executed every time, just after an connect to the db. As third possibilty you can give an hash reference. After every successful connect, DBIx::Recordset excutes the statements, in the element which corresponds to the name of the driver. '*' is executed for all drivers.

!Default

Specifies default values for new rows that are inserted via hash or array access. The Insert method ignores this parameter.

!TieRow

Setting this parameter to zero will cause DBIx::Recordset to not tie the returned rows to an DBIx::Recordset::Row object and instead returns an simple hash. The benefit of this is that it will speed up things, but you aren't able to write to such an row, nor can you use the link feature with such a row.

!Debug

Set the debug level. See DEBUGGING.

!PreFetch

Only for tieing a hash! Gives an where expression (either as string or as hashref) that is used to prefetch records from that database. All following accesses to the tied hash only access this prefetched data and don't execute any database queries. See "!Expires" how to force a refetch. Giving a '*' as value to "!PreFetch" fetches the whole table into memory.

 The following example prefetches all record with id < 7:
 tie %dbhash, 'DBIx::Recordset::Hash', {'!DataSource'   =>  $DSN,
                                        '!Username'     =>  $User,
                                        '!Password'     =>  $Password,
                                        '!Table'        =>  'foo',
                                        '!PreFetch'     =>  {
                                                             '*id' => '<',
                                                             'id' => 7
                                                            },
                                        '!PrimKey'      =>  'id'} ;
 The following example prefetches all records:
 tie %dbhash, 'DBIx::Recordset::Hash', {'!DataSource'   =>  $DSN,
                                        '!Username'     =>  $User,
                                        '!Password'     =>  $Password,
                                        '!Table'        =>  'bar',
                                        '!PreFetch'     =>  '*',
                                        '!PrimKey'      =>  'id'} ;
    

!Expires

Only for tieing a hash! If the values is numeric, the prefetched data will be refetched is it is older then the given number of seconds. If the values is a CODEREF the function is called and the data is refetched is the function returns true.

!MergeFunc

Only for tieing a hash! Gives an reference to an function that is called when more then one record for a given hash key is found to merge the records into one. The function receives a reference to both records a arguments. If more the two records are found, the function is called again for each following record, which is already merged data as first parameter.

 The following example sets up a hash, that, when more then one record with the same id is
 found, the field C<sum> is added and the first record is returned, where the C<sum> field
 contains the sum of B<all> found records:
 tie %dbhash, 'DBIx::Recordset::Hash', {'!DataSource'   =>  $DSN,
                                        '!Username'     =>  $User,
                                        '!Password'     =>  $Password,
                                        '!Table'        =>  'bar',
                                        '!MergeFunc'    =>  sub { my ($a, $b) = @_ ; $a->{sum} += $b->{sum} ; },
                                        '!PrimKey'      =>  'id'} ;
    

Where Parameters¶

The following parameters are used to build an SQL WHERE expression

$where

Give an SQL WHERE expression literaly. If $where is specified, all other where parameters described below are ignored. The only expection is $values which can be used to give the values to bind to the placeholders in $where

$values

Values which should be bound to the placeholders given in $where.

 Example:
 *set = DBIx::Recordset -> Search ({'!DataSource' => 'dbi:Oracle:....',
                                    '!Table'      => 'users',
                                    '$where'      => 'name = ? and age > ?',
                                    '$values'     => ['richter', 25] }) ;
    

NOTE: Filters defined with "!Filter" are not applied to these values, because DBIx::Recordset has no chance to know with values belongs to which field.

{fieldname}

Value for field. The value will be quoted automatically, if necessary. The value can also be an array ref in which case the values are put together with the operator passed via $valueconj (default: or)

  Example:
  'name' => [ 'mouse', 'cat'] will expand to name='mouse' or name='cat'
    

'{fieldname}

Value for field. The value will always be quoted. This is only necessary if DBIx::Recordset cannot determine the correct type for a field.

#{fieldname}

Value for field. The value will never be quoted, but will converted a to number. This is only necessary if DBIx::Recordset cannot determine the correct type for a field.

\{fieldname}

Value for field. The value will not be converted in any way, i.e. you have to quote it before supplying it to DBIx::Recordset if necessary.

+{fieldname}|{fieldname}..

Values for multiple fields. The value must be in one/all fields depending on $compconj
Example:
'+name|text' => 'abc' will expand to name='abc' or text='abc'

$compconj

'or' or 'and' (default is 'or'). Specifies the conjunction between multiple fields. (see above)

$valuesplit

Regular expression for splitting a field value in multiple values (default is '\t') The conjunction for multiple values could be specified with $valueconj. By default, only one of the values must match the field.

 Example:
 'name' => "mouse\tcat" will expand to name='mouse' or name='cat'
 NOTE: The above example can also be written as 'name' => [ 'mouse', 'cat']
    

$valueconj

'or' or 'and' (default is 'or'). Specifies the conjunction for multiple values.

$conj

'or' or 'and' (default is 'and') conjunction between fields

$operator

Default operator if not otherwise specified for a field. (default is '=')

*{fieldname}

Operator for the named field

 Example:
 'value' => 9, '*value' => '>' expand to value > 9
    

Could also be an array ref, so you can pass different operators for the values. This is mainly handy when you need to select a range

  Example:
    $set -> Search  ({id          => [5,    7   ],
                     '*id'        => ['>=', '<='],
                     '$valueconj' => 'and'})  ;
  This will expanded to "id >= 5 and id <= 7"
    

NOTE: To get a range you need to specify the $valueconj parameter as "and" because it defaults to "or".

$expr

$expr can be used to group parts of the where expression for proper priority. To specify more the one sub expression, add a numerical index to $expr (e.g. $expr1, $expr2)

  Example:
    $set -> Search  ({id          => 5,
                     '$expr'      => 
                        {
                        'name'  => 'Richter',
                        'country' => 'de',
                        '$conj'   => 'or'
                        }
                      }) ;
    This will expand to
        (name = 'Richter' or country = 'de') and id = 5
    

Search parameters¶

$start

First row to fetch. The row specified here will appear as index 0 in the data array.

$max

Maximum number of rows to fetch. Every attempt to fetch more rows than specified here will return undef, even if the select returns more rows.

$next

Add the number supplied with $max to $start. This is intended to implement a next button.

$prev

Subtract the number supplied with $max from $start. This is intended to implement a previous button.

$order

Fieldname(s) for ordering (ORDER BY) (must be comma-separated, could also contain USING)

$group

Fieldname(s) for grouping (GROUP BY) (must be comma-separated, could also contain HAVING).

$append

String which is appended to the end of a SELECT statement, can contain any data.

$fields

Fields which should be returned by a query. If you have specified multiple tables the fieldnames should be unique. If the names are not unique you must specify them along with the tablename (e.g. tab1.field).

NOTE 1: If !fields is supplied at setup time, this can not be overridden by $fields.

NOTE 2: The keys for the returned hash normally don't have a table part. Only the fieldname part forms the key. (See !LongNames for an exception.)

NOTE 3: Because the query result is returned in a hash, there can only be one out of multiple fields with the same name fetched at once. If you specify multiple fields with same name, only one is returned from a query. Which one this actually is, depends on the DBD driver. (See !LongNames for an exception.)

$primkey

Name of primary key. DBIx::Recordset assumes that if specified, this is a unique key to the given table(s). DBIx::Recordset can not verify this. You are responsible for specifying the right key. If such a primary exists in your table, you should specify it here, because it helps DBIx::Recordset optimize the building of WHERE expressions.

See also !PrimKey

Execute parameters¶

The following parameters specify which action is to be executed:

=search

search data

=update

update record(s)

=insert

insert record

=delete

delete record(s)

=empty

setup empty object

Joins¶

First, you can specify more than one table to the !Table parameter. If you do so, you need to specify how both tables are related. You do this with !TabRelation parameter. This method will access all the specified tables simultanously.

Join Example:¶

If you have the following two tables, where the field street_id is a pointer to the table street:

  table name
  name      char (30),
  street_id  integer
  table street
  id        integer,
  street    char (30),
  city      char (30)

You can perform the following search:

  *set = DBIx::Recordset -> Search ({'!DataSource' => 'dbi:drv:db',
                     '!Table'      => 'name, street',
                     '!TabRelation'=> 'name.street_id = street.id'}) ;

The result is that you get a set which contains the fields name, street_id, street, city and id, where id is always equal to street_id. If there are multiple streets for one name, you will get as many records for that name as there are streets present for it. For this reason, this approach works best when you have a 1:1 relation.

It is also possible to specify JOINs. Here's how:

  *set = DBIx::Recordset -> Search ({
            '!DataSource' => 'dbi:drv:db',
            '!Table'   => 'name, street',
            '!TabJoin' => 'name LEFT JOIN street ON (name.street_id=street.id)'}) ;

The difference between this and the first example is that this version also returns a record even if neither table contains a record for the given id. The way it's done depends on the JOIN you are given (LEFT/RIGHT/INNER) (see your SQL documentation for details about JOINs).

Links¶

If you have 1:n relations between two tables, the following may be a better way to handle it:

  *set = DBIx::Recordset -> Search ({'!DataSource' => 'dbi:drv:db',
                     '!Table'      => 'name',
                     '!Links'      => {
                        '-street'  => {
                            '!Table' => 'street',
                            '!LinkedField' => 'id',
                            '!MainField'   => 'street_id'
                            }
                        }
                    }) ;

After that query, every record will contain the fields name and street_id. Additionally, there is a pseudofield named -street, which could be used to access another recordset object, which is the result of a query where street_id = id. Use

  $set{name} to access the name field
  $set{-street}{street} to access the first street (as long as the
                                    current record of the subobject isn't
                                    modified)
  $set{-street}[0]{street}      first street
  $set{-street}[1]{street}      second street
  $set{-street}[2]{street}      third street
  $set[2]{-street}[1]{street} to access the second street of the
                                    third name

You can have multiple linked tables in one recordset; you can also nest linked tables or link a table to itself.

NOTE: If you select only some fields and not all, the field which is specified by '!MainField' must be also given in the '!Fields' or '$fields' parameter.

NOTE: See also Automatic detection of links below

LinkName¶

In the LinkName feature you may specify a "name" for every table. A name is one or more fields which gives a human readable "key" of that record. For example in the above example id is the key of the record, but the human readable form is street.

  *set = DBIx::Recordset -> Search ({'!DataSource' => 'dbi:drv:db',
                     '!Table'      => 'name',
                     '!LinkName'   => 1,
                     '!Links'      => {
                        '-street'  => {
                            '!Table' => 'street',
                            '!LinkedField' => 'id',
                            '!MainField'   => 'street_id',
                            '!NameField'   => 'street'
                            }
                        }
                    }) ;

For every record in the table, this example will return the fields:

  name  street_id  street

If you have more complex records, you may also specify more than one field in !NameField and pass it as an reference to an array e.g. ['street', 'city']. In this case, the result will contain

  name  street_id  street  city

If you set !LinkName to 2, the result will contain the fields

  name  street_id  STREET_ID

where STREET_ID contains the values of the street and city fields joined together. If you set !LinkName to 3, you will get only

  name  street_id

where street_id contains the values of the street and city fields joined together.

NOTE: The !NameField can also be specified as a table attribute with the function TableAttr. In this case you don't need to specify it in every link. When a !NameField is given in a link description, it overrides the table attribute.

Automatic detection of links¶

DBIx::Recordset and DBIx::Database will try to automatically detect links between tables based on the field and table names. For this feature to work, the field which points to another table must consist of the table name and the field name of the destination joined together with an underscore (as in the above example name.street_id). Then it will automatically recognized as a pointer to street.id.

  *set = DBIx::Recordset -> Search ({'!DataSource' => 'dbi:drv:db',
                                     '!Table'      => 'name') ;

is enough. DBIx::Recordset will automatically add the !Links attribute. Additionally, DBIx::Recordset adds a backlink (which starts with a star ('*')), so for the table street, in our above example, there will be a link, named *name, which is a pointer from table street to all records in the table name where street.id is equal to name.street_id.

You may use the !Links attribute to specify links which can not be automatically detected.

NOTE: To specify more then one link from one table to another table, you may prefix the field name with an specifier followed by two underscores. Example: first__street_id, second__street_id. The link (and backlink) names are named with the prefix, e.g. -first__street and the backlink *first__name.

new ($data_source, $username, $password, \%attr, $saveas, $keepopen)¶

$data_source

Specifies the database to which to connect. Driver/DB/Host. Same as the first parameter to the DBI connect function.

$username

Username (optional)

$password

Password (optional)

\%attr

Attributes (optional) Same as the attribute parameter to the DBI connect function.

$saveas

Name for this DBIx::Database object to save as. The name can be used in DBIx::Database::Get, or as !DataSource parameter in call to the DBIx::Recordset object.

This is intended as mechanism to retrieve the necessary metadata; for example, when your web server starts (e.g. in the startup.pl file of mod_perl). Here you can give the database object a name. Later in your mod_perl or Embperl scripts, you can use this metadata by specifying this name. This will speed up the setup of DBIx::Recordset object without the need to pass a reference to the DBIx::Database object.

$keepopen

Normaly the database connection will be closed after the metadata has been retrieved from the database. This makes sure you don't get trouble when using the new method in a mod_perl startup file. You can keep the connection open to use them in further setup calls to DBIx::Recordset objects. When the database is not kept open, you must specify the "!Password" parameter each time the recordset has to be reopend.

$tabfilter

same as setup parameter !TableFilter

$doonconnect

same as setup parameter !DoOnConnect

$reconnect

If set, forces DBIx::Database to "undef" any preexisting database handle and call connect in any case. This is useful in together with Apache::DBI. While the database connection are still kept open by Apache::DBI, Apache::DBI preforms a test if the handle is still vaild (which DBIx::Database itself wouldn't).

You also can specify a hashref which can contain the following parameters:

!DataSource, !Username, !Password, !DBIAttr, !SaveAs, !KeepOpen, !TableFilter, !DoOnConnect, !Reconnect

$db = DBIx::Database -> DBHdl¶

returns the database handle (only if you specify !KeepOpen when calling "new").

$db = DBIx::Database -> Get ($name)¶

$name = The name of the DBIx::Database object you wish to retrieve

Get a DBIx::Database object which has already been set up based on the name.

$db -> TableAttr ($table, $key, $value)¶

get and/or set an attribute for an specfic table.

$table

Name of table(s). You may use '*' instead of the table name to specify a default value which applies to all tables for which no other value is specified.

$key

key to set/get

$value

if present, set key to this value

$db -> TableLink ($table, $linkname, $value)¶

Get and/or set a link description for an table. If no $linkname is given, returns all links for that table.

$table

Name of table(s)

$linkname

Name of link to set/get

$value

if present, this must be a reference to a hash with the link decription. See !Links for more information.

$db -> MetaData ($table, $metadata, $clear)¶

Get and/or set the meta data for the given table.

$table

Name of table(s)

$metadata

If present, this must be a reference to a hash with the new metadata. You should only use this if you really know what you are doing.

$clear

Clears the metadata for the given table, The next call to DBIx::Database -> new will recreate the metadata. Useful if your table has changed (e.g. by ALTER TABLE).

$db -> AllTables¶

This returns a reference to a hash of the keys to all the tables of the datasource.

$db -> AllNames ($table)¶

Returns a reference to an array of all fieldnames for the given table.

$db -> AllTypes ($table)¶

Returns a reference to an array of all fieldtypes for the given table.

$db -> do ($statement, $attribs, \%params)

Same as DBI. Executes a single SQL statement on the open database.

$db -> CreateTables ($dbschema, $schemaname, $user, $setpriv, $alterconstraints)¶

The CreateTables method is used to create an modify the schema of your database. The idea is to define the schema as a Perl data structure and give it to this function, it will compare the actual schema of the database with the one provided and creates new tables, new fields or drop fields as necessary. It also sets the permission on the tables and is able to create indices for the tables. It will never drop a whole table! NOTE: Create tables cannot deteminate changes of the datatype of a fields, because DBI is not able to provide this information in a standard way.

$dbschema

Either the name of a file which contains the schema or a array ref. See below how this schema must look like.

$schemaname

schemaname (only used for Oracle)

$user

User that should be granted access. See "!Grant" parameter.

$setpriv

If set to true, access privilegs are revoked and granted again for already existing tables. That is necessary when $user changes.

$alterconstraints

If set to true contrains are cleared/set for already existing fields. DBI doesn't provide a database independ way to check which contrains already exists.

Schema definition¶

If give as a filename, the file must contain an hash %DBDefault and an array @DBSchema. The first gives default and the second is an array of hashs. Every of this hash defines one table.

Example:

  %DBDefault = 
    (
    '!Grant' => 
        [
        'select', 
        'insert',
        'update',
        'delete',
        ],
    )
     ;
  @DBSchema = (
    {
    '!Table' => 'language',
    '!Fields' => 
        [
        'id'            => 'char (2)',
        'directory'     => 'varchar(40)',
        'name'          => 'varchar(40)',
        'europe'        => 'bool', 
        ],
    '!PrimKey' => 'id',
    '!Default' =>
        {
        'europe'    => 1,
        },
    '!Init' =>
        [
        {'id' => 'de', 'directory' => 'html_49', 'name' => 'deutsch'},
        {'id' => 'en', 'directory' => 'html_76', 'name' => 'english'},
        {'id' => 'fr', 'directory' => 'html_31', 'name' => 'french'},
        ],
   '!Index' =>
        [
        'directory' => '',
        ]
 
    },
  );

The hash which defines a table can have the following keys:

!Table

Gives the table name

!Fields

Array with field names and types. There a some types which a translated database specifc. You can define more database specific translation in Compat.pm.

!PrimKey

Name of the primary key

!For

Can contain the same key as the table definintion, but is only executed for a specifc database.

Example:

    '!For' => { 
        'Oracle' => {
            '!Constraints' =>
                {
                'web_id'           => ['foreign key' => 'REFERENCES web (id)'],
                'prim__menu_id'    => ['!Name'       => 'web_prim_menu_id',
                                       'foreign key' => 'REFERENCES menu (id)',
                                       'not null'    => ''],
                }
            },
        },
    

!Contraints

Used to define constraints. See example under "!For".

!Init

Used to initialy populate the table.

!Default

Used to set a default value for a field, when the table is created. This doesn't have any affect for further INSERTs/UPDATEs.

!Grant

Give the rights that should be grant to $user

!Index

Gives the names for the fields for which indices should be created. If the second parameter for an index is not empty, it gives the index name, otherwise a default name is used.

$db -> DropTables ($schemaname, $user)¶

Drops all tables. Use with care!

$schemaname

schemaname (only used for Oracle)

$user

User that should be revoked access. See "!Grant" parameter.