NAME

DBD::Gofer::Transport::http - DBD::Gofer client transport using http

SYNOPSIS

  my $remote_dsn = "..."
  DBI->connect("dbi:Gofer:transport=http;url=http://gofer.example.com/gofer;dsn=$remote_dsn",...)

or, enable by setting the DBI_AUTOPROXY environment variable:

  export DBI_AUTOPROXY='dbi:Gofer:transport=http;url=http://gofer.example.com/gofer'

which will force all DBI connections to be made via that Gofer server.

DESCRIPTION

Connect with DBI::Gofer servers that use http transports, i.e., DBI::Gofer::Transport::mod_perl.

This module currently uses the LWP::UserAgent and HTTP::Request modules to manage the http protocol. The default timeout is undef (unlimited). The LWP::UserAgent env_proxy option is enabled.

ATTRIBUTES

See DBD::Gofer::Transport::Base for a description of the Gofer transport attributes that are common to all transports, and another common features such as enabling gofer transport tracing.

The DBD::Gofer::Transport::http transport doesn't add any extra attributes.

go_timeout

The timeout provided by DBD::Gofer::Transport::Base is used. The go_timeout value is also passed to LWP::UserAgent as its timeout value. In practice the DBD::Gofer::Transport::Base timeout would almost certainly fire first. This area is subject to change in future releases.

PROTOCOL

The request is sent as a POST with a content type of 'application/x-perl-gofer-request-binary'.

The user-agent string is 'DBD::Gofer::Transport::http/<$DBI::VERSION>/<$VERSION>'.

METHODS

transmit_request_by_transport

  $response = $transport->transmit_request_by_transport( $request );

Freezes and transmits the request using the LWP::UserAgent and HTTP::Request modules. Waits for and returns response. Any exception is caught and returned as a response object.

receive_response_by_transport

This method isn't used because transmit_request_by_transport() always returns a response object. If called it throws an exception.

response_retry_preference

  $retry = $transport->response_retry_preference($request, $response);

The response_retry_preference is called by DBD::Gofer when considering if a request should be retried after an error.

Returns true (would like to retry), false (must not retry), undef (no preference).

If a true value is returned in the form of a CODE ref then, if DBD::Gofer does decide to retry the request, it calls the code ref passing $retry_count, $retry_limit. Currently the called code must return using return;.

discard_cached_connections

  $transport->discard_cached_connections();

Drops any persistent-connections associated with the transport.

ENVIRONMENT VARIABLES

These environment variables are not considered a stable part of the interface and they may change between releases. (The general plan is for corresponding gofer transport attributes to be added. That would enable per-handle configuration. Patches welcome.)

DBD_GOFER_CONN_CACHE

Specifies the size of the persistent-conection cache for the transport object. Default is 10. Set to 0 to disable use of HTTP/1.1 persistent-conections.

DBD_GOFER_RETRY_WARN

Emit a warn() whenever a request is retried.

DBD_GOFER_RETRY_BACKOFF_SCALE

Specifies the amount to multiply the retry delay by on each retry. Default value 2.

DBD_GOFER_RETRY_DELAY_INIT

Initial delay, in seconds, before retrying after a request receives a 503 response. (The DBD_GOFER_RETRY_BACKOFF_SCALE is applied first, so the actual initial delay is this value multipled by DBD_GOFER_RETRY_BACKOFF_SCALE). Default value 0.2.

DBD_GOFER_RETRY_ON_EMPTY

Used to workaround problems with buggy load balancers (e.g. a Juniper DX with standing connections enabled) which cause some requests to fail whithout ever reaching the gofer server.

If set to 1 then empty responses will be retried. If is_idempotent() is true then upto 20 retries will be performed, else just 1 retry. The retries happen without any delay and log a warning each time.

If set to a higher value then the retry counts are multiplied by that amount, so a value of 3 will retry idempotent requests 30 times, for example.

This mechanism is not recommended for non-readonly databases because there's a risk that the server did receive and act on the request, so retrying it would cause the database change to be repeated, which may cause other problems.

BUGS AND LIMITATIONS

There is currently no support for http authentication.

Please report any bugs or feature requests to bug-dbi-gofer-transport-mod_perl@rt.cpan.org, or through the web interface at http://rt.cpan.org.

SEE ALSO

DBD::Gofer and DBI::Gofer::Transport::mod_perl

AUTHOR

Tim Bunce, http://www.tim.bunce.name

LICENCE AND COPYRIGHT

Copyright (c) 2007, Tim Bunce, Ireland. All rights reserved.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See perlartistic.