Main Page | Alphabetical List | Data Structures | File List | Data Fields | Globals

SQLiteODBC Documentation

README

SQLite ODBC Driver
------------------

This is an experimental open source ODBC driver for the wonderful
SQLite 2.8.* Database Engine/Library. A pre-alpha version for
SQLite 3.* is also contained in the source archive. So far it is
more a proof of concept and might contain lots of memory leaks
and all other kinds of bugs. Thus I highly appreciate feedback.

The current source can be downloaded from

    http://www.ch-werner.de/sqliteodbc/sqliteodbc-*.*.tar.gz

WIN32 binaries (the ODBC driver DLL, install/uninstall programs) are in

    http://www.ch-werner.de/sqliteodbc/sqliteodbc-win32.zip

The binaries were made with SQLite 2.8.15, MS VC++ 6.0 and tested on
Windows NT 4.0 with the query tool of MS Excel 97, with
StarOffice 5.2 and OpenOffice 1.1.
Unzip the archive into a temporary directory and execute the INST.EXE
program. This installs the SQLite ODBC driver and creates a System DSN.
To remove the driver use the UNINST.EXE program. To create a SQLite
data source use the ODBC control panel applet and provide the name of
the SQLite database file to be worked on as an absolute pathname including
the drive letter, eg as "C:\TEMP\SQLite.DB". The busy (or lock) timeout
for the database can be specified in the respective field. If empty
a default value of 1000 milliseconds is used.

Other tests were made on Linux with the "isql" command line tool and the
"DataManager" GUI tool of unixODBC 2.1.0.


Since October 14th, 2001, the driver supports the data types SQL_INTEGER,
SQL_TINYINT, SQL_SMALLINT, SQL_FLOAT, SQL_DOUBLE, SQL_DATE, SQL_TIME,
SQL_TIMESTAMP, and SQL_VARCHAR.

Since May 25th, 2002, SQL_LONGVARCHAR is available but rather
experimental. That type is used for SQLite schema containing text
or varchar with a size specifier larger than 255.

The data type mapping obtains per-column meta information from the
"PRAGMA table_info=..." SQLite statement. If SELECTs are used which
contain columns for which the table qualifier cannot be determined,
no meta information for data type mapping is available and therefore
the database source data type will be SQL_VARCHAR or SQL_LONGVARCHAR
which usually maps to SQL_C_CHAR.

Restrictions of data type mapping:

- Integer and floating point columns in the database are reported
  as NULLs when no digit seen in the column, otherwise all digits
  up to end of string or non-digit are interpreted as the value,
  i.e. '10blurk' is ten, '0blurk' is zero, but 'blurk' is NULL.
- Format for SQL_DATE is YYYY-MM-DD or YYYYMMDD
- Format for SQL_TIME is hh:mm:ss or hhmmss
- Format for SQL_TIMESTAMP is
      YYYYMMDDhhmmss[fraction]
  or  YYYY-MM-DD hh:mm:ss[.fraction]
  or  hh:mm:ss[.fraction] YYYY-MM-DD
  The fractional part is expressed as 1E-09 seconds
- The driver puts the ODBC string representations for date/time,
  (eg for "{ts '2001-10-10 12:58:00'}" the substring within the
  single quotes) directly into the SQLite column


Since November 17th, 2001, configure/libtool is used for the Un*x
version which should automatically find the SQLite and unixODBC
(or iODBC) header files and libraries. Do the usual

    $ ./configure && make

followed by

    # make install

in order to get /usr/local/lib/libsqliteodbc.so.
Of course, you should have installed the unixODBC (or iODBC)
development RPMs since the ODBC header files are required for
the build of the SQLite ODBC driver.

Since May 15th, 2003, (version 0.51), there are two versions
of the driver for Win32 platforms: the first (sqliteodbc.dll)
linked against ISO8859-1 SQLite library exporting ODBC/SQL ANSI
functions, and the second (sqliteodbcu.dll) linked against UTF-8
SQLite library exporting ODBC/SQL UNICODE functions.

The UNICODE version is experimental and allows to turn off
wide character SQL data types by its configuration dialog
(checkmark labelled "No WCHAR"). So far it has been only
tested on Win32.

To setup a SQLite data source using unixODBC (www.unixodbc.org):

  1. Add the driver to /etc/odbcinst.ini:

    [SQLite]
    Description=SQLite ODBC Driver
    Driver=/usr/local/lib/libsqliteodbc.so
    Setup=/usr/local/lib/libsqliteodbc.so

  2. Add a DSN to your private ~/.odbc.ini:

    [mysqlitedb]
    Description=My SQLite test database
    Driver=SQLite
    Database=/home/johndoe/databases/mytest.db
    # optional lock timeout in milliseconds
    Timeout=2000

