/ 
SPVM-DBI-0.003
/ SPVM::DBI::St

Name

SPVM::DBI::St - Statement Handle

Description

DBI::St class in SPVM represents a statement handle. This class is a base class for statement handles, and each method is expected to be overridden in child classes like DBI::St::SQLite.

Usage

A statement handle is typically created by calling the prepare method of a database handle (DBI::Db).

# Create a statement handle
my $sth = $dbh->prepare($ctx, "SELECT id, name FROM users WHERE id = ?");

# Execute with bind values
$sth->execute($ctx, [(object)1]);

# Fetch rows
while (my $row = $sth->fetch($ctx)) {
  my $id = $row->[0]->(int);
  my $name = $row->[1]->(string);
}

# Finish explicitly
$sth->finish;

Fields

Database

has Database : ro DBI::Db;

The database handle that created this statement handle.

Statement

has Statement : ro string;

The SQL statement string.

Instance Methods

option_names

protected method option_names : string[] ()

Returns the valid option names for this statement handle.

NUM_OF_FIELDS

method NUM_OF_FIELDS : int ($ctx : Go::Context)

Returns the number of fields (columns) in the result set.

NAME

method NAME : string[] ($ctx : Go::Context)

Returns an array of column names.

NULLABLE

method NULLABLE : int[] ($ctx : Go::Context)

Returns an array indicating if each column is nullable.

TYPE

method TYPE : int[] ($ctx : Go::Context)

Returns an array of column types.

PRECISION

method PRECISION : int[] ($ctx : Go::Context)

Returns an array of column precision values.

SCALE

method SCALE : int[] ($ctx : Go::Context)

Returns an array of column scale values.

execute

method execute : long ($ctx : Go::Context, $bind_values : object[] = undef)

Executes the prepared statement and return the number of affected rows, or -1 if unknown.

fetch

method fetch : object[] ($ctx : Go::Context, $bind_columns : object[] = undef, $ret_row : object[] = undef)

Fetches the next row of data from the result set.

Arguments:

  • $ctx : Go::Context

    The context for goroutine-like execution and cancellation.

  • $bind_columns : object[] (Optional)

    An array of objects used as persistent buffers for column values.

    • If a slot is undef, the driver creates a new object (e.g., Int, String) and stores it in this array.

    • If a slot already contains an object, the driver reuses it by updating its value (mutable update), which avoids new memory allocations.

  • $ret_row : object[] (Optional)

    An array to store the result of the current row (the pointers to objects in $bind_columns or undef for NULL).

    • If this argument is undef, the driver creates a new array for the row.

    • If an array is provided, the driver fills it and returns it.

Return Value:

Returns the fetched row as an array of objects.

  • If $ret_row was provided, that same array is returned (with updated values).

  • If $ret_row was undef, a newly allocated array is returned.

  • Returns undef when there are no more rows.

rows

method rows : long ($ctx : Go::Context)

Returns the number of rows affected by the last execute.

finish

method finish : void ()

Indicates that no more data will be fetched from this statement handle before it is prepared again or destroyed.

DESTROY

method DESTROY : void ()

The destructor. Calls "finish" method.

For Driver Authors

Extending DBI::St

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

class DBD::MyDriver::St extends DBI::St {
  
  # Overriding the execute method
  method execute : long ($ctx : Go::Context, $bind_values : object[] = undef) {
    
    # Implement the logic to execute the prepared statement.
    # Return the number of affected rows, or -1 if unknown.
    # ...
  }
  
  # Overriding the fetch method
  method fetch : object[] ($ctx : Go::Context, $bind_columns : object[] = undef, $ret_row : object[] = undef) {
    
    # Implement the logic to fetch one row.
    # Use $bind_columns and $ret_row to minimize memory allocations.
    # ...
  }
}

Overriding option_names

Returns the valid option names for this statement handle. Override this method if your statement handle supports specific options. These names are used to validate the options passed to DBI::Db#prepare_common method.

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) to indicate that the driver implementation is missing:

"NUM_OF_FIELDS", "NAME", "NULLABLE", "TYPE", "PRECISION", "SCALE", "execute", "fetch", "rows", "finish".

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