tdbc::connection(3tcl)

💖 tdbc::connection — the TDBC connection object, bestie edition 💖

tdbc::connection (3tcl) · from the Tcl Database Connectivity manual

okay so. you know how Tcl talks to databases and it's all very serious and grown-up? yeah, this is that. a connection object is literally your little golden ticket to a database, and once you have one you can do all the things — run statements, peek at tables, do transactions, the whole vibe. 🎀

---

✨ NAME ✨

tdbc::connection — the TDBC connection object 🫶

---

✨ SYNOPSIS ✨

first you gotta pull in the packages, no skips:

package require tdbc 1.0
package require tdbc::driver version

then you make a connection. this is the moment, main character energy:

tdbc::driver::connection create db ?-option value...?

and once db exists, here's every single thing it can do. the whole menu, not a single item skipped:

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

---

ok bestie that's the shape of it — all of those subcommands are coming up with the full tea in the next part, so don't go anywhere. 🌸

✨ DESCRIPTION ✨

okay so bestie, gather round 💖 every single database driver for TDBC (Tcl DataBase Connectivity) implements a connection object that's literally a whole connection to a database. By convention, this object gets created by the command tdbc::driver::connection create. That command takes the name of a Tcl command that will represent the connection, plus a possible set of options (peep CONFIGURATION OPTIONS for those). It establishes the connection to the database and returns the name of the newly-created Tcl command. No cap. 🫶

---

the configure object command

If you hit configure on a database connection with no arguments, it returns a list of alternating keywords and values representing the connection's current configuration. If you give it a single argument -option, it returns the configured value of that given option. Otherwise, it must be given an even number of arguments that alternate options and values. The specified options receive the specified values, and nothing is returned. 💅

the close object command

close 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. It's giving cleanup era ✨

the prepare object command

prepare 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 a more detailed discussion of the SQL accepted by the prepare object command and the interface accepted by a statement. 🎀

the preparecall object command

On a database connection where the underlying database and driver support stored procedures, preparecall 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

statements 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

resultsets 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

tables lets the program 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 "and and" is literally in the original bestie, we don't make the rules)

the columns object command

columns lets the program 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 primarykeys object command

primarykeys lets the program 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. 🧚

• tableCatalog — Name of the catalog in which the table appears.
• tableSchema — Name of the schema in which the table appears.
• tableName — Name of the table owning the primary key.
• constraintCatalog — 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.
• constraintSchema — 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.
• constraintName — Name of the primary key constraint,
• columnName — Name of a column that is a member of the primary key.
• ordinalPosition — 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

foreignkeys lets the program 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. 💜

• foreignConstraintCatalog — Catalog in which the foreign key constraint appears.
• foreignConstraintSchema — Schema in which the foreign key constraint appears.
• foreignConstraintName — Name of the foreign key constraint.
• primaryConstraintCatalog — Catalog holding the primary key constraint (or unique key constraint) on the column to which the foreign key refers.
• primaryConstraintSchema — Schema holding the primary key constraint (or unique key constraint) on the column to which the foreign key refers.
• primaryConstraintName — Name of the primary key constraint (or unique key constraint) on the column to which the foreign key refers.
• updateAction — Action to take when an UPDATE statement invalidates the constraint. The value will be CASCADE, SET DEFAULT, SET NULL, RESTRICT, or NO ACTION.
• deleteAction — Action to take when a DELETE statement invalidates the constraint. The value will be CASCADE, SET DEFAULT, SET NULL, RESTRICT, or NO ACTION.
• primaryCatalog — Catalog name in which the primary table (the one to which the foreign key refers) appears.
• primarySchema — Schema name in which the primary table (the one to which the foreign key refers) appears.
• primaryTable — Table name of the primary table (the one to which the foreign key refers).
• primaryColumn — Name of the column to which the foreign key refers.
• foreignCatalog — Name of the catalog in which the table containing the foreign key appears.
• foreignSchema — Name of the schema in which the table containing the foreign key appears.
• foreignTable — Name of the table containing the foreign key.
• foreignColumn — Name of the column appearing in the foreign key.
• ordinalPosition — Position of the column in the foreign key, if the key is a compound key.

the begintransaction object command

begintransaction 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 without an intervening commit or rollback command, an error is returned unless the underlying database supports nested transactions. ⚠️

the commit object command

commit on a database connection ends the most recent transaction started by begintransaction and commits changes to the database. 💖

the rollback object command

rollback 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

transaction 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

allrows 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

foreach 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. 🌈

🎀 CONFIGURATION OPTIONS 🎀

okay so bestie, these are the options you can pass when you create the connection, and also the ones that work on the connection's configure object command. this list is not exhaustive — your database driver might have its own extra special options too, iykyk 💅

• -encoding name — picks the encoding used to connect to the database. the name should be one of the names that the encoding command accepts. ngl you usually don't need this one at all; most database drivers are smart enough to figure out the encoding on their own ✨
• -isolation level — sets the transaction isolation level you need for transactions on this database. all the acceptable values for level are listed down in TRANSACTION ISOLATION LEVELS, keep scrolling 🌸
• -timeout ms — the max time to wait for a database engine operation before it reports an error back to whoever called it. ms is in milliseconds, fr fr. a value of zero — which is the default — means the calling process just waits forever for database operations 😭
• -readonly flag — says whether this connection will modify the database (if the Boolean flag is true) or that it may modify it (if flag is false). if flag is true, this option may have the side effect of raising the transaction isolation level up to readonly 👑

---

🔒 TRANSACTION ISOLATION LEVELS 🔒

the values you can hand to the -isolation configuration option are literally these:

• readuncommitted — lets the transaction read "dirty" data, aka data that hasn't been committed yet. 💀 this one may compromise data integrity, does not guarantee that foreign keys or uniqueness constraints are satisfied, and in general does not guarantee data consistency. be careful bestie.
• readcommitted — forbids the transaction from reading "dirty" data, but does not guarantee repeatable reads. so if a transaction reads a row of a database at a given time, there's no guarantee that same row will still be there later in the same transaction 🙈
• repeatableread — guarantees that any row of the database, once it's been read, will have the same values for the whole life of a transaction. still permits "phantom reads" though — that's where newly-added rows show up if you query a table a second time 👻
• serializable — the most restrictive and the most expensive level of transaction isolation. any query to the database, if repeated, returns precisely the same results for the life of the transaction, exactly as if this transaction is the only user of the database. main character energy, honestly 🫶
• readonly — behaves like serializable in that the only results visible to the transaction are the ones committed before the transaction started, but it also forbids the transaction from modifying the database. look but don't touch 💅

so here's the tea: a database that doesn't implement one of these isolation levels will instead use the next more restrictive isolation level. and if the given level of isolation can't be obtained at all, the database interface throws an error reporting that fact. the default isolation level is readcommitted.

⚠️ a script should not be setting the isolation level while a transaction is in progress. just don't. it's giving chaos 😭

---

👀 SEE ALSO 👀

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

---

⭐ KEYWORDS ⭐

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

---

💖 COPYRIGHT 💖

Copyright (c) 2008 by Kevin B. Kenny.

---

and that's a wrap on this one, bestie 🎀 this was the Tcl 8.6 era tdbc::connection(3tcl) page — go forth and connect responsibly, ily, mwah 💜✨