1DBIx::Introspector(3) User Contributed Perl DocumentationDBIx::Introspector(3)
2
3
4

NAME

6       DBIx::Introspector - Detect what database you are connected to
7

VERSION

9       version 0.001005
10

SYNOPSIS

12        my $d = DBIx::Introspector->new(drivers => '2013-12.01');
13
14        # standard dialects
15        $d->decorate_driver_unconnected(Pg     => concat_sql => '? || ?');
16        $d->decorate_driver_unconnected(SQLite => concat_sql => '? || ?');
17
18        # non-standard
19        $d->decorate_driver_unconnected(MSSQL  => concat_sql => '? + ?');
20        $d->decorate_driver_unconnected(mysql  => concat_sql => 'CONCAT( ?, ? )');
21
22        my $concat_sql = $d->get($dbh, $dsn, 'concat_sql');
23

DESCRIPTION

25       "DBIx::Introspector" is a module factored out of the DBIx::Class
26       database detection code.  Most code that needs to detect which database
27       it is connected to assumes that there is a one-to-one mapping from
28       database drivers to database engines.  Unfortunately reality is rarely
29       that simple.  For instance, DBD::ODBC is typically used to connect to
30       SQL Server, but ODBC can be used to connect to PostgreSQL, MySQL, and
31       Oracle.  Additionally, while ODBC is the most common way to connect to
32       SQL Server, it is not the only option, as DBD::ADO can also be used.
33
34       "DBIx::Introspector" can correctly detect which database you are
35       connected to, because it was factored out of a complex, working
36       codebase.  On top of that it has been written to be very extensible.
37       So if you needed to detect which version of your given database you are
38       connected to that would not be difficult.
39
40       Furthermore, "DBIx::Introspector" does its best to try to detect
41       information based on the dsn you give it if you have not yet connected,
42       so you can possibly avoid connection or at least defer connection.
43

METHODS

45   "add_driver"
46        $dbii->add_driver({
47          name => 'Pg',
48          parents => ['DBI'],
49          unconnected_options => {
50             concat_sql => '? || ?',
51             random_func => 'RANDOM()',
52          })
53
54       Takes a hashref defining a new driver .
55
56   "replace_driver"
57        $dbii->replace_driver({
58          name => 'Pg',
59          parents => ['DBI'],
60          unconnected_options => {
61             concat_sql => '? || ?',
62             random_func => 'RANDOM()',
63          })
64
65       Takes a hashref replacing an existing driver .  Replaces the driver
66       already defined with the same name.
67
68   "decorate_driver_connected"
69        $dbii->decorate_driver_connected('MSSQL', 'concat_sql', '? + ?')
70
71       Takes a "driver name", "key" and a "value".  The "key value" pair will
72       be inserted into the driver's "connected_options".
73
74   "decorate_driver_unconnected"
75        $dbii->decorate_driver_unconnected('SQLite', 'concat_sql', '? || ?')
76
77       Takes a "driver name", "key" and a "value".  The "key value" pair will
78       be inserted into the driver's "unconnected_options".
79
80   "get"
81        $dbii->get($dbh, $dsn, 'concat_sql')
82
83       Takes a "dbh", "dsn", "key", and optionally a hashref of "options".
84
85       The "dbh" can be a coderef returning a "dbh".  If you provide the
86       "dbh_fallback_connect" option it will be used to connect the "dbh" if
87       it is not already connected and then queried, if the "dsn" was
88       insufficient.
89
90       So for example, one might do:
91
92        my $dbh;
93        $dbii->get(sub { $dbh }, $dsn, 'concat_sql', {
94           dbh_fallback_connect => sub { $dbh = DBI->connect($dsn, $user, $pass) },
95        });
96
97       Which will only connect if it has to, like if the user is using the
98       "DBD::ODBC" driver to connect.
99

ATTRIBUTES

101   "drivers"
102       This has no default and is required, though a sane defaultish value
103       does exist.
104
105       Currently there is one predefined set of drivers, named "2013-12.01".
106       If drivers or facts or just the general structure of drivers changes
107       they will always be as a new named set of drivers.  "2013-12.01"
108       matches the 0.08250 release of DBIx::Class and probably many previous
109       and following releases.
110
111       If you need to define it from scratch, you can just pass an arrayref of
112       drivers; see the "DRIVER DEFINITION" section on what is required for
113       that.  But generally it will look something like this (from the tests):
114
115        my $d = DBIx::Introspector->new(
116          drivers => [ map DBIx::Introspector::Driver->new($_),
117             {
118                name => 'DBI',
119                connected_determination_strategy => sub { $_[1]->{Driver}{Name} },
120                unconnected_determination_strategy => sub {
121                   my $dsn = $_[1] || $ENV{DBI_DSN} || '';
122                   my ($driver) = $dsn =~ /dbi:([^:]+):/i;
123                   $driver ||= $ENV{DBI_DRIVER};
124                   return $driver
125                },
126             },
127             {
128                name => 'SQLite',
129                parents => ['DBI'],
130                connected_determination_strategy => sub {
131                   my ($v) = $_[1]->selectrow_array('SELECT "value" FROM "a"');
132                   return "SQLite$v"
133                },
134                connected_options => {
135                   bar => sub { 2 },
136                },
137                unconnected_options => {
138                   borg => sub { 'magic ham' },
139                },
140             },
141             { name => 'SQLite1', parents => ['SQLite'] },
142             { name => 'SQLite2', parents => ['SQLite'] },
143          ]
144        );
145

DRIVER DEFINITION

147       Drivers ("DBIx::Introspector::Driver" objects) have the following six
148       attributes:
149
150   "name"
151       Required.  Must be unique among the drivers contained in the
152       introspector.
153
154   "parents"
155       Arrayref of parent drivers.  This allows parent drivers to implement
156       common options among children.  So for example on might define a driver
157       for each version of PostgreSQL, and have a parent driver that they all
158       use for common base info.
159
160   "connected_determination_strategy"
161       This is a code reference that is called as a method on the driver with
162       the "dbh" as the first argument and an optional "dsn" as the second
163       argument.  It should return a driver name.
164
165   "unconnected_determination_strategy"
166       This is a code reference that is called as a method on the driver with
167       the "dsn" as the first argument.  It should return a driver name.
168
169   "connected_options"
170       Hashref of "key value" pairs for detecting information based on the
171       "dbh".  A value that is not a code reference is returned directly,
172       though I suggest non-coderefs all go in the "unconnected_options" so
173       that they may be used without connecting if possilbe.
174
175       If a code reference is passed it will get called as a method on the
176       driver with the following list of values:
177
178       "dbh"
179         This is the connected "dbh" that you can use to introspect the
180         database.
181
182       "dsn"
183         This is the "dsn" passed to "get", possibly undefined.
184
185   "unconnected_options"
186       Hashref of "key value" pairs for detecting information based on the
187       "dsn".  A value that is not a code reference is returned directly.
188
189       If a code reference is passed it will get called as a method on the
190       driver with the following list value:
191
192       "dsn"
193         This is the connected "dsn" that you can use to introspect the
194         database.
195

AUTHOR

197       Arthur Axel "fREW" Schmidt <frioux+cpan@gmail.com>
198
200       This software is copyright (c) 2015 by Arthur Axel "fREW" Schmidt.
201
202       This is free software; you can redistribute it and/or modify it under
203       the same terms as the Perl 5 programming language system itself.
204
205
206
207perl v5.38.0                      2023-07-20             DBIx::Introspector(3)
Impressum