Tdbc Documentation > TDBC > tdbc_connection

Tcl Database Connectivity | TDBC-ODBC Bridge | TDBC driver for Sqlite3 | TDBC driver for Mysql

NAME
tdbc::connection - TDBC connection object
SYNOPSIS
DESCRIPTION
type
precision
scale
nullable
CONFIGURATION OPTIONS
-encoding name
-isolation level
-timeout ms
-readonly flag
TRANSACTION ISOLATION LEVELS
readuncommitted
readcommitted
repeatableread
serializable
readonly
SEE ALSO
KEYWORDS
COPYRIGHT

NAME

tdbc::connection - TDBC connection object

SYNOPSIS

package require tdbc 1.0
package require tdbc::driver version
tdbc::driver::connection create db ?-option value...?
db configure ?-option value...?
db close
db prepare sql-code
db preparecall call
db statements
db resultsets
db tables ?pattern?
db columns table ?pattern?
db begintransaction
db commit
db rollback
db transaction script
db allrows ?-as lists|dicts? ?-columnsvariable name? ?--? sql-code ?dictionary?
db foreach ?-as lists|dicts? ?-columnsvariable name? ?--? sql-code ?dictionary? varName script

DESCRIPTION

Every database driver for TDBC (Tcl DataBase Connectivity) implements a connection object that represents a connection to a database. By convention, this object is created by the command, tdbc::driver::connection create. This command accepts the name of a Tcl command that will represent the connection and a possible set of options (see CONFIGURATION OPTIONS). It establishes a connection to the database and returns the name of the newly-created Tcl command.

The configure object command on a database connection, if presented with no arguments, returns a list of alternating keywords and values representing the connection's current configuration. If presented with a single argument -option, it returns the configured value of the given option. Otherwise, it must be given an even number of arguments which are alternating options and values. The specified options receive the specified values, and nothing is returned.

The close object command on a database connection closes the connection. All active statements and result sets on the connection are closed. Any uncommitted transaction is rolled back. The object command is deleted.

The prepare object command on a database connection prepares a SQL statement for execution. The sql-code argument must contain a single SQL statement to be executed. Bound variables may be included. See SQL STATEMENTS for a further description of the SQL that is accepted by this command. The return value is a newly-created Tcl command that represents the statement. See tdbc_statement(n) for the interface accepted by a statement.

On a database connection where the underlying database and driver support stored procedures, the preparecall object command prepares a call to a stored procedure for execution. The syntax of the stored procedure call is:

?resultvar =? procname(?arg ?, arg...?)

The return value is a newly-created Tcl command that represents the statement. See tdbc_statement(n) for the interface accepted by a statement.

The statements object command returns a list of statements that have been created by prepare and preparecall statements against the given connection and have not yet been closed.

The resultsets object command returns a list of result sets that have been obtained by executing statements prepared using the given connection and not yet closed.

The tables object command allows the program to query the connection for the names of tables that exist in the database. The optional pattern parameter is a pattern to match the name of a table. It may contain the SQL wild-card characters '%' and and whose values are subdictionaries. See the documentation for the individual database driver for the interpretation of the values.

The columns object command allows the program to query the connection for the names of columns that exist in a given table. The optional pattern parameter is a pattern to match the name of a column. It may contain the SQL wild-card characters '%' and and whose values are dictionaries. Each of the subdictionaries will contain at least the following keys and values (and may contain others whose usage is determined by a specific database driver).

type
Contains the data type of the column, and will generally be chosen from the set, bigint, binary, bit, char, date, decimal, double, float, integer, longvarbinary, longvarchar, numeric, real, time, timestamp, smallint, tinyint, varbinary, and varchar. (If the column has a type that cannot be represented as one of the above, type will contain a driver-dependent description of the type.)

precision
Contains the precision of the column in bits, decimal digits, or the width in characters, according to the type.

scale
Contains the scale of the column (the number of digits after the radix point), for types that support the concept.

nullable
Contains 1 if the column can contain NULL values, and 0 otherwise.