For iODBC (www.iodbc.org, only versions 3.0.[56] tested) do the
following steps:

  1. Add the driver to /etc/odbcinst.ini:

    [ODBC Drivers]
    ...
    SQLite=Installed
    ...

    [SQLite]
    Driver=/usr/local/lib/libsqliteodbc.so

  2. Add a DSN to your private ~/.odbc.ini:

    [ODBC Data Sources]
    ...
    mysqlitedb=SQLite
    ...

    [mysqlitedb]
    Driver=/usr/local/lib/libsqliteodbc.so
    Description=My SQLite test database
    Database=/home/johndoe/databases/mytest.db
    # optional lock timeout in milliseconds
    Timeout=2000


Python sample usage with eGenix mx-Extension
(see http://www.lemburg.com/files/python/mxODBC.html)

    $ python
    >>> import mx.ODBC.unixODBC
    >>> dbc=mx.ODBC.unixODBC.connect("mysqlitedb")
    >>> cur=dbc.cursor()
    >>> cur.execute("create table foo (id int, name string)")
    1
    >>> cur.execute("insert into foo values(1, 'Me')")
    1
    >>> cur.execute("insert into foo values(2, 'You')")
    1
    >>> dbc.commit()
    >>> cur.execute("select * from foo")
    >>> print cur.fetchall()
    [(1, 'Me'), (2, 'You')]
    >>> print cur.fetchall()
    []
    >>> cur.execute("drop table foo")
    1
    >>> dbc.commit()


Build instructions for MS Visual C++ 6.0:

1. Extract the source tarball sqliteodbc.tar.gz
2. Extract the official SQLite 2.x.x sources in the sqliteodbc
   directory which resulted from step 1. Optionally, apply the
   sqlite-locale-patch-28* which matches your SQLite version
3. Setup your MSVC++ environment, ie PATH/INCLUDE/LIB, then
   open a command window, cd to the sqliteodbc directory and enter:

        nmake -f sqliteodbc.mak

   This compiles the SQLite sources first, creates a link library
   of the necessary object files, then compiles and links the ODBC
   driver and the (un)install program.
4. If you'd like to create the UNICODE version of the driver, enter:

	nmake -f sqliteodbc.mak clean
	nmake -f sqliteodbc.mak ENCODING=UTF8


Starting with release 0.63 support for SQLite version 3 will be
added as a separate DLL/shared library. The SQLite 3.* driver
is named sqlite3odbc.dll on windows and libsqlite3odbc.so on
Linux.


TODO:

- improve documentation


September, 5th, 2004
Christian Werner
mailto:chw@ch-werner.de

ChangeLog

SQLite ODBC Driver
------------------

Sun Sep 05 2004 version 0.64 released

	* added row-wise binding for rowsets
	* fixed off-by-one error for SQL_FETCH_PRIOR
	* another bug fix in fixupsql() concerning quotes thanks to
	  Justin Foutts
	* always fallback to _ROWID_ in SQLSpecialColumns(SQL_BEST_ROWID)
	  even for tables w/o index
	* update to SQLite 2.8.15
	* fixes concerning SQL_COLUMN_LABEL in SQLColumnAttribute(s)

Thu Jul 08 2004 version 0.63 released

	* added tracefile DSN option using sqlite_trace() if available
	* in drvprepare() make SQL check with all parameters set to NULL
	* only use *step() for select statements w/o parameters
	  (makes option usable on OpenOffice.org on Linux)
	* added pre-alpha version for SQLite 3.x
	* added limited support for paramsets/rowset for OTLv4
	* added limited support for named parameters (Oracle-style)
	* fixed problem in SQLBindParameter argument checking
	* when using gcc do printf-style format checks on setstat/setstatd
	* added SQLite functions current_(date|time|datetime)_(local|utc)
	* include SQLite error codes or -1 in native error field in
	  SQLError() and SQLGetDiagRec()
	* bug fixes in SQLNativeSql() concerning buffer/length
	  semantics, thanks to N Rajesh
	* corrected problems in fixupdyncols (select on views) and
	  UN*X version of drvdriverconnect
	* added SQLite functions hextobin/bintohex when
	  sqlite_(encode|decode)_binary API available
	* introduced blob handling when sqlite_(encode|decode)_binary
	  available (SQLite 2.8.14 made these APIs public)
	* update to SQLite 2.8.14
	* made SQL_COLUMN_LABEL different from SQL_COLUMN_NAME
	* fix in configure.in concerning SQLITE_INC/LIBDIR macros,
	  thanks to Stefan Radman

Sat May 01 2004 version 0.62 released

	* don't implement some APIs for unixODBC unicode driver version
	* fixed unicode length semantics in SQLGetInfoW() et.al.
	* when SQLITE_UTF8 make SQLDriverConnectW() on UN*X, too
	* added missing SQL_DESC_TYPE_NAME case in SQLColAttribute(),
	  patch provided by Chris Waters
	  
Sat Apr 24 version 0.61 released

	* fixed getrowdata() to support SQLGetData() with NULL ptr and
	  SQLFetch() to retrieve proper data length, thanks to Joel Reed
	* fall back to integer primary key columns in SQLPrimaryKeys()
	  and SQLStatistics() when no indices on table found
	* improved auto increment detection

Thu Apr 08 2004 version 0.60 released

	* improved RPM .spec file
	* added heuristic to detect auto increment columns
	  (not a 100% solution yet) for better OpenOffice.org
	  support, thanks to Yves Chaufour for OOo testing
	* added property list function for unixODBC setup dialog
	* another SQLFreeStmt(...SQL_CLOSE) fix to make OOo work
	* added implemetation of SQLForeignKeys()
	* removed worker thread support, use sqlite_compile(),
	  sqlite_step(), sqlite_finalize() instead, DSN option to
	  use that feature is "StepAPI"
	* minimum required SQLite version is now 2.8.0

Sun Mar 21 2004 version 0.56 released

	* update to SQLite 2.8.13
	* fixes in UTF to unicode conversion
	* fixes in handling of length indicator in SQLBindParameter()
	* added SQL_{COLUMN,DESC}_{PRECISION,SCALE} to SQLColAttribute()
	* some unixODBC tweaks related to SQLError()/SQLGetDiagRec()
	* corrections in SQLError()/SQLGetDiagRec() handling,
	* fixed bugs in SQLColAttribute() which crashed OpenOffice.org
	* added SQL_FETCH_RELATIVE support as requested by Jorge Mason
	* fix in SQLFreeStmt(...SQL_CLOSE): don't unbind bound columns
	  thanks to Martin Saturka

Sat Jan 25 2004 version 0.55 released

	* update to SQLite 2.8.11
	* fixes in error messages
	* fixed SQL_IDENTIFIER_QUOTE_CHAR to be double-quote, thanks
	  to Mourad Ben Cheikh
	* minor fixes in functions related to SQLColAttribute(s)
	* started support of bookmarks
	* added SQL_DYNAMIC_CURSOR_ATTRIBUTES1 in drvgetinfo(),
	  thanks to Jeff Robbins
	* changed "numeric" in mapsqltype() to return SQL_DOUBLE,
	  thanks to Cristian Guissani
	* added add[sys]dsn/rem[sys]dsn utility programs for Win32
	  as requested by Tom Shafer
	* fix in ParseAttributes() for proper DSN configuration
	* don't automatically rollback in drvexecute()
	* bug fix in UTF8 version for deferred bound parameters
	  thanks to Kimmo Hamalainen

Sun Jul 27 2003 version 0.54 released

	* update to SQLite 2.8.5
	* minor fixes in SQLGetDiagRec()
	* when ODBC V3 turned on report proper error codes (eg HY000)
	* added partial support of SQL_ATTR_ROW_BIND_TYPE

Fri Jul 11 2003 version 0.53 released

	* update to SQLite 2.8.4
	* added missing handling of ODBC V3 data type codes SQL_C_DATE,
	  SQL_C_TIME, SQL_C_TIMESTAMP in some functions. Thanks to
	  Justin at cloudmark dot com

Sun Jun 15 2003 version 0.52 released

	* update to SQLite 2.8.3
	* fixed potential crash in dbopen() thanks to Gene Shkolnik
	* some improvements and hacks for WIN32 ADO
	* for SQL type "float" report SQL_DOUBLE instead of SQL_FLOAT
	* WIN32: export more ODBC V2 symbols
	* fixes in unicode conversions in SQLGetData() and drvbindparam().

Thu May 15 2003 version 0.51 released

	* added support for SQLITE_UTF8 by SQL*W unicode entries,
	  partially tested on Win32 only!
	* added ODBC v2/3 handling on SQLAllocHandle etc.
	* use localeconv() to fixup floating point formatting
	* eliminated unnecessary odbcver.h and ctl3d.h from
	  *.rc and *.c files, thanks to Roberto Artigas Jr
	* added ODBC version 3 SQL_TYPE_* features
	* fixes in configure.in for Solaris, thanks to
	  Gene Shkolnik
	* fixed bug in drvbindparam() thanks to Alex Clement
	* switched coroutine handling to use pth_uctx_*() from
	  GNU pth package, configure option --enable-pth

Sat Mar 08 2003 version 0.50 released

	* changed freeresult() behaviour in order to allow
	  SQLBindCol() column bindings before prepare/execute
	* revision of SQLGetTypeInfo()
	* minor changes in SQLGetInfo() and SQLGetFunctions()

Sat Feb 22 2003 version 0.49 released

	* update to SQLite 2.8.0
	* bug fix in fixupsql() concerning quotes thanks to Alex Clement
	* bug fix in substparam() for SQL_NTS/SQL_NULL_DATA
	  thanks to Alex Clement
	* bug fix in drvfetchscroll for wrong column counting
	  for SQL_FETCH_ABSOLUTE, thanks to Gene Shkolnik

Thu Jan 02 2003 version 0.48 released

	* cleanup threading
	* added mkopc tool for making opcodes.[ch] on Win32

Sat Sep 14 2002 version 0.47 released

	* fixed NULL pointer derefs in getmd() and mapsqltype()
	* SQLBindCol() now always binds even if no result available

Sat Aug 31 2002 version 0.46 released

	* experimental: configuration option: use coroutine
	  instead of thread for running select statements
	* SQLMoreResults() now always returns SQL_NO_DATA
	* use the new PRAGMA show_datatypes if available
	* reworked busy handling logic to use sqlite_busy_handler()
	* now perform sqlite_open() in single function dbopen()
	* changed all pthread_cond_signal() to pthread_cond_broadcast()

Fri Jul 05 2002 version 0.45 released

	* improved timestamp scanning
	* return result set with _ROWID_ for SQLSpecialColumns()
	  when no unique column in table
	* fixes in parameter substitution (SQLSetParam())
	* fixed reading data in pieces (SQLGetData())
	* added dummy implementations for SQLTablePrivileges(),
	  SQLColumnPrivileges(), SQLProcedures(), SQLForeignKeys(),
	  SQLProcedureColumns()
	* code cleanup
	* added support for NULL in parameters using %Q
	  sqlite_..printf() format specifier for SQLite > 2.4.x

Sun Jun 16 2002 version 0.44 released

	* fixed getbool() to return false on empty string
	* added implementation of SQLParamData(), SQLPutData()
	* fixed values of NON_UNIQUE field in SQLStatistics(),
	  store empty INDEX_QUALIFIER field in SQLStatistics()
	* fixes in getrowdata() concerning partial retrieving
	  of result set
	* when starting an asynchronous query, set number of
	  result rows to -1
	* fixes in SQLBindParameters(), for some datatypes
	  the binding was not performed

Sun Jun 09 2002 version 0.43 released

	* replaced all %s in PRAGMAs by '%q' to make SQLPrimaryKeys(),
	  SQLStatistics(), SQLSpecialColumns() work on automatic indexes
	* added NULLABLE column to result set of SQLSpecialColumns()
	  to support last SQLSpecialColumns() parameter properly
	* additions in SQLGetInfo()
	* added implemetation of SQL(Get|Set)ConnectAttr()
	* improved handling of SQLDriverConnect() for non Win32 OSes
	* improved handling of arguments in SQLTables()

Tue Jun 04 2002 version 0.42 released

	* now use doxygen for docs
	* added ChangeLog
	* added BSD type license

License Terms

This software is copyrighted by Christian Werner <chw@ch-werner.de>.
The following terms apply to all files associated with the software
unless explicitly disclaimed in individual files.

The authors hereby grant permission to use, copy, modify, distribute,
and license this software and its documentation for any purpose, provided
that existing copyright notices are retained in all copies and that this
notice is included verbatim in any distributions. No written agreement,
license, or royalty fee is required for any of the authorized uses.
Modifications to this software may be copyrighted by their authors
and need not follow the licensing terms described here, provided that
the new terms are clearly indicated on the first page of each file where
they apply.

IN NO EVENT SHALL THE AUTHORS OR DISTRIBUTORS BE LIABLE TO ANY PARTY
FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES
ARISING OUT OF THE USE OF THIS SOFTWARE, ITS DOCUMENTATION, OR ANY
DERIVATIVES THEREOF, EVEN IF THE AUTHORS HAVE BEEN ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.

THE AUTHORS AND DISTRIBUTORS SPECIFICALLY DISCLAIM ANY WARRANTIES,
INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT.  THIS SOFTWARE
IS PROVIDED ON AN "AS IS" BASIS, AND THE AUTHORS AND DISTRIBUTORS HAVE
NO OBLIGATION TO PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR
MODIFICATIONS.

Generated on 9 Oct 2004 by doxygen.
Contact: chw@ch-werner.de