/ 
DBIO-0.900000
/ DBIO::AccessBroker

NAME

DBIO::AccessBroker - Credential lifecycle for DBIO connections

VERSION

version 0.900000

SYNOPSIS

# Static — same as traditional connect, one DSN
use DBIO::AccessBroker::Static;
my $broker = DBIO::AccessBroker::Static->new(
    dsn => 'dbi:Pg:dbname=myapp',
    username => 'app', password => 'secret',
);
# Storage gets storage-native connect info
my $info = $broker->current_connect_info_for_storage($schema->storage);

# Vault — rotating credentials from OpenBao/Vault
use DBIO::AccessBroker::Vault;
my $broker = DBIO::AccessBroker::Vault->new(
    vault     => WWW::OpenBao->new(endpoint => 'http://vault:8200', token => $token),
    dsn       => 'dbi:Pg:dbname=myapp;host=db',
    cred_path => 'database/creds/myapp',
    ttl       => 3600,         # credentials valid for 1 hour
    refresh_margin => 900,     # refresh 15 min before expiry
);
# DBIO can now connect directly with a broker
my $schema = MyApp::Schema->connect($broker);

DESCRIPTION

AccessBroker is a CredentialSource: it supplies the connect info for exactly one backend identity (one set of credentials). It is storage-agnostic — it returns connection parameters, not handles — so it works with both Storage::DBI (sync) and Storage::Async (async/Future-based). It handles:

  • Credential lifecycle — fetching, rotating, and caching database credentials

A broker does not route, and it does not own a host list. Read/write routing and the master/replicant topology belong to DBIO::Replicated. One credential can serve many servers via a "for_host" view, which pairs this single identity with one host at connect time.

NAME

DBIO::AccessBroker - Credential lifecycle for DBIO connections

TRANSACTION SAFETY

A broker only supplies credentials, so the sole hazard to a running transaction is credentials rotating mid-flight. DBIO distinguishes:

  • has_rotating_credentials() — new connections may need refreshed credentials

  • is_transaction_safe() — DBIO may start a transaction through this broker without an explicit override

The default implementation treats brokers as transaction-safe unless they rotate credentials.

This means:

Starting a transaction through a broker marked as unsafe will throw by default. If you intentionally want to allow this, set DBIO_ALLOW_UNSAFE_BROKER_TRANSACTIONS=1. DBIO will then proceed, but emit a warning on transaction start.

SUBCLASSING

Implement these methods:

connect_info_for_storage($storage) — Return storage-native connect info
connect_info_for() — Optional legacy DBI-shaped connect info
needs_refresh() — Return true if credentials should be rotated
refresh() — Perform credential rotation
has_rotating_credentials() — Return true if credentials rotate across connections
is_transaction_safe() — Return true if DBIO may open transactions through this broker

The $mode argument

The broker methods accept a trailing $mode argument ('read' or 'write') for backward compatibility. It is vestigial: a broker is a single-identity CredentialSource with nothing to route on, so all built-in brokers ignore it. Routing decides read versus write — see DBIO::Replicated — not the broker. New broker subclasses should not branch on $mode.

AUTHOR

DBIO & DBIx::Class Authors

COPYRIGHT AND LICENSE

Copyright (C) 2026 DBIO Authors Portions Copyright (C) 2005-2025 DBIx::Class Authors Based on DBIx::Class, heavily modified.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.