/ 
DBD-BigQuery-0.01
/ DBD::BigQuery

NAME

DBD::BigQuery - Perl DBI Driver for Google Cloud BigQuery with Non-Blocking Async Support

SYNOPSIS

use DBI;

# Standard Connection (REST default transport)
my $dbh = DBI->connect(
    'dbi:BigQuery:project=my-project;dataset=my_dataset',
    '', '', { RaiseError => 1, AutoCommit => 1 }
);

# gRPC (Storage Read API) Connection
my $dbh_grpc = DBI->connect(
    'dbi:BigQuery:project=my-project;dataset=my_dataset;transport=grpc',
    '', ''
);

# Connection Health Check
$dbh->ping();

# Asynchronous Non-Blocking Query
my $sth = $dbh->prepare('SELECT id, data FROM my_table WHERE active = ?', { Async => 1 });
my $rv  = $sth->execute(1);

if ($rv eq '0E0') {
    # Event loop integration via socket / file descriptor fileno
    my $fd = $sth->fileno();
    
    while ($sth->FETCH('AsyncWantRead')) {
        if ($sth->async_read_ready()) {
            my $row = $sth->fetch_async_row();
            last if !defined $row;
            print "Record ID: $row->[0], Payload: $row->[1]\n";
        }
    }
}

# Transaction Management
$dbh->begin_work();
$dbh->do('INSERT INTO my_table (id, data) VALUES (500, "sample")');
$dbh->commit();

# Bulk Tuple Batch Execution via Storage Write API
my $sth_batch = $dbh->prepare('INSERT INTO logs (id, event) VALUES (?, ?)');
$sth_batch->bind_param_array(1, [100, 200, 300]);
$sth_batch->bind_param_array(2, ['ingest', 'transform', 'export']);
my $tuples = $sth_batch->execute_array({ ArrayTupleStatus => [] });

DESCRIPTION

DBD::BigQuery provides a full-featured Perl DBI driver for Google Cloud BigQuery. It supports synchronous and non-blocking asynchronous queries, REST and gRPC (Storage Read API) transports, transaction boundaries, bulk batch tuple execution, and Information Schema catalog metadata queries.

CONNECTING

DSN Syntax

dbi:BigQuery:project=PROJECT_ID;dataset=DATASET_ID

Transport Options

Cloud BigQuery supports both REST (HTTP/1.1) and gRPC / Storage Read API transports.

  • REST (Default): Standard HTTP REST transport via JSON APIs.

    dbi:BigQuery:project=P;dataset=D;transport=rest

  • gRPC: High-speed columnar streaming transport via BigQuery Storage Read API.

    dbi:BigQuery:project=P;dataset=D;transport=grpc

Environment Variables

  • BIGQUERY_PROJECT: Default GCP Project ID if omitted from DSN.

  • BIGQUERY_DATASET: Default BigQuery Dataset ID if omitted from DSN.

  • BIGQUERY_TRANSPORT: Transport override (rest or grpc).

  • GOOGLE_APPLICATION_CREDENTIALS: Path to service account JSON key file.

BLOCKING VS NON-BLOCKING OPERATIONS

DBD::BigQuery supports both standard synchronous (blocking) operations and non-blocking asynchronous operations.

1. Synchronous (Blocking) Operations (Default)

By default, calls to execute() block execution until the SQL query completes and result rows are returned from Cloud BigQuery:

my $sth = $dbh->prepare('SELECT id, data FROM my_table WHERE active = ?');
$sth->execute(1);  # Blocks until query completes!

while (my $row = $sth->fetchrow_arrayref()) {
    print "Record ID: $row->[0], Data: $row->[1]\n";
}

2. Asynchronous (Non-Blocking) Operations

To execute queries without blocking the Perl main thread or event loop, pass { Async = 1 }> to prepare(). execute() returns immediately with status '0E0' without blocking:

my $sth = $dbh->prepare('SELECT id, data FROM my_table WHERE active = ?', { Async => 1 });
my $rv  = $sth->execute(1);  # Returns '0E0' immediately without blocking!

if ($rv eq '0E0') {
    # File descriptor for IO::Select / EV event loops
    my $fd = $sth->fileno();

    # Poll non-blocking handle
    while ($sth->FETCH('AsyncWantRead')) {
        if ($sth->async_read_ready()) {
            my $row = $sth->fetch_async_row();
            last if !defined $row;
            print "Record ID: $row->[0], Data: $row->[1]\n";
        }
    }
}

ASYNCHRONOUS NON-BLOCKING OPERATIONS

DBD::BigQuery supports non-blocking execution via DBI's Async attribute.

Handle Methods

  • $sth-fileno()>: Returns the socket/channel file descriptor for IO::Select / EV event loops.

  • $sth-FETCH('AsyncWantRead')>: Returns true while waiting for server response bytes.

  • $sth-async_read_ready()>: Polls non-blocking socket state.

  • $sth-fetch_async_row()>: Non-blocking fetch of the next result tuple.

METADATA & CATALOG METHODS

  • $dbh-table_info($catalog, $schema, $table, $type)>

  • $dbh-column_info($catalog, $schema, $table, $column)>

  • $dbh-primary_key_info($catalog, $schema, $table)>

SEE ALSO

DBI, DBD::Spanner, Google::Cloud::Bigquery::V2, Google::Cloud::BigQuery::Storage::V1