.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" 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
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    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 >0, 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
.\" ========================================================================
.\"
.IX Title "SQL::Translator::Parser::DBI 3pm"
.TH SQL::Translator::Parser::DBI 3pm 2024-01-20 "perl v5.38.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
SQL::Translator::Parser::DBI \- "parser" for DBI handles
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 2
\&  use DBI;
\&  use SQL::Translator;
\&
\&  my $dbh = DBI\->connect(\*(Aqdsn\*(Aq, \*(Aquser\*(Aq, \*(Aqpass\*(Aq,
\&      {
\&          RaiseError       => 1,
\&          FetchHashKeyName => \*(AqNAME_lc\*(Aq,
\&      }
\&  );
\&
\&  my $translator  =  SQL::Translator\->new(
\&      parser      => \*(AqDBI\*(Aq,
\&      parser_args => {
\&          dbh => $dbh,
\&      },
\&  );
.Ve
.PP
Or:
.PP
.Vb 1
\&  use SQL::Translator;
\&
\&  my $translator      =  SQL::Translator\->new(
\&      parser          => \*(AqDBI\*(Aq,
\&      parser_args     => {
\&          dsn         => \*(Aqdbi:mysql:FOO\*(Aq,
\&          db_user     => \*(Aqguest\*(Aq,
\&          db_password => \*(Aqpassword\*(Aq,
\&    }
\&  );
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
This parser accepts an open database handle (or the arguments to create
one) and queries the database directly for the information.
.PP
The following are acceptable arguments:
.IP \(bu 4
dbh
.Sp
An open DBI database handle.  NB:  Be sure to create the database with the
"FetchHashKeyName => 'NAME_lc'" option as all the DBI parsers expect
lowercased column names.
.IP \(bu 4
dsn
.Sp
The DSN to use for connecting to a database.
.IP \(bu 4
db_user
.Sp
The user name to use for connecting to a database.
.IP \(bu 4
db_password
.Sp
The password to use for connecting to a database.
.PP
There is no need to specify which type of database you are querying as
this is determined automatically by inspecting \f(CW$dbh\fR\->{'Driver'}{'Name'}.
If a parser exists for your database, it will be used automatically;
if not, the code will fail automatically (and you can write the parser
and contribute it to the project!).
.PP
Currently parsers exist for the following databases:
.IP \(bu 4
MySQL
.IP \(bu 4
SQLite
.IP \(bu 4
Sybase
.IP \(bu 4
PostgreSQL (still experimental)
.PP
Most of these parsers are able to query the database directly for the
structure rather than parsing a text file.  For large schemas, this is
probably orders of magnitude faster than traditional parsing (which
uses Parse::RecDescent, an amazing module but really quite slow).
.PP
Though no Oracle parser currently exists, it would be fairly easy to
query an Oracle database directly by using DDL::Oracle to generate a
DDL for the schema and then using the normal Oracle parser on this.
Perhaps future versions of SQL::Translator will include the ability to
query Oracle directly and skip the parsing of a text file, too.
.SH AUTHOR
.IX Header "AUTHOR"
Ken Y. Clark <kclark@cpan.org>.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
DBI, SQL::Translator.