Back to the SQLite Home Page
(This page was last modified on [lrange $rcsid 3 4] GMT)
" puts {The SQLite library is designed to be very easy to use from a Tcl or Tcl/Tk script. This document gives an overview of the Tcl programming interface.
The interface to the SQLite library consists of single tcl command named sqlite. Because there is only this one interface command, the interface is not placed in a separate namespace.
The sqlite command is used as follows:
sqlite dbcmd database-directory-name
The sqlite command opens the SQLite database located in the directory named by the second argument. If the database or directory does not exist, it is created. The sqlite command also creates a new Tcl command to control the database. The name of the new Tcl command is given by the first argument. This approach is similar to the way widgets are created in Tk.
Once an SQLite database is open, it can be controlled using methods of the dbcmd. There are currently 5 methods defined:
We will explain all of these methods, though not in that order. We will be begin with the "close" method.
As its name suggests, the "close" method to an SQLite database just closes the database. This has the side-effect of deleting the dbcmd Tcl command. Here is an example of opening and then immediately closing a database:
sqlite db1 ./testdb
db1 close
If you delete the dbcmd directly, that has the same effect as invoking the "close" method. So the following code is equivalent to the previous:
sqlite db1 ./testdb
rename db1 {}
The most useful dbcmd method is "eval". The eval method is used to execute SQL on the database. The syntax of the eval method looks like this:
dbcmd eval sql ?array-name script?
The job of the eval method is to execute the SQL statement or statements given in the second argument. For example, to create a new table in a database, you can do this:
sqlite db1 ./testdb
db1 eval {CREATE TABLE t1(a int, b text)}
The above code creates a new table named t1 with columns a and b. What could be simplier?
Query results are returned as a list of column values. If a query requests 2 columns and there are 3 rows matching the query, then the returned list will contain 6 elements. For example:
db1 eval {INSERT INTO t1 VALUES(1,'hello')}
db1 eval {INSERT INTO t1 VALUES(2,'goodbye')}
db1 eval {INSERT INTO t1 VALUES(3,'howdy!')}
set x [db1 eval {SELECT * FROM t1 ORDER BY a}]
The variable $x is set by the above code to
1 hello 2 goodbye 3 howdy!
You can also process the results of a query one row at a time by specifying the name of an array variable and a script following the SQL code. For each row of the query result, the value of each column will be inserted into the array variable and the script will be executed. For instance:
db1 eval {SELECT * FROM t1 ORDER BY a} values {
parray values
puts ""
}
This last code will give the following output:
values(*) = a b
values(a) = 1
values(b) = hellovalues(*) = a b
values(a) = 2
values(b) = goodbyevalues(*) = a b
values(a) = 3
values(b) = howdy!
For each column in a row of the result, the name of that column is used as an index in to array. The value of the column is stored in the corresponding array entry. The special array index * is used to store a list of column names in the order that they appear.
If the array variable name is the empty string, then the value of each column is stored in a variable with the same name as the column itself. For example:
db1 eval {SELECT * FROM t1 ORDER BY a} {} {
puts "a=$a b=$b"
}
From this we get the following output
a=1 b=hello
a=2 b=goodbye
a=3 b=howdy!