NAME

MyDB::DBI - implement the CIToolkit ``persistant object store'' in tabular form over the popular DBI-DBD foundation.


MODULE

base


SYNOPSIS

  use MyDB::DBI;
  $db = MyDB::DBI->new(@dbopts,@args);
  $db = MyDB::DBI->new($subtype, $subargs, $dbname, $rw_opt, %args);


DESCRIPTION

This package provides methods for converting an object into key-value pairs and storing it as a row in a table, and vice-versa. Table interaction is provided through the Perl DBI-DBD interface, allowing the data to be stored in most SQL databases, delimited text files, and several common spreadsheet formats.

To use this package, you must select and install your database system and appropriate DBD module. A couple common options are listed below, but read the Perl DBI and DBD documentation for more information.


WARNING!!!

This package does NOT accomodate all instances of all objects!

It is meant to help beginning users with _most_ of the types we have defined so far. It makes several assumptions about the devices and supporting libraries in order to parse the object's attributes into a form that can be stored in a table.

It does NOT just store the object as a flattened data structure like GDBM and LDAP do! This means that the configuration data can be more easily imported from other sources and/or modified outside of the available CIT tools. However, this limits the capabilities of the CIToolkit. It is also considerably slower as the objects need to be parsed or created on the fly.

If you do wish to use this package, we recommend that you do so only for initial configuration. Use the db_mgr --dump and --restore capabilities to convert the database to a faster, more flexible form for future use.

You have been warned.


METHODS

new - connect to the database
  $db = MyDB::DBI->new(@dbopts,@args);
  $db = MyDB::DBI->new($subtype, $subargs, $dbname, $rw_opt, %args);

This method examines the datasource connection info to determine where and how to connect to a tabular database and then initiates the connection, returning the connected database object. Returns undef on failure.

The $subtype parameter tells the DBI module which type of database it will be connecting to such as CSV, MySQL, etc.

The $subargs parameter contains information on how and where to connect to the database. This the supporting database ``instance''.

In general, the ``connect string'' or ``datasource'' described in your DBD documentation will look like ``DBI:$subtype:$subargs''. This is the string that will be passed to DBI->connect();

The $dbname parameter is a unique identifier for the CIT persistent object store instance. This happens to be the table name to be used within the underlying database instance.

The $rw_opt parameter determines whether the database is opened for read or write access, or if a new object store should be initialized. Although there is not yet a difference between connecting to the underlying database with read or write access, ``r'' should be used for read access, ``w'' for write access, and ``c'' for create. Write access implies read access, and creating the database implies both read and write.

At this point, the %args parameter is not used, but may contain extra connection information in the future, such as username and password.

other methods -
See MyDB documentation for other db access methods


COLUMN NAME CONVENTIONS

A few simple name conventions are used to capture as much information about the objects as possible in flat tabular form:

The NAME column is required and must contain a unique object name.

The ISA column is required and must contain either ``Collection'' or the device type (eg: ``Device::Node::Alpha''). Support for the device type must be included in the Device Hierarchy libraries.

Collections can be specified by including a space separated list of objects in the COLLECTION_MEMBERS column.

Console connections are specified with the CONSOLE_DEV column and one of either CONSOLE_PORT or CONSOLE_VIA_PORT. CONSOLE_DEV specifies the device to connect to (ts-45), CONSOLE_PORT specifies the port on the console device to open a telnet connection to (2005), and CONSOLE_VIA_PORT can be used to specify additional port information for the cases where a menu on the console device must be navigated to make the final connection.

Power connections are specified with the POWER_DEV column and one of either POWER_PORT or POWER_VIA_PORT. POWER_DEV specifies the device to connect to (rpc-8), POWER_PORT specifies the port on the power device to open a telnet connection to (23), and POWER_VIA_PORT can be used to specify additional port information for the cases where a menu on the power device must be navigated to control power to a given port.

Since a node can have multiple interfaces, interface fields must be prefixed with ``IF?_'' where ? is a digit, starting with 0 and going up. (IF0_NET_MASK for example) Interface field suffixes are:

IF?_ADDRESS - IP address (192.168.1.30)
IF?_HOSTNAME - Host name (n-2.r-7)
IF?_MAC_ADDRESS - MAC (00:b0:d0:de:74:6e)
IF?_NAME - OS network device name (eth0)
IF?_NET_MASK - Net mask (255.255.255.0)

And, if a device has multiple interfaces, you may also specify:

IF?_IS_PRIMARY - Flag (0/1) to define the primary interface.

Columns for simple key/value pairs should be specified simply with the attribute name. Common attributes include: LEADER, ROLE, VMNAME, IMAGE and SYSARCH. Additional ``simple'' attributes can be added as long as the Device hierarchy libs support them.

If you want to add additional ``complex attributes'', support code must be added to Attr_mgr.pm and DBI.pm. Or, as recommended, use one of the other MyDB packages such as GDBM or LDAP to store your objects.


USING DBD::CSV

The requirements of the csv file are as follows: - First line is the column headers - First column is the object name

For a CSV (character separated values) file, the connect string to pass to MyDB->new will look something like this:

  'DBI:CSV:f_dir=/home/nwdauch/dev/csvtest/dbdir;csv_eol=\012:cluster'

(ugly ain't it?)

Note that if the connection string fails on a create, by default the DBD::CSV module will create the database in your current directory.

And the modules you will need to install include:

  DBD::CSV
  SQL::Statement
  Text::CSV_XS
  (and possbly others)

Alternatively, you can take the AnyData approach:

  DBD::AnyData
  SQL::Statement
  DBD::File
  (but I haven't tested it yet at all)


USING MySQL

The connect string to pass to MyDB->new should look something like this:

  'DBI:mysql:$database:cluster'

And you will need to have a working MySQL install and $database should already be created.


SEE ALSO

MyDB documentation for other db access methods

Perl DBI documentation perldoc DBI perldoc DBI::FAQ http://dbi.perl.org/

dumpdb

restoredb