File Coverage

blib/lib/DBIx/PgLink.pm

Criterion	Covered	Total	%
statement	15	36	41.6
branch	0	10	0.0
condition			n/a
subroutine	5	8	62.5
pod	3	3	100.0
total	23	57	40.3

package DBIx::PgLink;

use 5.008006;
use strict;
use warnings;
use Exporter;
use DBIx::PgLink::Logger;

our @ISA = qw/Exporter/;

our @EXPORT = qw/named_params/;

our $VERSION = '0.01';

our %connection_by_name;

sub connect {
  my $self = shift;
  my $conn_name = shift;

  trace_msg('INFO', "Using connection $conn_name")
    if trace_level>=2;

  if (exists $connection_by_name{$conn_name}) {
    return $connection_by_name{$conn_name};
  } else {
    require DBIx::PgLink::Connector;
    my $conn = DBIx::PgLink::Connector->new(
      conn_name => $conn_name,
      @_
    );
    $connection_by_name{$conn_name} = $conn;
    return $conn;
  }
}

sub disconnect {
  my ($self, $conn_name) = @_;

  my $data = $main::_SHARED{'dbix_pglink'};
  my $conn = $connection_by_name{$conn_name} or return;
  trace_msg('INFO', "Disconnect from $conn_name")
    if trace_level>=1;
  $conn->adapter->disconnect;
  delete $connection_by_name{$conn_name};
}


sub named_params {
  my $params = shift;
  my $i = 0;
  my %p = map {
    my $v = $params->[$i++];
    defined $v ?  ($_ => $v) : () # skip NULLs
  } @_;
  return \%p;
}

1;


__END__


=head1 NAME

DBIx::PgLink - external database access from PostgreSQL backend using Perl DBI

=head1 SYNOPSIS

For SQL script examples see L<DBIx::PgLink::Manual::Usage>.

I<In PL/PerlU function>

    use DBIx::PgLink;

    $conn = DBIx::PgLink->connect('NORTHWIND');

    $db = $conn->adapter;
    $db->begin_work;
    $st = $db->prepare('SELECT * FROM Orders WHERE OrderID=?');
    $st->execute(42);
    while (@row = $st->fetchrow_array) {
      ...
    }
    $db->commit;

    $conn->builder->build_accessors(
      local_schema  => 'northwind',
      remote_schema => 'dbo',
      remote_object => 'Order%',
    );

    DBIx::PgLink->disconnect('NORTHWIND');

=head1 DESCRIPTION

I<PgLink> is based on I<DBI-Link> project for accessing
external data sources from PostgreSQL backend.

This module can be used only in untrusted PL/Perl function.

=head2 Differences from I<DBI-Link>

=over

=item *

I<PgLink> is standard Perl module

While I<DBI-Link> store all Perl code in PL/Perl functions,
DBIx-PgLink use Perl infrastructure for installation and testing.

=item *

Extensibility

The main goal is to compose functionality without writing a line of Perl code.

=item *

Flexible data type mapping

=item *

Customizable SQL queries.

=item *

Parametrized queries

Prevent SQL-injection attack.

=item *

Mapping between database accounts

Can connect with different credentials for each PostgreSQL user.

=item *

Additional functionality for DBI

Such as automatic reconnection after network outage,
nested transactions, charset conversion, prepared statement cache management.


=back


=head1 SUBROUTINES

=over

=item connect

    $adapter = connect($conn_name);

Load connection metadata from PostgreSQL and connect to remote datasource.

Returns instance of L<DBIx::PgLink::Connector> object.

Subsequent calls return the same cached object.
Single connection persists while PostgreSQL session live
or until explicit C<disconnect>.

=item disconnect

    disconnect($conn_name);

Close connection to remote database and delete entry from cache.

=item named_params

    my $hashref = named_params(\@_, qw/foo bar/); # { foo=>$_[0], bar=>$_[1] }

Utility subroutine. Converts positional arguments of PL/Perl function (passed in @_) to named parameters.
NULL arguments are ignored.

Exported by default.

=back


=head1 SEE ALSO

L<DBIx::PgLink::Manual::Install>,
L<DBIx::PgLink::Manual::Usage>,
L<DBI>,
L<DBIx::PgLink::Connector>,
L<DBIx::PgLink::Adapter>,
L<DBIx::PgLink::Accessor::Table>,
L<DBIx::PgLink::Local>,
L<http://pgfoundry.org/projects/dbi-link/>

=head1 AUTHOR

Alexey Sharafutdinov E<lt>[e-mail]<gt>

=head1 COPYRIGHT AND LICENSE

Copyright (C) 2007 by Alexey Sharafutdinov

This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself, either Perl version 5.8.8 or,
at your option, any later version of Perl 5 you may have available.

DBI-Link project by David Fetter under BSD License.

=cut