« blib/lib/DBIO/DeploymentHandler/VersionStorage/Standard.pm
↑ Summary
blib/lib/DBIO/Storage/Async/TransactionContext.pm »
| 1 | package DBIO::Storage::DBI::Capabilities; | ||||||||||||||||||||||||||||
| 2 | # ABSTRACT: Three-tier capability probing for DBI storage drivers | ||||||||||||||||||||||||||||
| 3 | |||||||||||||||||||||||||||||
| 4 | 345 | ▶ | use strict; | ||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||
| 5 | 345 | ▶ | use warnings; | ||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||
| 6 | |||||||||||||||||||||||||||||
| 7 | 345 | our $VERSION = '0.900007'; | |||||||||||||||||||||||||||
| 8 | |||||||||||||||||||||||||||||
| 9 | 345 | ▶ | use base 'DBIO::Storage'; | ||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||
| 10 | 345 | ▶ | use mro 'c3'; | ||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||
| 11 | |||||||||||||||||||||||||||||
| 12 | 345 | ▶ | use DBIO::Exception; | ||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||
| 13 | |||||||||||||||||||||||||||||
| 14 | 345 | ▶ | use namespace::clean; | ||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||
| 15 | |||||||||||||||||||||||||||||
| 16 | 345 | our $CONTRACT_VERSION = '1.3'; | |||||||||||||||||||||||||||
| 17 | |||||||||||||||||||||||||||||
| 18 | |||||||||||||||||||||||||||||
| 19 | |||||||||||||||||||||||||||||
| 20 | 2 | ▶ | sub contract_version { $CONTRACT_VERSION } | ||||||||||||||||||||||||||
|
Subroutine
contract_version: called CC=1 SCAR=0.0
Pod
undocumented
| |||||||||||||||||||||||||||||
| 21 | |||||||||||||||||||||||||||||
| 22 | 345 | my @capabilities = (qw/ | |||||||||||||||||||||||||||
| 23 | insert_returning | ||||||||||||||||||||||||||||
| 24 | insert_returning_bound | ||||||||||||||||||||||||||||
| 25 | |||||||||||||||||||||||||||||
| 26 | multicolumn_in | ||||||||||||||||||||||||||||
| 27 | |||||||||||||||||||||||||||||
| 28 | placeholders | ||||||||||||||||||||||||||||
| 29 | typeless_placeholders | ||||||||||||||||||||||||||||
| 30 | |||||||||||||||||||||||||||||
| 31 | join_optimizer | ||||||||||||||||||||||||||||
| 32 | |||||||||||||||||||||||||||||
| 33 | transactional_ddl | ||||||||||||||||||||||||||||
| 34 | supports_if_exists | ||||||||||||||||||||||||||||
| 35 | supports_upsert | ||||||||||||||||||||||||||||
| 36 | supports_upsert_where | ||||||||||||||||||||||||||||
| 37 | supports_exists_query | ||||||||||||||||||||||||||||
| 38 | /); | ||||||||||||||||||||||||||||
| 39 | 345 | __PACKAGE__->mk_group_accessors( dbms_capability => map { "_supports_$_" } @capabilities ); | |||||||||||||||||||||||||||
| 40 | 345 | __PACKAGE__->mk_group_accessors( use_dbms_capability => map { "_use_$_" } (@capabilities ) ); | |||||||||||||||||||||||||||
| 41 | |||||||||||||||||||||||||||||
| 42 | # on by default, not strictly a capability (pending rewrite) | ||||||||||||||||||||||||||||
| 43 | 345 | __PACKAGE__->_use_join_optimizer (1); | |||||||||||||||||||||||||||
| 44 | 0 | ▶ | sub _determine_supports_join_optimizer { 1 }; | ||||||||||||||||||||||||||
|
Subroutine
_determine_supports_join_optimizer: not called CC=1 SCAR=6.9
| |||||||||||||||||||||||||||||
| 45 | |||||||||||||||||||||||||||||
| 46 | # transactional_ddl and supports_if_exists are engine-specific facts. The | ||||||||||||||||||||||||||||
| 47 | # default _determine_supports_* returns 0 (conservative: do not assume the | ||||||||||||||||||||||||||||
| 48 | # engine is transactional / has the IF [NOT] EXISTS syntax until the driver | ||||||||||||||||||||||||||||
| 49 | # says so). Drivers override via _use_X or _determine_supports_X. | ||||||||||||||||||||||||||||
| 50 | 10 | ▶ | sub _determine_supports_transactional_ddl { 0 } | ||||||||||||||||||||||||||
|
Subroutine
_determine_supports_transactional_ddl: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||
| 51 | 3 | ▶ | sub _determine_supports_supports_if_exists { 0 } | ||||||||||||||||||||||||||
|
Subroutine
_determine_supports_supports_if_exists: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||
| 52 | |||||||||||||||||||||||||||||
| 53 | # The per-statement half of transactional_ddl (ADR 0026 addendum). The | ||||||||||||||||||||||||||||
| 54 | # capability is one boolean for the connection, but atomicity is decided per | ||||||||||||||||||||||||||||
| 55 | # statement: some engines have DDL that may not be inside a transaction even | ||||||||||||||||||||||||||||
| 56 | # where everything else may. Default yes -- a driver that never overrides this | ||||||||||||||||||||||||||||
| 57 | # behaves exactly as before, and that is also the correct answer for every | ||||||||||||||||||||||||||||
| 58 | # engine whose DDL is uniformly transactional. Only a driver that emits such a | ||||||||||||||||||||||||||||
| 59 | # statement needs to say so. See L</_ddl_statement_is_transactional>. | ||||||||||||||||||||||||||||
| 60 | 0 | ▶ | sub _ddl_statement_is_transactional { 1 } | ||||||||||||||||||||||||||
|
Subroutine
_ddl_statement_is_transactional: not called CC=1 SCAR=6.9
| |||||||||||||||||||||||||||||
| 61 | |||||||||||||||||||||||||||||
| 62 | # The SQL dialect the engine's DDL is split under. undef = not declared = the | ||||||||||||||||||||||||||||
| 63 | # splitter takes both backslash readings, as it always has. A driver names | ||||||||||||||||||||||||||||
| 64 | # 'postgresql', 'sqlite', 'mysql' or 'oracle'. See L</_ddl_sql_dialect>. | ||||||||||||||||||||||||||||
| 65 | 21 | ▶ | sub _ddl_sql_dialect { undef } | ||||||||||||||||||||||||||
|
Subroutine
_ddl_sql_dialect: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||
| 66 | |||||||||||||||||||||||||||||
| 67 | # supports_upsert (ADR 0036) is the same kind of engine-specific fact: an | ||||||||||||||||||||||||||||
| 68 | # atomic INSERT ... ON CONFLICT / ON DUPLICATE KEY needs both engine grammar | ||||||||||||||||||||||||||||
| 69 | # and a driver SQLMaker that renders it, so the conservative default is 0. | ||||||||||||||||||||||||||||
| 70 | 17 | ▶ | sub _determine_supports_supports_upsert { 0 } | ||||||||||||||||||||||||||
|
Subroutine
_determine_supports_supports_upsert: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||
| 71 | |||||||||||||||||||||||||||||
| 72 | # ... and the conditional conflict branch on top of it. Default 0 is what | ||||||||||||||||||||||||||||
| 73 | # keeps a driver that has never heard of the option safe: core refuses to | ||||||||||||||||||||||||||||
| 74 | # send a condition rather than let it be dropped into an unconditional write. | ||||||||||||||||||||||||||||
| 75 | 5 | ▶ | sub _determine_supports_supports_upsert_where { 0 } | ||||||||||||||||||||||||||
|
Subroutine
_determine_supports_supports_upsert_where: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||
| 76 | |||||||||||||||||||||||||||||
| 77 | # supports_exists_query (ADR 0037): a boolean-valued EXISTS query is one more | ||||||||||||||||||||||||||||
| 78 | # engine fact -- three engines need a dummy table in it, and the ones nobody | ||||||||||||||||||||||||||||
| 79 | # has checked are exactly the ones a default-on would ship broken SQL to. The | ||||||||||||||||||||||||||||
| 80 | # driver renders the whole fragment (_exists_value_sql) and declares here that | ||||||||||||||||||||||||||||
| 81 | # it did. | ||||||||||||||||||||||||||||
| 82 | 1 | ▶ | sub _determine_supports_supports_exists_query { 0 } | ||||||||||||||||||||||||||
|
Subroutine
_determine_supports_supports_exists_query: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||
| 83 | |||||||||||||||||||||||||||||
| 84 | 722 | ▶ | sub set_use_dbms_capability { | ||||||||||||||||||||||||||
|
Subroutine
set_use_dbms_capability: called CC=3 SCAR=11.0
Pod
undocumented
| |||||||||||||||||||||||||||||
| 85 | 722 | my ($self, $capname, $value) = @_; | |||||||||||||||||||||||||||
| 86 | |||||||||||||||||||||||||||||
| 87 | # ADR 0041. The per-storage force (tier 1) and the class-level | ||||||||||||||||||||||||||||
| 88 | # declaration (tier 2) are two physically different slots -- set_inherited | ||||||||||||||||||||||||||||
| 89 | # writes the instance hash for an instance invocant and the | ||||||||||||||||||||||||||||
| 90 | # $Class::__cag_<field> package variable for a class one -- but | ||||||||||||||||||||||||||||
| 91 | # get_inherited reads the instance with exists(), not defined(). A plain | ||||||||||||||||||||||||||||
| 92 | # undef assignment would therefore leave a *tombstone* in tier 1 that | ||||||||||||||||||||||||||||
| 93 | # shadows the declaration for the life of this storage: the caller who | ||||||||||||||||||||||||||||
| 94 | # forces a capability off and then clears the force does not get the | ||||||||||||||||||||||||||||
| 95 | # driver's answer back, they fall through to _determine_supports_* and land | ||||||||||||||||||||||||||||
| 96 | # on core's conservative default. | ||||||||||||||||||||||||||||
| 97 | # | ||||||||||||||||||||||||||||
| 98 | # Deleting the slot is what "clear" has to mean, and undef is unambiguous | ||||||||||||||||||||||||||||
| 99 | # here: get_use_dbms_capability below already treats undef as "no opinion, | ||||||||||||||||||||||||||||
| 100 | # ask the next tier", so undef can never have meant "off" -- that is 0. | ||||||||||||||||||||||||||||
| 101 | # | ||||||||||||||||||||||||||||
| 102 | # A class invocant needs nothing: get_inherited tests defined() while it | ||||||||||||||||||||||||||||
| 103 | # walks classes, so an undef declaration already falls through on its own. | ||||||||||||||||||||||||||||
| 104 | 722 | ▶ | if (! defined $value and ref $self) { | ||||||||||||||||||||||||||
|
Branch: 1 branch
Condition100%3/3
not defined $value and ref $self
MC/DC100%2/2
not defined $value and ref $self
not defined $value
ref $self
Truth table100%3/3
not(A) and B
A= not defined $valueB= ref $self
| |||||||||||||||||||||||||||||
| 105 | 11 | delete $self->{$capname}; | |||||||||||||||||||||||||||
| 106 | 11 | return undef; | |||||||||||||||||||||||||||
| 107 | } | ||||||||||||||||||||||||||||
| 108 | |||||||||||||||||||||||||||||
| 109 | 711 | $self->set_inherited ($capname, $value); | |||||||||||||||||||||||||||
| 110 | } | ||||||||||||||||||||||||||||
| 111 | |||||||||||||||||||||||||||||
| 112 | 2779 | ▶ | sub get_use_dbms_capability { | ||||||||||||||||||||||||||
|
Subroutine
get_use_dbms_capability: called CC=2 SCAR=6.9
Pod
undocumented
| |||||||||||||||||||||||||||||
| 113 | 2779 | my ($self, $capname) = @_; | |||||||||||||||||||||||||||
| 114 | |||||||||||||||||||||||||||||
| 115 | 2779 | my $use = $self->get_inherited ($capname); | |||||||||||||||||||||||||||
| 116 | return defined $use | ||||||||||||||||||||||||||||
| 117 | ? $use | ||||||||||||||||||||||||||||
| 118 | 2779 | ▶ | : do { $capname =~ s/^_use_/_supports_/; $self->get_dbms_capability ($capname) } | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 119 | ; | ||||||||||||||||||||||||||||
| 120 | } | ||||||||||||||||||||||||||||
| 121 | |||||||||||||||||||||||||||||
| 122 | 192 | ▶ | sub set_dbms_capability { | ||||||||||||||||||||||||||
|
Subroutine
set_dbms_capability: called CC=1 SCAR=0.0
Pod
undocumented
| |||||||||||||||||||||||||||||
| 123 | 192 | $_[0]->_dbh_details->{capability}{$_[1]} = $_[2]; | |||||||||||||||||||||||||||
| 124 | } | ||||||||||||||||||||||||||||
| 125 | |||||||||||||||||||||||||||||
| 126 | 2417 | ▶ | sub get_dbms_capability { | ||||||||||||||||||||||||||
|
Subroutine
get_dbms_capability: called CC=5 SCAR=16.1
Pod
undocumented
| |||||||||||||||||||||||||||||
| 127 | 2417 | my ($self, $capname) = @_; | |||||||||||||||||||||||||||
| 128 | |||||||||||||||||||||||||||||
| 129 | # Determining a capability reads the per-$dbh detail slot, so a class-method | ||||||||||||||||||||||||||||
| 130 | # invocant runs out of road right here. Left alone, the accessor below dies | ||||||||||||||||||||||||||||
| 131 | # with "Class::XSAccessor: invalid instance method invocant: no hash ref | ||||||||||||||||||||||||||||
| 132 | # supplied", which names neither the capability nor the reason -- and the | ||||||||||||||||||||||||||||
| 133 | # very same call *does* work on a class whose driver declared the value via | ||||||||||||||||||||||||||||
| 134 | # _use_, so the failure looks arbitrary from the call site. | ||||||||||||||||||||||||||||
| 135 | # The check sits where the instance is actually needed and costs one ref(). | ||||||||||||||||||||||||||||
| 136 | 2417 | ▶ | unless (ref $self) { | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 137 | 4 | (my $usename = $capname) =~ s/^_supports_/_use_/; | |||||||||||||||||||||||||||
| 138 | 4 | DBIO::Exception->throw( | |||||||||||||||||||||||||||
| 139 | "Cannot determine the capability '$capname' on class '$self': " | ||||||||||||||||||||||||||||
| 140 | . "determining a capability probes the connected \$dbh and therefore needs " | ||||||||||||||||||||||||||||
| 141 | . "a storage instance -- ask one instead " | ||||||||||||||||||||||||||||
| 142 | . "(\$schema->storage->${capname}). A capability answers as a class method " | ||||||||||||||||||||||||||||
| 143 | . "only where a driver declared its value outright, with " | ||||||||||||||||||||||||||||
| 144 | . "__PACKAGE__->${usename}(0|1) in its storage class; that is why some " | ||||||||||||||||||||||||||||
| 145 | . "capabilities work that way and their neighbours die here" | ||||||||||||||||||||||||||||
| 146 | ); | ||||||||||||||||||||||||||||
| 147 | } | ||||||||||||||||||||||||||||
| 148 | |||||||||||||||||||||||||||||
| 149 | 2413 | my $cap = $self->_dbh_details->{capability}{$capname}; | |||||||||||||||||||||||||||
| 150 | |||||||||||||||||||||||||||||
| 151 | 2413 | ▶ | unless (defined $cap) { | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 152 | 192 | ▶ | if (my $meth = $self->can ("_determine$capname")) { | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 153 | 40 | ▶ | $cap = $self->$meth ? 1 : 0; | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 154 | } | ||||||||||||||||||||||||||||
| 155 | else { | ||||||||||||||||||||||||||||
| 156 | 152 | $cap = 0; | |||||||||||||||||||||||||||
| 157 | } | ||||||||||||||||||||||||||||
| 158 | |||||||||||||||||||||||||||||
| 159 | 192 | $self->set_dbms_capability ($capname, $cap); | |||||||||||||||||||||||||||
| 160 | } | ||||||||||||||||||||||||||||
| 161 | |||||||||||||||||||||||||||||
| 162 | 2413 | return $cap; | |||||||||||||||||||||||||||
| 163 | } | ||||||||||||||||||||||||||||
| 164 | |||||||||||||||||||||||||||||
| 165 | 345 | 1; | |||||||||||||||||||||||||||
| 166 | |||||||||||||||||||||||||||||
| 167 | __END__ | ||||||||||||||||||||||||||||