-*-text-*-
$Header: /CVSROOT/public/scylla-charybdis/md5backup/doc/sqlite.txt,v 1.2 2005/07/17 00:50:48 tino Exp $

COMPILE
=======

As sqlite.org does not provide statically linkable libraries (*.a),
you have to compile sqlite yourelf.  I decided to go for the
statically linked library as this makes md5backup more stable from my
point of view.

You will need at least sqlite 3.2.1.

Sqlite will be compiled in a separate directory.  So you do not need
to compile it again if md5backup is updated.  However, md5backup
checks to see if your sqlite version is the one it expects.  If this
is not the case it will warn you.  If the version of sqlite is too
old, md5backup will refuse to run.

1) Get the source from CVS

	Use one of the variants (not both!):

1a) Get sources from CVS

	You are in the directory where this documentation is:
	cd ../..
	cvs -d :pserver:anonymous@www.sqlite.org:/sqlite login
	(Password is: anonymous)
	cvs -d :pserver:anonymous@www.sqlite.org:/sqlite checkout sqlite
	cd sqlite

1b) Get the sources via WWW

	You are in the directory where this documentation is:
	cd ../..
	wget http://sqlite.org/sqlite-3.2.1.tar.gz
	tar xfz sqlite-3.2.1.tar.gz
	ln -s sqlite-3.2.1 sqlite
	cd sqlite

2) Compile the source

	You are in the directory where you were from step 1:
	mkdir build
	../configure
	make

	If you like, you can run the sqlite tests as well:
	make test
	Note that this command failed for me as my TCL was the wrong
	version (RH9).  So you can happily ignore this.

If you change the paths, be sure to update the softlink to the
sqlite build directory in the md5backup distribution directory.


RATIONALE
=========

md5backup needs a better database.  Therefor it will be based on
sqlite in future.

With sqlite you not only have an embedded database which is public
domain, it also allows to change the table format in future without
the need to run a full backup afterwards to rebuild the database.

I decided to use sqlite 3.2, which has the ALTER TABLE ADD COLUMN
command, which I will need to be able to add new features without
seamlessly.

Also sqlite has a command line frontend (sqlite3) which allows you to
access the database directly.  No need to compile separate programs
like "tinodbm" or things like this.

As sqlite 3.2 is relatively new, it may be considered not very stable.
That's not a problem with md5backup, as md5backup does not need a
stable database for operation.  In case of trouble or suspected
trouble with the database, just remove it and start a fresh md5backup.
Except of more logging and runtime, no harm is done this way.

With the help of sqlite, the shell scripts will start to use the
database for some purpose.  Be sure, to have the current sqlite3
binary in the path.  It's automatically softlinked in the bin/
directory, so don't remove the compiled sqlite3 binary!


TRANSITION
==========

For easy transition, there is a migration process bin/migrate.sh to
read the old DBM files and transform them into the sqlite database.
This migration will no more be possible when md5backup reaches 0.5.

-Tino
$Log