/ 
Net-Blossom-Server-Backend-Postgres-0.001000
/ Net::Blossom::Server::Backend::Postgres

NAME

Net::Blossom::Server::Backend::Postgres - Postgres storage backend for Blossom servers

SYNOPSIS

use Net::Blossom::Server;
use Net::Blossom::Server::Backend::Postgres;

my $storage = Net::Blossom::Server::Backend::Postgres->new(
    dsn      => 'dbi:Pg:dbname=blossom;host=/var/run/postgresql',
    username => 'blossom',
    password => $password,
    base_url => 'https://cdn.example.com',
);
$storage->deploy_schema;

my $server = Net::Blossom::Server->new(storage => $storage);

DESCRIPTION

Net::Blossom::Server::Backend::Postgres is a Postgres storage backend for Net::Blossom::Server. It stores Blossom blob bytes and metadata in Postgres and implements the Net::Blossom::Server::Storage contract.

Postgres access is provided through DBI and DBD::Pg.

Blob bodies are stored in Postgres bytea values. This keeps the backend self-contained and transactional. Very large public media services may still prefer a backend that stores blob bytes outside the metadata database.

This backend serializes uploads and deletes for the same hash with a transaction-level PostgreSQL advisory lock. The lock is released when the transaction commits or rolls back. Direct SQL writes to the backend tables do not participate in this locking protocol. Operations for different hashes may run concurrently.

CONSTRUCTOR

new

my $storage = Net::Blossom::Server::Backend::Postgres->new(
    dsn      => $dsn,
    username => $username,
    password => $password,
    base_url => $url,
);

Creates a storage object. dsn is a DBI Postgres data source string. username and password are optional and are passed to DBI->connect. base_url is the public HTTP or HTTPS URL prefix used when descriptors are created. It may include a path prefix, but not userinfo, query, or fragment parts. Trailing slashes are removed.

Instead of dsn, callers may pass an existing DBI handle as dbh. The handle must be a Postgres handle.

Optional connect_attrs may be supplied with dsn. The backend always forces AutoCommit, RaiseError, PrintError, and pg_enable_utf8 to values needed by the storage implementation.

METHODS

dbh

my $dbh = $storage->dbh;

Returns the DBI handle used by the backend.

base_url

my $url = $storage->base_url;

Returns the normalized descriptor URL prefix.

deploy_schema

$storage->deploy_schema;

Creates the required Postgres tables and indexes if they do not already exist. This method is safe to call more than once.

begin_upload

my $upload = $storage->begin_upload(%context);

Starts a blob upload and returns an upload writer. The server core writes bytes to the writer and later calls commit with validated blob metadata.

get_blob

my $result = $storage->get_blob($sha256);

Returns a Net::Blossom::Server::BlobResult for $sha256, or undef when the blob is absent.

head_blob

my $descriptor = $storage->head_blob($sha256);

Returns a Net::Blossom::BlobDescriptor without returning the blob body, or undef when the blob is absent.

delete_blob

my $deleted = $storage->delete_blob($sha256, pubkey => $pubkey);

Deletes one owner relationship when pubkey is supplied. The blob bytes are deleted when the final owner is removed. Without pubkey, the blob and all owners are deleted.

list_blobs

my $descriptors = $storage->list_blobs($pubkey, limit => 100);

Returns descriptors owned by $pubkey, sorted by uploaded descending and sha256 ascending. cursor and limit follow the Net::Blossom::Server::Storage contract.