tdbc::sqlite3(3tcl)

💖 NAME 💖

tdbc::sqlite3 — the TDBC driver for the SQLite3 database manager. She lives in the Tcl Database Connectivity manual family, and she's lowkey the blueprint, no cap. ✨

---

🌸 SYNOPSIS 🌸

package require tdbc::sqlite3 1.0

tdbc::sqlite3::connection create db fileName ?-option value...?

---

🦋 DESCRIPTION 🦋

Okay so, the tdbc::sqlite3 driver hands you a database interface that conforms to Tcl DataBase Connectivity (TDBC, iykyk), and it lets a Tcl script connect to a SQLite3 database. That's the whole vibe. 💅

But here's the tea: it's also shipped as a worked example of how to write a database driver in Tcl, so that driver authors out there have an actual starting point for further development. A little "here's how it's done, bestie" moment. 🫶

You establish a connection to a SQLite3 database by invoking tdbc::sqlite3::connection create, passing it a string to be used as the connection handle, followed by the file name of the database. The side effect of tdbc::sqlite3::connection create is to create a new database connection.. (yes, that trailing double dot is canon, we don't edit the queen's handwriting)

As an alternative, tdbc::sqlite::connection new may be used to create a database connection with an automatically assigned name. The return value from tdbc::sqlite::connection new is the name that was chosen for the connection handle. 🎀

And if you wanna know the details of how to actually use that connection to manipulate a database, go read tdbc::connection(3tcl). Go on, she's right there. ⭐

---

👑 CONFIGURATION OPTIONS 👑

The standard configuration options are all recognized — both on tdbc::sqlite3::connection create and on the configure method of the resulting connection:

• -encoding
• -isolation
• -readonly
• -timeout

Now let's get into the individual girlies, because they each have lore:

• -encoding — since the encoding of a SQLite3 database is always well known, this option accepts only utf-8 as an encoding, and it always returns utf-8 for an encoding. Periodt. If you actually want to set the real encoding, you do it with a SQLite3 PRAGMA statement when you're creating a new database. 💅
• -isolation — only the isolation levels readuncommitted and serializable are implemented. Any other isolation level you throw at her gets promoted to serializable. She's not mad, she's just upgrading you. ✨
• -readonly — bestie. This flag is not implemented. A false boolean value is accepted silently (she'll just smile and nod), while any other value reports an error. 🚨
• -keepcase — this one is special and controls how table and column names are reported in the various methods that retrieve database metadata. By default the flag is zero, meaning table and column names are reported all lower case. Otherwise — i.e. anything else — table and column names are reported as defined in the database. Casing rights restored, as a treat. 🎀

---

😭 BUGS 😭

Okay listen, there is one known situation, and it's giving cursed:

If any column name is not unique among the columns in a result set, the results of -as dicts returns will be missing all but the rightmost of the duplicated columns. She eats the duplicates, fr fr. 💀

This limitation can be worked around by adding appropriate AS clauses to SELECT statements to ensure that all returned column names are unique. Slay, problem solved by you. 🫶

And the plans? The plans are to fix this bug by using a C implementation of the driver, which will also improve performance significantly. So it's not a forever situation, it's a glow-up in progress. 🌈

---

🔥 SEE ALSO 🔥

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

---

🍓 KEYWORDS 🍓

TDBC, SQL, SQLite3, database, connectivity, connection

---

💜 COPYRIGHT 💜

Copyright (c) 2008 by Kevin B. Kenny.

---

okay that's the whole page bestie, you ate that reading btw 💅 This one is from the Tcl 8.6 era and she answers to tdbc::sqlite3(3tcl) — so if you ever need to cite her, that's the name to drop. Take care of her, she's iconic. 🎀✨🦋