1DBIx::Introspector(3) User Contributed Perl DocumentationDBIx::Introspector(3)
2
6 DBIx::Introspector - Detect what database you are connected to
7
9 version 0.001005
10
12 my $d = DBIx::Introspector->new(drivers => '2013-12.01');
13 # standard dialects
15 $d->decorate_driver_unconnected(Pg => concat_sql => '? || ?');
16 $d->decorate_driver_unconnected(SQLite => concat_sql => '? || ?');
17 # non-standard
19 $d->decorate_driver_unconnected(MSSQL => concat_sql => '? + ?');
20 $d->decorate_driver_unconnected(mysql => concat_sql => 'CONCAT( ?, ? )');
21 my $concat_sql = $d->get($dbh, $dsn, 'concat_sql');
23
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 "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 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
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 Takes a hashref defining a new driver .
55 "replace_driver"
57 $dbii->replace_driver({
58 name => 'Pg',
59 parents => ['DBI'],
60 unconnected_options => {
61 concat_sql => '? || ?',
62 random_func => 'RANDOM()',
63 })
64 Takes a hashref replacing an existing driver . Replaces the driver
66 already defined with the same name.
67 "decorate_driver_connected"
69 $dbii->decorate_driver_connected('MSSQL', 'concat_sql', '? + ?')
70 Takes a "driver name", "key" and a "value". The "key value" pair will
72 be inserted into the driver's "connected_options".
73 "decorate_driver_unconnected"
75 $dbii->decorate_driver_unconnected('SQLite', 'concat_sql', '? || ?')
76 Takes a "driver name", "key" and a "value". The "key value" pair will
78 be inserted into the driver's "unconnected_options".
79 "get"
81 $dbii->get($dbh, $dsn, 'concat_sql')
82 Takes a "dbh", "dsn", "key", and optionally a hashref of "options".
84 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 So for example, one might do:
91 my $dbh;
93 $dbii->get(sub { $dbh }, $dsn, 'concat_sql', {
94 dbh_fallback_connect => sub { $dbh = DBI->connect($dsn, $user, $pass) },
95 });
96 Which will only connect if it has to, like if the user is using the
98 "DBD::ODBC" driver to connect.
99
101 "drivers"
102 This has no default and is required, though a sane defaultish value
103 does exist.
104 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 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 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
147 Drivers ("DBIx::Introspector::Driver" objects) have the following six
148 attributes:
149 "name"
151 Required. Must be unique among the drivers contained in the
152 introspector.
153 "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 "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 "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 "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 If a code reference is passed it will get called as a method on the
176 driver with the following list of values:
177 "dbh"
179 This is the connected "dbh" that you can use to introspect the
180 database.
181 "dsn"
183 This is the "dsn" passed to "get", possibly undefined.
184 "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 If a code reference is passed it will get called as a method on the
190 driver with the following list value:
191 "dsn"
193 This is the connected "dsn" that you can use to introspect the
194 database.
195
197 Arthur Axel "fREW" Schmidt <frioux+cpan@gmail.com>
198
200 This software is copyright (c) 2015 by Arthur Axel "fREW" Schmidt.
201 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.
204perl v5.38.0 2023-07-20 DBIx::Introspector(3)