/ 
SPVM-DBI-0.003
/ SPVM::DBI::Dr

Name

SPVM::DBI::Dr - Driver Handle

Description

DBI::Dr class in SPVM represents a driver handle.

This class is a base class for database driver handles, and each method is expected to be overridden in child classes like DBD::SQLite::Dr.

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.

Instance Methods

connect

method connect : DBI::Db ($ctx : Go::Context, $dsn : string, $user : string = undef, $password : string = undef, $options : object[] = undef)

Establishes a connection to the database specified by the $dsn and returns a database handle (DBI::Db).

The following options can be specified in $options.

  • ConnectTimeoutDurationNsec

    The maximum time to wait for the database connection to be established, specified in nanoseconds.

  • TCPNoDelay

    A boolean value (0 or 1) to disable Nagle's algorithm. Set to 1 to reduce latency for small packets by sending them immediately.

  • SocketKeepAliveDurationNsec

    The interval for TCP keep-alive probes, specified in nanoseconds. This is useful for maintaining long-lived connections through firewalls or load balancers.

  • IdleTimeoutDurationNsec

    The duration a connection can remain idle before it is considered expired and closed by the driver, specified in nanoseconds.

  • InactiveDestroy

    A boolean value. If set to 1, the disconnect method will not be called automatically when the database handle object is destroyed.

connect_common

protected method connect_common : void ($dbh : DBI::Db, $ctx : Go::Context, $dsn : string, $user : string = undef, $password : string = undef, $options : object[] = undef)

Provides common initialization logic for a database handle, such as parsing the DSN and mapping options to fields.

option_names

protected method option_names : string[] ()

Returns an array of supported option names for the database handle.

For Driver Authors

Extending DBI::Dr

The following example shows how to implement a specific database driver (DBD) by extending the DBI::Dr class.

class DBD::MyDriver::Dr extends DBI::Dr {
  
  # Overriding the connect method
  method connect : DBI::Db ($ctx : Go::Context, $dsn : string, $user : string = undef, $password : string = undef, $options : object[] = undef) {
    
    my $dbh = DBD::MyDriver::Db->new;
    
    # Call the common connection logic provided by the base class.
    # This validates options and stores them into the database handle ($dbh).
    $self->connect_common($dbh, $ctx, $dsn, $user, $password, $options);
    
    # Implement the driver-specific logic to connect to a database.
    # Apply network-related settings using the values stored in $dbh.
    # ...
    
    return $dbh;
  }
  
}

Abstract Methods

The following method is intended to be overridden in child classes. If it is not overridden, it throws a DBI::Error::SQLState exception with SQLSTATE "IM001" (Driver does not support this function):

"connect".

Implementing connect

When implementing "connect", driver authors are responsible for the following:

  • Option Validation: Call "connect_common" to validate and store options in the DBI::Db instance.

  • Network Settings: Apply TCPNoDelay (TCP_NODELAY), ConnectTimeoutDurationNsec (dialer deadline), and SocketKeepAliveDurationNsec (TCP keep-alive) to the actual socket.

  • Modern Defaults: If network options are not provided in $options, call apply_modern_tcp_settings from IO::Socket to ensure optimized default behavior.

  • Idle Management: Use IdleTimeoutDurationNsec to set the timeout of the IO::Socket to prevent resource leaks.

  • Handle Cleanup: Ensure the InactiveDestroy value is correctly set in the database handle so that DESTROY behaves as expected.

How to use connect_common

This method provides common initialization logic for a database handle. It is intended to be called by driver authors within their connect implementation.

It performs the following tasks:

  1. Validates the option names in $options using option_names.

  2. Parses the DSN to extract the database name and username.

  3. Sets the AutoCommit field of $dbh to 1.

  4. Maps values from $options to the corresponding fields in $dbh (e.g., InactiveDestroy, TCPNoDelay, and various timeout durations).

Overriding option_names

Returns an array of supported option names for the database handle. In the base class, this returns default options like InactiveDestroy, TCPNoDelay, and several *DurationNsec options.

Driver authors can override this method to add driver-specific options. These names are used by "connect_common" or prepare_common via Fn#check_option_names.

See Also

DBI, DBI::Db, Go::Context

Repository

https://github.com/yuki-kimoto/SPVM-DBI

Author

Yuki Kimoto kimoto.yuki@gmail.com

Copyright & License

Copyright (c) 2026 Yuki Kimoto

MIT License