Debian Codegraph @

README

raw
1 NAME
2 DBIx::Introspector - Detect what database you are connected to
3
4 VERSION
5 version 0.001005
6
7 SYNOPSIS
8 my $d = DBIx::Introspector->new(drivers => '2013-12.01');
9
10 # standard dialects
11 $d->decorate_driver_unconnected(Pg => concat_sql => '? || ?');
12 $d->decorate_driver_unconnected(SQLite => concat_sql => '? || ?');
13
14 # non-standard
15 $d->decorate_driver_unconnected(MSSQL => concat_sql => '? + ?');
16 $d->decorate_driver_unconnected(mysql => concat_sql => 'CONCAT( ?, ? )');
17
18 my $concat_sql = $d->get($dbh, $dsn, 'concat_sql');
19
20 DESCRIPTION
21 "DBIx::Introspector" is a module factored out of the DBIx::Class
22 database detection code. Most code that needs to detect which database
23 it is connected to assumes that there is a one-to-one mapping from
24 database drivers to database engines. Unfortunately reality is rarely
25 that simple. For instance, DBD::ODBC is typically used to connect to SQL
26 Server, but ODBC can be used to connect to PostgreSQL, MySQL, and
27 Oracle. Additionally, while ODBC is the most common way to connect to
28 SQL Server, it is not the only option, as DBD::ADO can also be used.
29
30 "DBIx::Introspector" can correctly detect which database you are
31 connected to, because it was factored out of a complex, working
32 codebase. On top of that it has been written to be very extensible. So
33 if you needed to detect which version of your given database you are
34 connected to that would not be difficult.
35
36 Furthermore, "DBIx::Introspector" does its best to try to detect
37 information based on the dsn you give it if you have not yet connected,
38 so you can possibly avoid connection or at least defer connection.
39
40 METHODS
41 "add_driver"
42 $dbii->add_driver({
43 name => 'Pg',
44 parents => ['DBI'],
45 unconnected_options => {
46 concat_sql => '? || ?',
47 random_func => 'RANDOM()',
48 })
49
50 Takes a hashref defining a new driver .
51
52 "replace_driver"
53 $dbii->replace_driver({
54 name => 'Pg',
55 parents => ['DBI'],
56 unconnected_options => {
57 concat_sql => '? || ?',
58 random_func => 'RANDOM()',
59 })
60
61 Takes a hashref replacing an existing driver . Replaces the driver
62 already defined with the same name.
63
64 "decorate_driver_connected"
65 $dbii->decorate_driver_connected('MSSQL', 'concat_sql', '? + ?')
66
67 Takes a "driver name", "key" and a "value". The "key value" pair will be
68 inserted into the driver's "connected_options".
69
70 "decorate_driver_unconnected"
71 $dbii->decorate_driver_unconnected('SQLite', 'concat_sql', '? || ?')
72
73 Takes a "driver name", "key" and a "value". The "key value" pair will be
74 inserted into the driver's "unconnected_options".
75
76 "get"
77 $dbii->get($dbh, $dsn, 'concat_sql')
78
79 Takes a "dbh", "dsn", "key", and optionally a hashref of "options".
80
81 The "dbh" can be a coderef returning a "dbh". If you provide the
82 "dbh_fallback_connect" option it will be used to connect the "dbh" if it
83 is not already connected and then queried, if the "dsn" was
84 insufficient.
85
86 So for example, one might do:
87
88 my $dbh;
89 $dbii->get(sub { $dbh }, $dsn, 'concat_sql', {
90 dbh_fallback_connect => sub { $dbh = DBI->connect($dsn, $user, $pass) },
91 });
92
93 Which will only connect if it has to, like if the user is using the
94 "DBD::ODBC" driver to connect.
95
96 ATTRIBUTES
97 "drivers"
98 This has no default and is required, though a sane defaultish value does
99 exist.
100
101 Currently there is one predefined set of drivers, named "2013-12.01". If
102 drivers or facts or just the general structure of drivers changes they
103 will always be as a new named set of drivers. "2013-12.01" matches the
104 0.08250 release of DBIx::Class and probably many previous and following
105 releases.
106
107 If you need to define it from scratch, you can just pass an arrayref of
108 drivers; see the "DRIVER DEFINITION" section on what is required for
109 that. But generally it will look something like this (from the tests):
110
111 my $d = DBIx::Introspector->new(
112 drivers => [ map DBIx::Introspector::Driver->new($_),
113 {
114 name => 'DBI',
115 connected_determination_strategy => sub { $_[1]->{Driver}{Name} },
116 unconnected_determination_strategy => sub {
117 my $dsn = $_[1] || $ENV{DBI_DSN} || '';
118 my ($driver) = $dsn =~ /dbi:([^:]+):/i;
119 $driver ||= $ENV{DBI_DRIVER};
120 return $driver
121 },
122 },
123 {
124 name => 'SQLite',
125 parents => ['DBI'],
126 connected_determination_strategy => sub {
127 my ($v) = $_[1]->selectrow_array('SELECT "value" FROM "a"');
128 return "SQLite$v"
129 },
130 connected_options => {
131 bar => sub { 2 },
132 },
133 unconnected_options => {
134 borg => sub { 'magic ham' },
135 },
136 },
137 { name => 'SQLite1', parents => ['SQLite'] },
138 { name => 'SQLite2', parents => ['SQLite'] },
139 ]
140 );
141
142 DRIVER DEFINITION
143 Drivers ("DBIx::Introspector::Driver" objects) have the following six
144 attributes:
145
146 "name"
147 Required. Must be unique among the drivers contained in the
148 introspector.
149
150 "parents"
151 Arrayref of parent drivers. This allows parent drivers to implement
152 common options among children. So for example on might define a driver
153 for each version of PostgreSQL, and have a parent driver that they all
154 use for common base info.
155
156 "connected_determination_strategy"
157 This is a code reference that is called as a method on the driver with
158 the "dbh" as the first argument and an optional "dsn" as the second
159 argument. It should return a driver name.
160
161 "unconnected_determination_strategy"
162 This is a code reference that is called as a method on the driver with
163 the "dsn" as the first argument. It should return a driver name.
164
165 "connected_options"
166 Hashref of "key value" pairs for detecting information based on the
167 "dbh". A value that is not a code reference is returned directly, though
168 I suggest non-coderefs all go in the "unconnected_options" so that they
169 may be used without connecting if possilbe.
170
171 If a code reference is passed it will get called as a method on the
172 driver with the following list of values:
173
174 "dbh"
175 This is the connected "dbh" that you can use to introspect the
176 database.
177
178 "dsn"
179 This is the "dsn" passed to "get", possibly undefined.
180
181 "unconnected_options"
182 Hashref of "key value" pairs for detecting information based on the
183 "dsn". A value that is not a code reference is returned directly.
184
185 If a code reference is passed it will get called as a method on the
186 driver with the following list value:
187
188 "dsn"
189 This is the connected "dsn" that you can use to introspect the
190 database.
191
192 AUTHOR
193 Arthur Axel "fREW" Schmidt <[email protected]>
194
195 COPYRIGHT AND LICENSE
196 This software is copyright (c) 2015 by Arthur Axel "fREW" Schmidt.
197
198 This is free software; you can redistribute it and/or modify it under
199 the same terms as the Perl 5 programming language system itself.
200