lang/sql/odbc/README

   1 SQLite ODBC Driver\r
   2 ------------------\r
   3 \r
   4 This is an open source ODBC driver for the wonderful\r
   5 SQLite 2.8.* and SQLite 3.* Database Engine/Library.\r
   6 The driver is usable but may contain lots of memory\r
   7 leaks and all other kinds of bugs. Use it on your own\r
   8 risk.\r
   9 \r
  10 The current source can be downloaded from\r
  11 \r
  12     http://www.ch-werner.de/sqliteodbc/sqliteodbc-*.tar.gz\r
  13 \r
  14 WIN32 binaries (the ODBC driver DLL, install/uninstall programs) are in\r
  15 \r
  16     http://www.ch-werner.de/sqliteodbc/sqliteodbc.exe\r
  17 \r
  18 The binaries were made with SQLite 2.8.17, SQLite 3.7.8, MingW\r
  19 cross compiler and tested on Windows NT 4.0 with the query tool\r
  20 of MS Excel 97, with StarOffice 5.2 and OpenOffice 1.1 and 2.x.\r
  21 Execute the sqliteodbc.exe NSIS installer to unpack the necessary\r
  22 files. This installs the SQLite ODBC driver and creates a System DSN.\r
  23 To remove the driver use the start menu entries or the UNINST.EXE\r
  24 program. To create a SQLite data source use the ODBC control panel\r
  25 applet and provide the name of the SQLite database file to be worked\r
  26 on as an absolute pathname including the drive letter, eg as\r
  27 "C:\TEMP\SQLite.DB". The busy (or lock) timeout for the database\r
  28 can be specified in the respective field. If empty a default value\r
  29 of 100000 milliseconds is used.\r
  30 \r
  31 The Win64 installer (sqliteodbc_w64.exe) was made with SQLite 3.7.8,\r
  32 MingW cross compiler and only rudimentary tested on Windows Vista 64.\r
  33 \r
  34 Other tests were made on Linux with the "isql" command line tool\r
  35 and the "DataManager" GUI tool of unixODBC 2.1.0.\r
  36 \r
  37 \r
  38 Since October 14th, 2001, the driver supports the data types SQL_INTEGER,\r
  39 SQL_TINYINT, SQL_SMALLINT, SQL_FLOAT, SQL_DOUBLE, SQL_DATE, SQL_TIME,\r
  40 SQL_TIMESTAMP, and SQL_VARCHAR.\r
  41 \r
  42 Since May 25th, 2002, SQL_LONGVARCHAR is available but rather\r
  43 experimental. That type is used for SQLite schema containing text\r
  44 or varchar with a size specifier larger than 255.\r
  45 \r
  46 The data type mapping obtains per-column meta information from the\r
  47 "PRAGMA table_info(...)" SQLite statement. If SELECTs are used which\r
  48 contain columns for which the table qualifier cannot be determined,\r
  49 no meta information for data type mapping is available and therefore\r
  50 the database source data type will be SQL_VARCHAR or SQL_LONGVARCHAR\r
  51 which usually maps to SQL_C_CHAR.\r
  52 \r
  53 Restrictions of data type mapping:\r
  54 \r
  55 - Integer and floating point columns in the database are reported\r
  56   as NULLs when no digit seen in the column, otherwise all digits\r
  57   up to end of string or non-digit are interpreted as the value,\r
  58   i.e. '10blurk' is ten, '0blurk' is zero, but 'blurk' is NULL.\r
  59 - Format for SQL_DATE is YYYY-MM-DD or YYYYMMDD\r
  60 - Format for SQL_TIME is hh:mm:ss or hhmmss\r
  61 - Format for SQL_TIMESTAMP is\r
  62       YYYYMMDDhhmmss[fraction]\r
  63   or  YYYY-MM-DD hh:mm:ss[.fraction]\r
  64   or  hh:mm:ss[.fraction] YYYY-MM-DD\r
  65   The fractional part is expressed as 1E-09 seconds\r
  66 - The driver puts the ODBC string representations for date/time,\r
  67   (eg for "{ts '2001-10-10 12:58:00'}" the substring within the\r
  68   single quotes) directly into the SQLite column\r
  69 \r
  70 \r
  71 Since November 17th, 2001, configure/libtool is used for the Un*x\r
  72 version which should automatically find the SQLite and unixODBC\r
  73 (or iODBC) header files and libraries. Do the usual\r
  74 \r
  75     $ ./configure && make\r
  76 \r
  77 followed by\r
  78 \r
  79     # make install\r
  80 \r
  81 in order to get /usr/local/lib/libsqliteodbc.so.\r
  82 Of course, you should have installed the unixODBC (or iODBC)\r
  83 development RPMs since the ODBC header files are required for\r
  84 the build of the SQLite ODBC driver.\r
  85 \r
  86 Since May 15th, 2003, (version 0.51), there are two variants\r
  87 of the SQLite 2.x driver for Win32 platforms: the first (sqliteodbc.dll)\r
  88 linked against ISO8859-1 SQLite library exporting ODBC/SQL ANSI\r
  89 functions, and the second (sqliteodbcu.dll) linked against UTF-8\r
  90 SQLite library exporting ODBC/SQL UNICODE functions.\r
  91 \r
  92 The UNICODE version is experimental and allows to turn off\r
  93 wide character SQL data types by its configuration dialog\r
  94 (checkmark labelled "No WCHAR"). It is known to work on Win32.\r
  95 It may work on UN*X too using newer version of unixODBC.\r
  96 \r
  97 To setup a SQLite data source using unixODBC (www.unixodbc.org):\r
  98 \r
  99   1. Add the driver to /etc/odbcinst.ini:\r
 100 \r
 101     [SQLite]\r
 102     Description=SQLite ODBC Driver\r
 103     Driver=/usr/local/lib/libsqliteodbc.so\r
 104     Setup=/usr/local/lib/libsqliteodbc.so\r
 105     Threading=2\r
 106 \r
 107   2. Add a DSN to your private ~/.odbc.ini:\r
 108 \r
 109     [mysqlitedb]\r
 110     Description=My SQLite test database\r
 111     Driver=SQLite\r
 112     Database=/home/johndoe/databases/mytest.db\r
 113     # optional lock timeout in milliseconds\r
 114     Timeout=2000\r
 115 \r
 116 For iODBC (www.iodbc.org, only versions 3.0.[56] tested) do the\r
 117 following steps:\r
 118 \r
 119   1. Add the driver to /etc/odbcinst.ini:\r
 120 \r
 121     [ODBC Drivers]\r
 122     ...\r
 123     SQLite=Installed\r
 124     ...\r
 125 \r
 126     [SQLite]\r
 127     Driver=/usr/local/lib/libsqliteodbc.so\r
 128 \r
 129   2. Add a DSN to your private ~/.odbc.ini:\r
 130 \r
 131     [ODBC Data Sources]\r
 132     ...\r
 133     mysqlitedb=SQLite\r
 134     ...\r
 135 \r
 136     [mysqlitedb]\r
 137     Driver=/usr/local/lib/libsqliteodbc.so\r
 138     Description=My SQLite test database\r
 139     Database=/home/johndoe/databases/mytest.db\r
 140     # optional lock timeout in milliseconds\r
 141     Timeout=2000\r
 142 \r
 143 \r
 144 Python sample usage with eGenix mx-Extension\r
 145 (see http://www.lemburg.com/files/python/mxODBC.html)\r
 146 \r
 147     $ python\r
 148     >>> import mx.ODBC.unixODBC\r
 149     >>> dbc=mx.ODBC.unixODBC.connect("mysqlitedb")\r
 150     >>> cur=dbc.cursor()\r
 151     >>> cur.execute("create table foo (id int, name string)")\r
 152     1\r
 153     >>> cur.execute("insert into foo values(1, 'Me')")\r
 154     1\r
 155     >>> cur.execute("insert into foo values(2, 'You')")\r
 156     1\r
 157     >>> dbc.commit()\r
 158     >>> cur.execute("select * from foo")\r
 159     >>> print cur.fetchall()\r
 160     [(1, 'Me'), (2, 'You')]\r
 161     >>> print cur.fetchall()\r
 162     []\r
 163     >>> cur.execute("drop table foo")\r
 164     1\r
 165     >>> dbc.commit()\r
 166 \r
 167 \r
 168 Build instructions for MS Visual C++ 6.0:\r
 169 \r
 170 ... for SQLite 2.x.x\r
 171 \r
 172 1. Extract the source tarball sqliteodbc.tar.gz\r
 173 2. Extract the official SQLite 2.x.x sources in the sqliteodbc\r
 174    directory which resulted from step 1. Optionally, apply the\r
 175    sqlite-locale-patch-28* which matches your SQLite version\r
 176 3. Setup your MSVC++ environment, ie PATH/INCLUDE/LIB, then\r
 177    open a command window, cd to the sqliteodbc directory and enter:\r
 178 \r
 179         nmake -f sqliteodbc.mak\r
 180 \r
 181    This compiles the SQLite sources first, creates a link library\r
 182    of the necessary object files, then compiles and links the ODBC\r
 183    driver and the (un)install program.\r
 184 4. If you'd like to create the UNICODE version of the driver, enter:\r
 185 \r
 186         nmake -f sqliteodbc.mak clean\r
 187         nmake -f sqliteodbc.mak ENCODING=UTF8\r
 188 \r
 189 ... for SQLite 3.x.x\r
 190 \r
 191 1. Extract the source tarball sqliteodbc.tar.gz\r
 192 2. Extract the amalgamation SQLite 3.x.x. sources in the sqliteodbc\r
 193    directory which resulted from step 1.\r
 194 3. Setup your MSVC++ environment, ie PATH/INCLUDE/LIB, then\r
 195    open a command window, cd to the sqliteodbc directory and enter:\r
 196 \r
 197         nmake -f sqlite3odbc.mak\r
 198 \r
 199    This compiles the amalgamation SQLite3 source and the ODBC driver\r
 200    first, then and links the ODBC driver and the (un)install program.\r
 201 \r
 202 \r
 203 Names of Win32 Driver DLLs:\r
 204 \r
 205    sqliteodbc.dll    Driver with ISO8859-1 SQLite2 engine\r
 206    sqliteodbcu.dll   Driver with UTF-8/UNICODE SQLite2 engine\r
 207    sqlite3odbc.dll   Driver with SQLite3 engine\r
 208 \r
 209 \r
 210 Build instructions for MingW cross compiler for Win32 targets:\r
 211 \r
 212   A script named mingw-cross-build.sh is provided which contains\r
 213   all necessary information. It downloads the required SQLite\r
 214   source tarballs and builds SQLite and the ODBC drivers. The\r
 215   final step is creating an NSIS installer.\r
 216 \r
 217 \r
 218 Build instructions for MingW cross compiler for Win64 targets:\r
 219 \r
 220   A script named mingw64-cross-build.sh is provided which contains\r
 221   all necessary information. It downloads the required SQLite\r
 222   source tarballs and builds SQLite 3 and the ODBC driver. The\r
 223   final step is creating an NSIS installer.\r
 224 \r
 225 \r
 226 Win32 install/remove/shell by RUNDLL32\r
 227 \r
 228   Each driver DLL provides entry points for ODBC driver installation\r
 229   and removal which can be invoked from RUNDLL32.EXE, eg\r
 230 \r
 231   ### install sqliteodbc.dll\r
 232   C:\> rundll32 [path]sqliteodbc.dll,install [quiet]\r
 233 \r
 234   ### remove sqlite3odbc.dll\r
 235   C:\> rundll32 [path]sqlite3odbc.dll,uninstall [quiet]\r
 236 \r
 237   If [path] is not provided newer Windows OSes tend to favor the\r
 238   sqlite*odbc*dll in system directories over the current directory,\r
 239   thus better provide an absolute path to the DLL of interest.\r
 240   If the word "quiet" appears anywhere after the DLL/function\r
 241   name, no info message boxes pop up (but errors are shown).\r
 242 \r
 243   An (interactive or batch) SQLite shell can be invoked, too, eg\r
 244 \r
 245   ### run SQLite shell on database C:\bla\my.db\r
 246   C:\> rundll32 [path]sqliteodbc.dll,shell C:\bla\my.db ...\r
 247 \r
 248   ### batch run with given SQL\r
 249   C:\> rundll32 [path]sqliteodbc.dll,shell -batch C:\bla\my.db\r
 250        "select * from table" <NUL: 2>NUL: >out.txt\r
 251 \r
 252 \r
 253 Win64 notes\r
 254 \r
 255   On Win64 (64 bit versions of Vista, Windows 7) both 32 bit and 64 bit\r
 256   drivers can be installed in parallel. The 32 bit drivers are required\r
 257   when using 32 bit applications. In order to manage 32 bit data\r
 258   sources, the 32 bit ODBC admin tool C:\Windows\SysWOW64\odbcad32.exe\r
 259   must be used.\r
 260 \r
 261 \r
 262 DSN-less connection to the driver\r
 263 \r
 264   Using the SQLDriverConnect() API it should be possible to connect to\r
 265   a SQLite database with these strings (Win32 and UN*X)\r
 266 \r
 267     DSN=SQLite Datasource;Database=full-path-to-db;...\r
 268     DSN=SQLite3 Datasource;Database=full-path-to-db;...\r
 269 \r
 270   alternatively\r
 271 \r
 272   Win32:\r
 273 \r
 274     Driver=SQLite ODBC Driver;Database=full-path-to-db;...\r
 275     Driver=SQLite3 ODBC Driver;Database=full-path-to-db;...\r
 276 \r
 277   UN*X (Linux RPM):\r
 278 \r
 279     Driver=SQLITE;Database=full-path-to-db;...\r
 280     Driver=SQLITE3;Database=full-path-to-db;...\r
 281 \r
 282 \r
 283 Build Instructions for Alpha/Tru64 (OSF1 V5.1) and HP/UX (B.11.23 U ia64)\r
 284 \r
 285   Nikola Radovanovic had success with these commands to build\r
 286   all required components:\r
 287 \r
 288   sqlite (3.6.7):\r
 289     ./configure --prefix=$HOME/development --disable-tcl \\r
 290       CC='cc -pthread' CFLAGS='-DSQLITE_ENABLE_COLUMN_METADATA=1'\r
 291     gmake && gmake install\r
 292 \r
 293   unixODBC (2.2.12):\r
 294     ./configure --prefix=${HOME}/development --disable-gui \\r
 295       --without-x --enable-iconv=no\r
 296     gmake && gmake install\r
 297 \r
 298   sqliteodbc (>0.79):\r
 299     ./configure --with-sqlite3=${HOME}/development \\r
 300       --with-odbc=${HOME}/development --prefix=${HOME}/development \\r
 301       --enable-winterface=no\r
 302     OSF1:  gmake && gmake install\r
 303     HP/UX: gmake CFLAGS="+DD64" && gmake install\r
 304 \r
 305 \r
 306 Build Instructions for RPM based systems\r
 307 \r
 308   rpmbuild -tb sqliteodbc-*.tar.gz\r
 309 \r
 310 \r
 311 Build Instructions for Debian based systems\r
 312 \r
 313   tar xzf sqliteodbc-*.tar.gz\r
 314   cd sqliteodbc-*\r
 315   ./configure && make deb\r
 316 \r
 317 \r
 318 Special build to use System.Data.SQLite on Win32/Win64\r
 319 \r
 320   A variant of the SQLite3 ODBC driver can be build which uses\r
 321   internal dynamic linking to System.Data.SQLite.dll or sqlite3.dll.\r
 322   This feature is turned on when running the mingw*-cross-build.sh\r
 323   scripts with SQLITE_DLLS=2.\r
 324 \r
 325 \r
 326 \r
 327 TODO:\r
 328 \r
 329 - improve documentation\r
 330 \r
 331 \r
 332 2011-11-15\r
 333 Christian Werner\r
 334 mailto:chw@ch-werner.de\r
 335 \r