= Connection, Statement and Result =

The basic Stubbles database API is determined by three interfaces: {{{net::stubbles::rdbms::stubDatabaseConnection}}}, {{{net::stubbles::rdbms::stubDatabaseStatement}}} and {{{net::stubbles::rdbms::stubDatabaseResult}}}. This chapter will describe the purpose of each. A default implementation is provided in the {{{net::stubbles::rdbms::pdo}}} package utilizing the [http://php.net/pdo PDO] extension of PHP. Due to the nature of PDO the {{{net::stubbles::rdbms::stubDatabasePDOStatement}}} implements both {{{net::stubbles::rdbms::stubDatabaseStatement}}} and {{{net::stubbles::rdbms::stubDatabaseResult}}}. If you do not want to use PDO you can create your own implementations of the interfaces described here.

== {{{net::stubbles::rdbms::stubDatabaseConnection}}} ==

The {{{net::stubbles::rdbms::stubDatabaseConnection}}} is responsible for managing the concrete connection to the database. It takes an instance of {{{net::stubbles::rdbms::stubDatabaseConnectionData}}} as argument for the constructor, which contains all necessary information to establish the connection to the database server. See [wiki:Docs/Database/Configuration Database configuration] for how to configure this connection data objects.

The interface offers methods that can be used to query the database ({{{prepare()}}}, {{{query()}}} and {{{exec}}}) and to process transactions ({{{beginTransaction()}}}, {{{commit()}}} and {{{rollback()}}}. All methods that work directly with the connection itself are allowed to throw exceptions of type {{{stubDatabaseException}}}. While {{{exec()}}} will execute the query directly, {{{prepare()}}} will return an instance of {{{net::stubbles::rdbms::stubDatabaseStatement}}}, and {{{query()}}} an instance of {{{net::stubbles::rdbms::stubDatabaseResult}}}.

== {{{net::stubbles::rdbms::stubDatabaseStatement}}} ==

Instances of this interface allow the usage of prepared statements. The interface offers two ways of binding data to the statement: With {{{bindParam()}}} the binding will be via reference, so it is evaluated at the time when the prepared statement is executed meaning that in opposite to {{{bindValue()}}} the value of the variable at the time of execution will be used, not the value at the time when this method is called.  In opposite to {{{bindParam()}}} the method {{{bindValue()}}} will use the value as it is at the time when this method is called.

The statement can be executed with {{{execute()}}}, returning an instance of {{{net::stubbles::rdbms::stubDatabaseResult}}}. (The PDO implementation mentioned above will return itself, because the {{{net::stubbles::rdbms::pdo::stubDatabasePDOStatement}}} implements both {{{net::stubbles::rdbms::stubDatabaseStatement}}} and {{{net::stubbles::rdbms::stubDatabaseResult}}}).

Additionally the {{{clean()}}} method frees up the connection to the server so that other SQL statements may be issued, but leaves the statement in a state that enables it to be executed again.

== {{{net::stubbles::rdbms::stubDatabaseResult}}} ==

This represents the result of a select query. It offers methods to get the result values like {{{fetch()}}} which retrieves a single row, {{{fetchOne()}}} which retrieves a single column value, and {{{fetchAll()}}} which returns an array containing all result rows. To drop the result set from the database memory call {{{free()}}}.