DOKK / manpages / debian 11 / tcl8.6-tdbc / tdbc_connection.3tcl.en
tdbc::connection(3tcl) Tcl Database Connectivity tdbc::connection(3tcl) 







tdbc::connection - TDBC connection object








package require tdbc 1.0
package require tdbc::driver version
tdbc::driver::connection create db ?-option value...?
db configure ?-option value...?
db close
db foreignkeys ?-primary tableName? ?-foreign tableName?
db prepare sql-code
db preparecall call
db primarykeys tableName
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? ?--? varName sqlcode ?dictionary?
    script










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. The return value is a newly-created Tcl command that represents
    the statement. See tdbc::statement for more detailed discussion of
    the SQL accepted by the prepare object command and 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 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
    ´_´. The return value is a dictionary whose keys are
    table names 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
    ´_´. The return value is a dictionary whose keys are
    column names 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).



  

  
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.)

  

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

  

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

  

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




The primarykeys object command allows the program to query
    the connection for the primary keys belonging to a given table. The
    tableName parameter identifies the table being interrogated. The
    result is a list of dictionaries enumerating the keys (in a similar format
    to the list returned by $connection allrows -as dicts). The
    keys of the dictionary may include at least the following. Values that are
    NULL or meaningless in a given database are omitted.



  

  
Name of the catalog in which the table appears.

  

  
Name of the schema in which the table appears.

  

  
Name of the table owning the primary key.

  

  
Name of the catalog in which the primary key constraint appears. In some
      database systems, this may not be the same as the table's catalog.

  

  
Name of the schema in which the primary key constraint appears. In some
      database systems, this may not be the same as the table's schema.

  

  
Name of the primary key constraint,

  

  
Name of a column that is a member of the primary key.

  

  
Ordinal position of the column within the primary key.




To these columns may be added additional ones that are specific to
    a particular database system.


The foreignkeys object command allows the program to query
    the connection for foreign key relationships that apply to a particular
    table. The relationships may be constrained to the keys that appear in a
    particular table (-foreign tableName), the keys that refer to
    a particular table (-primary tableName), or both. At least one
    of -primary and -foreign should be specified, although some
    drivers will enumerate all foreign keys in the current catalog if both
    options are omitted. The result of the foreignkeys object command is
    a list of dictionaries, with one list element per key (in a similar format
    to the list returned by $connection allrows -as dicts). The
    keys of the dictionary may include at least the following. Values that are
    NULL or meaningless in a given database are omitted.



  

  
Catalog in which the foreign key constraint appears.

  

  
Schema in which the foreign key constraint appears.

  

  
Name of the foreign key constraint.

  

  
Catalog holding the primary key constraint (or unique key constraint) on
      the column to which the foreign key refers.

  

  
Schema holding the primary key constraint (or unique key constraint) on
      the column to which the foreign key refers.

  

  
Name of the primary key constraint (or unique key constraint) on the
      column to which the foreign key refers.

  

  
Action to take when an UPDATE statement invalidates the constraint. The
      value will be CASCADE, SET DEFAULT, SET NULL,
      RESTRICT, or NO ACTION.

  

  
Action to take when a DELETE statement invalidates the constraint. The
      value will be CASCADE, SET DEFAULT, SET NULL,
      RESTRICT, or NO ACTION.

  

  
Catalog name in which the primary table (the one to which the foreign key
      refers) appears.

  

  
Schema name in which the primary table (the one to which the foreign key
      refers) appears.

  

  
Table name of the primary table (the one to which the foreign key
    refers).

  

  
Name of the column to which the foreign key refers.

  

  
Name of the catalog in which the table containing the foreign key
    appears.

  

  
Name of the schema in which the table containing the foreign key
    appears.

  

  
Name of the table containing the foreign key.

  

  
Name of the column appearing in the foreign key.

  

  
Position of the column in the foreign key, if the key is a compound
    key.




The begintransaction 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
    begintransaction object command returns an error reporting the fact.
    Similarly, if multiple begintransaction 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 begintransaction and commits
    changes to the database.


The rollback object command on a database connection rolls
    back the most recent transaction started by begintransaction. 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 commit fails for any reason, the error in
    the commit is treated as an error in the script. In the case of an
    error in script or in the commit, the transaction is rolled back and
    the error is rethrown. Any nonstandard return code from the script causes
    the transaction to be rolled back and then is rethrown.


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 for details) with the optional
    dictionary parameter giving bind variables. Finally, it uses the
    allrows object command on the result set (see tdbc::resultset)
    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 for details) with the optional
    dictionary parameter giving bind variables. Finally, it uses the
    foreach object command on the result set (see tdbc::resultset)
    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.








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.



  

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

  

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

  

  
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.

  

  
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.








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



  

  
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.

  

  
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.

  

  
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).

  

  
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.

  

  
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.










encoding(3tcl), tdbc(3tcl), tdbc::resultset(3tcl),
    tdbc::statement(3tcl), tdbc::tokenize(3tcl)








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








Copyright (c) 2008 by Kevin B. Kenny.







  

    8.6
    Tcl