Name
SPVM::DBI::Db - Database Handle
Description
DBI::Db class in SPVM represents a database handle.
This class is a base class for database handles, and each method is expected to be overridden in child classes like DBI::Db::SQLite.
Note that this class is intended for driver authors. General users should not use this class directly; instead, use the DBI class to establish a connection.
Usage
The following example shows how to prepare a statement and manage transactions using a database handle (DBI::Db).
use DBI::Db;
use DBI::St;
use Go::Context;
my $ctx = Go::Context->new;
# Assuming $dbh is already obtained via DBI->connect
# 1. Prepare a statement
my $sth = $dbh->prepare($ctx, "SELECT * FROM users WHERE id = ?");
# 2. Transaction management
eval {
$dbh->begin_work($ctx);
# ... execute statements ...
$dbh->commit($ctx);
};
if ($@) {
$dbh->rollback($ctx);
}
# 3. Disconnect explicitly
$dbh->disconnect;Fields
Name
has Name : ro string;
The data source name (DSN). This field stores the part of the DSN after the second colon (e.g., "dbname=:memory:" if the DSN is "dbi:SQLite:dbname=:memory:").
Username
has Username : ro string;
The username for the database connection. This field stores the username extracted from the DSN.
AutoCommit
has AutoCommit : ro byte;
The AutoCommit status.
InactiveDestroy
has InactiveDestroy : rw byte;
The InactiveDestroy status.
IdleTimeoutDurationNsec
has IdleTimeoutDurationNsec : rw long;
The maximum duration that a connection can remain idle, in nanoseconds.
ConnectTimeoutDurationNsec
has ConnectTimeoutDurationNsec : rw long;
The timeout value for establishing a new database connection, in nanoseconds.
ReadTimeoutDurationNsec
has ReadTimeoutDurationNsec : rw long;
The timeout value for read operations, in nanoseconds.
WriteTimeoutDurationNsec
has WriteTimeoutDurationNsec : rw long;
The timeout value for write operations, in nanoseconds.
SocketKeepAliveDurationNsec
has SocketKeepAliveDurationNsec : rw long;
The duration for TCP keep-alive idle time, in nanoseconds.
TCPNoDelay
has TCPNoDelay : rw byte;
The TCP_NODELAY status (boolean 1 or 0).
Instance Methods
prepare
method prepare : DBI::St ($ctx : Go::Context, $sql : string, $options : object[] = undef)
Prepares the SQL statement and returns a statement handle (DBI::St).
begin_work
method begin_work : void ($ctx : Go::Context)
Starts a new transaction.
commit
method commit : void ($ctx : Go::Context)
Commits the current transaction.
rollback
method rollback : void ($ctx : Go::Context)
Rolls back the current transaction.
last_insert_id
method last_insert_id : object ($ctx : Go::Context, $catalog : string = undef, $schema : string = undef, $table : string = undef, $field : string = undef, $options : object[] = undef)
Returns the ID of the last inserted row.
ping
method ping : int ($ctx : Go::Context)
Checks if the database connection is still alive.
get_info
method get_info : object ($ctx : Go::Context, $info_type : int)
Returns information about the database.
table_info
method table_info : DBI::St ($ctx : Go::Context, $catalog : string, $schema : string, $table : string, $type : string, $options : object[] = undef)
Returns a statement handle containing information about tables.
column_info
method column_info : DBI::St ($ctx : Go::Context, $catalog : string, $schema : string, $table : string, $column : string)
Returns a statement handle containing information about columns.
quote
method quote : string ($ctx : Go::Context, $str : string, $type : int = -1)
Quotes a string for use in a SQL statement.
quote_identifier
method quote_identifier : string ($ctx : Go::Context, $catalog : string, $schema : string, $table : string, $options : object[] = undef)
Quotes an identifier for use in a SQL statement.
disconnect
method disconnect : void ()
Disconnects from the database.
prepare_common
protected method prepare_common : void ($sth : DBI::St, $ctx : Go::Context, $sql : string, $options : object[] = undef)
Provides common initialization logic for a statement handle.
option_names
protected method option_names : string[] ()
Returns the valid option names for this database handle.
DESTROY
method DESTROY : void ()
The destructor. Unless "InactiveDestroy" is true, it calls "disconnect".
For Driver Authors
Extending DBI::Db
The following example shows how to implement a specific database handle (DBD) by extending the DBI::Db class.
class DBD::MyDriver::Db extends DBI::Db {
# Overriding the prepare method
method prepare : DBI::St ($ctx : Go::Context, $sql : string, $options : object[] = undef) {
my $sth = DBD::MyDriver::St->new;
# Call the common preparation logic provided by the base class.
$self->prepare_common($sth, $ctx, $sql, $options);
# Implement the driver-specific logic to prepare a statement.
# ...
return $sth;
}
}Abstract Methods
The following methods are intended to be overridden in child classes. If a method is not overridden, it throws a DBI::Error::SQLState exception with SQLSTATE "IM001" (Driver does not support this function):
"prepare", "begin_work", "commit", "rollback", "last_insert_id", "ping", "get_info", "table_info", "column_info", "quote", "quote_identifier", "disconnect".
Implementing prepare
When implementing "prepare", driver authors should:
Call prepare_common: Use "prepare_common" to validate options and perform common initialization tasks.
Handle Driver Defaults: Ensure that initial states (like
AutoCommitdefaulting to 1) are respected in the underlying database connection.
How to use prepare_common
This method provides common initialization logic for a statement handle. It validates the option names in $options using "option_names" and performs other shared setup tasks. Driver authors are expected to call this method within their prepare implementation.
Overriding option_names
Override this method if your database handle supports specific options. These names are used by "prepare_common" to validate the options passed by the user.
See Also
Repository
https://github.com/yuki-kimoto/SPVM-DBI
Author
Yuki Kimoto kimoto.yuki@gmail.com
Copyright & License
Copyright (c) 2026 Yuki Kimoto
MIT License