dbi_sqlite3
Home
Binary distributions
Source distribution
Documentation
dbi_interface ?objectName?
DESCRIPTION
The dbi_sqlite command creates an object objectName that
can be used to connect to sqlite databases using its native API. If
objectName is not provided, a name will be automatically generated
and returned by the command The object created supports the [dbi interface] for accessing and querying
databases.
The object supports transactions, lines, serials, views and checks.
Foreign keys are accepted, but not checked. sqlite3 dbi objects do not
support column permissions, roles, domains or permissions, as these are
not supported by sqlite3.
Extra commands supported
- objectName function name script
- Create an Sqlite function with name name. script will be executed
when the function is called (with parameters apended to it).
- objectName collate name script
- Create a new Sqlite collation with name name. script will be executed
when the collation is used with to strings as parameters. The application defined collation
routine should return negative, zero or positive if the first string is less than, equal to,
or greater than the second string
- objectName backup ?database? filename
-
The "backup" method makes a backup copy of a live database. The
optional database argument tells which database in the current
connection should be backed up. The default value is main (or, in other
words, the primary database file). To back up TEMP tables use temp. To
backup an auxilary database added to the connection using the ATTACH
command, use the name of that database as it was assigned in the ATTACH
command. filename is the name of a file into which the backup
is written. filename does not have to exist ahead of time, but if
it does, it must be a well-formed SQLite database.
- objectName restore ?database? filename
-
The "restore" method copies the content a separate database file into the
current database connection, overwriting any preexisting content. The
optional database argument tells which database in the current
connection should be overwritten with new content. The default value is
main (or, in other words, the primary database file). To repopulate the
TEMP tables use temp. To overwrite an auxilary database added to the
connection using the ATTACH command, use the name of that database as it
was assigned in the ATTACH command. filename is the name of a
existing well-formed SQLite database file from which the content is
extracted.
- objectName progress n callback
-
This method registers a callback that is invoked periodically during query
processing. There are two arguments: the number of SQLite virtual machine
opcodes between invocations n, and the TCL command callback
to invoke. Setting the progress callback to an empty string
disables it. The progress callback can be used to display the status of a
lengthy query or to process GUI events during a lengthy query.
- objectName incrblob ?-readonly? ?db? table column rowid
-
This method opens a TCL channel that can be used to read or write
into a preexisting BLOB in the database, identified by table
column, rowid, and optionally db. This optional
database name is not the filename that contains the database but rather
the symbolic name of the database that is assigned when the database is
connected using ATTACH. For the main database file, the database name is
"main". For TEMP tables, the database name is "temp". The command returns
a new TCL channel for reading or writing to the BLOB. The channel is
opened using the underlying sqlite3_blob_open() C-langauge interface.
Close the channel using the close command of Tcl.
- objectName import conflict-algorithm table filename ?separator? ?nullindicator? ?header?
-
This method imports the data from the file filename in the table table.
By default different fields are separated by tabs; the separator can be changed using the
separator option. An empty value is imported as a NULL value. This can be changed by using the
nullindicator option.
As in the default sqlite imnport, the method does not properly support quoting in csv files (yet),
meaning fields cannot contain the separator character, or be multiline.
header: By default, the method assumes that the file loaded will contain the same number of columns in
the same order as the the table, and no header. If header is given, but empty, the first
line in the file is taken as a header to determine what columns are in the file. If not empty, it
is used as a list of fields in the file.
conflict-algorithm can be either of rollback,abort,fail,ignore,replace. It gives the conflict resolution algorithm
that will be used when errors occur during inserts.
Extra collations
The dbi interface also adds two new collations:
- DICT
- dictionary sort: Sort alphabetically, but numbers are treated as integers:
e.g. test2 wil be sorted before test10
- DICTREAL
- dictionary sort: Sort alphabetically, but numbers are treated as reals:
e.g. a2.0555 wil be sorted before a2.08.
Extra functions
The dbi interface also adds two new functions to sqlite:
- regexp
- This function has to parameters: the pattern and the value. Thus allows the
use of regular expressions in queries, e.g.: where "first_name" regexp '^[Jj]o'
- list_concat
- This aggregate function returns a proper list of all elements in the query
SEE ALSO
KEYWORDS
- dbi
- sqlite
- sqlite3
- interface
- database
- sql