Module documentation
Perl
module
-
Part of CPAN
distribution
XML-Generator-DBI 0.01.
XML::Generator::DBI - Generate SAX events from SQL queries
use XML::Generator::DBI;
use XML::Handler::YAWriter;
use DBI;
my $ya = XML::Handler::YAWriter->new(AsFile => "-");
my $dbh = DBI->connect("dbi:Pg:dbname=foo", "user", "pass");
my $generator = XML::Generator::DBI->new(
Handler => $ya,
dbh => $dbh
);
$generator->execute($sql, [@bind_params]);
This module is a replacement for the outdated DBIx::XML_RDB module.
It generates SAX events from SQL queries against a DBI connection.
Unlike DBIx::XML_RDB, it does not create a string directly, instead
you have to use some sort of SAX handler module. If you wish to
create a string or write to a file, use YAWriter, as shown in the
above SYNOPSIS section. Alternatively you might want to generate
a DOM tree or XML::XPath tree, which you can do with either of those
module's SAX handlers (known as Builders in those distributions).
The XML structure created is as follows:
<database>
<select query="SELECT * FROM foo">
<row>
<column1>1</column1>
<column2>fubar</column2>
</row>
<row>
<column1>2</column1>
<column2>intravert</column2>
</row>
</select>
</database>
Alternatively, pass the option AsAttributes => 1 to either the
execute() method, or to the new() method, and your XML will look
like:
<database>
<select query="SELECT * FROM foo">
<row column1="1" column2="fubar"/>
<row column1="2" column2="intravert"/>
</select>
</database>
Note that with attributes, ordering of columns is likely to be lost,
but on the flip side, it may save you some bytes.
Nulls are handled by excluding either the attribute or the tag.
Create a new XML generator.
Parameters are passed as key/value pairs:
- Handler (required)
-
A SAX handler to recieve the events.
- dbh (required)
-
A DBI handle on which to execute the queries. Must support the
prepare, execute, fetch model of execution, and also support
type_info if you wish to use the ShowColumns option (see below).
- AsAttributes
-
The default is to output everything as elements. If you wish to
use attributes instead (perhaps to save some bytes), you can
specify the AsAttributes option with a true value.
- RootElement
-
You can specify the root element name by passing the parameter
RootElement => "myelement". The default root element name is
"database".
- QueryElement
-
You can specify the query element name by passing the parameter
QueryElement => "thequery". The default is "select".
- RowElement
-
You can specify the row element name by passing the parameter
RowElement => "item". The default is "row".
- NoIndent
-
The indenting will be as above, unless you specify the NoIndent
parameter with a true value, which can reduce the size of the
generated results.
- ShowColumns
-
If you wish to add information about the columns to your output,
specify the ShowColumns option with a true value. This will then
show things like the name and data type of the column, whether the
column is NULLABLE, the precision and scale, and also the size of
the column. All of this information is from $dbh->type_info() (see
perldoc DBI), and may change as I'm not 100% happy with the output.
You execute a query and generate results with the execute method.
The first parameter is a string containing the query. The second is
a single or set of bind parameters. If you wish to make it more than
one bind parameter, it must be passed as an array reference:
$generator->execute(
"SELECT * FROM Users WHERE name = ?
AND password = ?",
[ $name, $password ],
);
Following the bind parameters you may pass any options you wish to
use to override the above options to new(). Thus allowing you to
turn on and off certain options on a per-query basis.
Binary data is encoded using Base64. If you are using AsElements,
the element containing binary data will have an attribute
xml:encoding="base64". We detect binary data as anything containing
characters outside of the XML UTF-8 allowed character set.
NB: Binary encoding is actually on the TODO list :-)
I'm thinking about adding something that will do nesting, so that
if you get back:
id activity colour
=============================
1 food green
1 garden yellow
2 garden red
It will automatically try and nest it as:
<database>
<select query="SELECT id, activity, colour FROM Favourites">
<id>
<value>1</value>
<activity>food</activity>
<colour>green</colour>
<activity>garden</activity>
<colour>yellow</colour>
</id>
<id>
<value>2</value>
<activity>garden</activity>
<colour>red</colour>
</id>
</select>
</database>
(the format above isn't considered set in stone, comments welcome)
I would only be able to do this based on changes in the value in a
particular column, rather than how certain technologies (e.g. MS SQL
Server 2000) do it based on the joins used.
Matt Sergeant, matt@sergeant.org
This is free software, you may use it and distribute it under the
same terms as Perl itself. Specifically this is the Artistic License,
or the GNU GPL Version 2.
PerlSAX, XML::Handler::YAWriter.
|
