tdbc::mysql(3tcl)

💖 tdbc::mysql — the TDBC-MYSQL bridge, bestie edition 💖

manual page: tdbc::mysql(3tcl) — part of Tcl Database Connectivity. Sit down, grab a strawberry 🍓, we're doing databases.

---

✨ NAME ✨

tdbc::mysql — the TDBC-MYSQL bridge, aka the lil' friendship bracelet between Tcl and MySQL 🫶

---

🌈 SYNOPSIS 🌈

package require tdbc::mysql 1.0

tdbc::mysql::connection create db ?-option value...?
tdbc::mysql::connection new ?-option value...?

tdbc::mysql::datasources ?-system|-user?

tdbc::mysql::drivers

tdbc::mysql::datasource command driverName ?keyword-value?...

---

🦋 DESCRIPTION 🦋

okay so the tdbc::mysql driver hands you a database interface that conforms to Tcl DataBase Connectivity (TDBC), and it lets a Tcl script connect to a MySQL database. that's the whole vibe. 💅

You establish a connection to a MySQL database by invoking tdbc::mysql::connection create, and you pass it the name you wanna give the database handle plus a set of -option-value pairs. (yes, exactly like that, dashes and all — we do not improvise here.) All the available options are listed under CONNECTION OPTIONS below, so scroll, bestie. As an alternative, tdbc::mysql::connection new creates a database connection with an automatically assigned name. The return value from tdbc::mysql::connection new is the name that was chosen for the connection handle — so if you didn't pick it, it tells you what it picked. iconic. ✨

The side effect of tdbc::mysql::connection create is to create a new database connection. (that's it. that's the side effect.) See tdbc::connection(3tcl) for the details of how to use the connection to manipulate a database — because the connection object itself has lore, and that lore lives over there.

---

🎀 CONNECTION OPTIONS 🎀

The tdbc::mysql::connection create object command supports the -encoding, -isolation, -readonly and -timeout options common to all TDBC drivers. Two of those have Opinions:

• The -encoding option will always fail unless the encoding is utf-8 — the database connection always uses UTF-8 encoding so it can transfer arbitrary Unicode characters. no cap.
• The -readonly option must be 0, because MySQL does not offer read-only connections. like, it's just not a thing MySQL does. 😭

In addition, the following options are recognized:

• -host hostname — Connects to the host specified by hostname. This option must be set on the initial creation of the connection; it cannot be changed after connecting. Default is to connect to the local host. 🏠
• -port number — Connects to a MySQL server listening on the port specified by number. This option may not be changed after connecting. It is used only when host is specified and is not localhost.
• -socket path — Connects to a MySQL server listening on the Unix socket or named pipe specified by path. This option may not be changed after connecting. It is used only when -host is not specified or is localhost.
• -user name — Presents name as the user name to the MySQL server. Default is the current user ID.
• -passwd password —
• -password password — These two options are synonymous. They present the given password as the user's password to the MySQL server. Default is not to present a password. 🔐
• -database name —
• -db name — These two options are synonymous. They present the given name as the name of the default database to use in MySQL queries. If not specified, the default database for the current user is used.
• -interactive flag — The flag value must be a Boolean value. If it is true (or any equivalent), the default timeout is set for an interactive user; otherwise, the default timeout is set for a batch user. This option is meaningful only on initial connection. When using the configure method on a MySQL connection, use the -timeout option to set the timeout desired. 👀
• -ssl_ca string —
• -ssl_capath string —
• -ssl_cert string —
• -ssl_cipher string —
• -ssl_key string — These five options set the certificate authority, certificate authority search path, SSL certificate, transfer cipher, and SSL key to the given string arguments. These options may be specified only on initial connection to a database, not in the configure method of an existing connection. Default is not to use SSL. 🔒

---

🍓 EXAMPLES 🍓

tdbc::mysql::connection -user joe -passwd sesame -db joes_database

Connects to the MySQL server on the local host using the default connection method, presenting user ID 'joe' and password 'sesame'. Uses 'joes_database' as the default database name. slay. 👑

---

💜 ADDITIONAL CONNECTION METHODS 💜

In addition to the usual methods on the tdbc::connection(3tcl) object, connections to a MySQL database support one additional method:

• $connection evaldirect sqlStatement — This method takes the given sqlStatement and interprets it as MySQL native SQL code and evaluates it without preparing it. The statement may not contain variable substitutions. The result set is returned as a list of lists, with each sublist being the list of columns of a result row formatted as character strings. Note that the string formatting is done by MySQL and not by Tcl, so details like the appearance of floating point numbers may differ. This command is not recommended for anything where the usual prepare or preparecall methods work correctly. It is provided so that data management language statements that are not implemented in MySQL's prepared statement API — such as CREATE DATABASE or CREATE PROCEDURE — can be executed. (iykyk, sometimes you just gotta go direct. 💀)

---

🌸 SEE ALSO 🌸

• tdbc(3tcl)
• tdbc::connection(3tcl)
• tdbc::resultset(3tcl)
• tdbc::statement(3tcl)

---

⭐ KEYWORDS ⭐

TDBC, SQL, MySQL, database, connectivity, connection

---

🧚 COPYRIGHT 🧚

Copyright (c) 2009 by Kevin B. Kenny.

---

okay that's the whole page bestie, you ate 💅✨ — this was the tdbc::mysql(3tcl) manual page, living in the Tcl source, version 8.6. mwah, go connect to something. 🎀🦋