The starttransaction object command on a database connection begins a transaction on the database. If the underlying database does not support atomic, consistent, isolated, durable transactions, the starttransaction object command returns an error reporting the fact. Similarly, if multiple starttransaction commands are executed withough an intervening commit or rollback command, an error is returned unless the underlying database supports nested transactions.

The commit object command on a database connection ends the most recent transaction started by starttransaction and commits changes to the database.

The rollback object command on a database connection rolls back the most recent transaction started by starttransaction. The state of the database is as if nothing happened during the transaction.

The transaction object command on a database connection presents a simple way of bundling a database transaction. It begins a transaction, and evaluates the supplied script argument as a Tcl script in the caller's scope. If script terminates normally, or by break, continue, or return, the transaction is committed (and any action requested by break, continue, or return takes place). If the evaluation of script ends with an error, the transaction is rolled back and the error is rethrown. Any other return code is treated similarly to break, continue, or return.

The allrows object command prepares a SQL statement (given by the sql-code parameter) to execute against the database. It then executes it (see tdbc_statement(n) for details) with the optional dictionary parameter giving bind variables. Finally, it uses the allrows object command on the result set (see tdbc_resultset(n)) to construct a list of the results. Finally, both result set and statement are closed. The return value is the list of results.

The foreach object command prepares a SQL statement (given by the sql-code parameter) to execute against the database. It then executes it (see tdbc_statement(n) for details) with the optional dictionary parameter giving bind variables. Finally, it uses the foreach object command on the result set (see tdbc_resultset(n)) to evaluate the given script for each row of the results. Finally, both result set and statement are closed, even if the given script results in a return, an error, or an unusual return code.

CONFIGURATION OPTIONS

The configuration options accepted when the connection is created and on the connection's configure object command include the following, and may include others specific to a database driver.

-encoding name
Specifies the encoding to be used in connecting to the database. The name should be one of the names accepted by the encoding(n) command. This option is usually unnecessary; most database drivers can figure out the encoding in use by themselves.

-isolation level
Specifies the transaction isolation level needed for transactions on the database. The acceptable values for level are shown under TRANSACTION ISOLATION LEVELS.

-timeout ms
Specifies the maximum time to wait for a an operation database engine before reporting an error to the caller. The ms argument gives the maximum time in milliseconds. A value of zero (the default) specifies that the calling process is to wait indefinitely for database operations.

-readonly flag
Specifies that the connection will not modify the database (if the Boolean parameter flag is true), or that it may modify the database (if flag is false). If flag is true, this option may have the effect of raising the transaction isolation level to readonly.

TRANSACTION ISOLATION LEVELS

The acceptable values for the -isolation configuration option are as follows:

readuncommitted
Allows the transaction to read "dirty", that is, uncommitted data. This isolation level may compromise data integrity, does not guarantee that foreign keys or uniqueness constraints are satisfied, and in general does not guarantee data consistency.

readcommitted
Forbids the transaction from reading "dirty" data, but does not guarantee repeatable reads; if a transaction reads a row of a database at a given time, there is no guarantee that the same row will be available at a later time in the same transaction.

repeatableread
Guarantees that any row of the database, once read, will have the same values for the life of a transaction. Still permits "phantom reads" (that is, newly-added rows appearing if a table is queried a second time).

serializable
The most restrictive (and most expensive) level of transaction isolation. Any query to the database, if repeated, will return precisely the same results for the life of the transaction, exactly as if the transaction is the only user of the database.

readonly
Behaves like serializable in that the only results visible to the transaction are those that were committed prior to the start of the transaction, but forbids the transaction from modifying the database.

A database that does not implement one of these isolation levels will instead use the next more restrictive isolation level. If the given level of isolation cannot be obtained, the database interface throws an error reporting the fact. The default isolation level is readcommitted.

A script should not the isolation level when a transaction is in progress.

SEE ALSO

encoding, tdbc, tdbc::resultset, tdbc::statement, tdbc::tokenize

KEYWORDS

TDBC, SQL, database, connectivity, connection, resultset, statement

COPYRIGHT

Copyright (c) 2008 by Kevin B. Kenny.