Index: trunk/Changes
===================================================================
--- trunk/Changes	(revision 33)
+++ trunk/Changes	(revision 34)
@@ -1,3 +1,7 @@
 Revision history for Perl extension MP3::Find.
+
+0.06
+    - deprecated the create_db, update_db, and sync_db methods
+    - databases can be selected by a custom DSN or an already open database handle
 
 0.05 28 Apr 2006
Index: trunk/MANIFEST
===================================================================
--- trunk/MANIFEST	(revision 33)
+++ trunk/MANIFEST	(revision 34)
@@ -6,4 +6,5 @@
 t/02-filesystem.t
 t/03-db.t
+t/04-new-db.t
 t/mp3s/not-an-mp3
 t/mp3s/dont_look_here/testv2.4.0.mp3
Index: trunk/lib/MP3/Find/DB.pm
===================================================================
--- trunk/lib/MP3/Find/DB.pm	(revision 33)
+++ trunk/lib/MP3/Find/DB.pm	(revision 34)
@@ -72,8 +72,17 @@
     
     # create another database
-    $finder->create_db('my_mp3s.db');
-    
-    # update the database from the filesystem
-    $finder->update_db('my_mp3s.db', ['/home/peter/mp3', '/home/peter/cds']);
+    $finder->create({ db_file => 'my_mp3s.db' });
+    
+    # update the database by searching the filesystem
+    $finder->update({
+	db_file => 'my_mp3s.db',
+	dirs => ['/home/peter/mp3', '/home/peter/cds'],
+    });
+
+    # or just update specific mp3s
+    $finder->update({
+	db_file => 'my_mp3s.db',
+	files => \@filenames,
+    });
     
     # and then blow it away
@@ -86,19 +95,10 @@
 =head1 DESCRIPTION
 
-This is the SQLite database backend for L<MP3::Find>.
-
-B<Note:> I'm still working out some kinks in here, so this backend
-is currently not as stable as the Filesystem backend.
-
-=head2 Special Options
-
-=over
-
-=item C<db_file>
-
-The name of the SQLite database file to use. Defaults to F<~/mp3.db>.
-
-The database should have at least one table named C<mp3> with the
-following schema:
+This is the database backend for L<MP3::Find>. The easiest way to
+use it is with a SQLite database, but you can also pass in your own
+DSN or database handle.
+
+The database you use should have at least one table named C<mp3> with 
+the following schema:
 
     CREATE TABLE mp3 (
@@ -133,11 +133,45 @@
     );
 
+B<Note:> I'm still working out some kinks in here, so this backend
+is currently not as stable as the Filesystem backend. Expect API
+fluctuations for now.
+
+B<Deprecated Methods:> C<create_db>, C<update_db>, and C<sync_db>
+have been deprectaed in this release, and will be removed in a future
+release. PLease switch to the new methods C<create>, C<update>, and
+C<sync>.
+
+=head2 Special Options
+
+When using this backend, provide one of the following additional options
+to the C<search> method:
+
+=over
+
+=item C<dsn>, C<username>, C<password>
+
+A custom DSN and (optional) username and password. This gets passed
+to the C<connect> method of L<DBI>.
+
+=item C<dbh>
+
+An already created L<DBI> database handle object.
+
+=item C<db_file>
+
+The name of the SQLite database file to use.
+
 =back
 
 =cut
 
+# get a database handle from named arguments
 sub _get_dbh {
     my $args = shift;
+
+    # we got an explicit $dbh object
     return $args->{dbh} if defined $args->{dbh};
+
+    # or a custom DSN
     if (defined $args->{dsn}) {
     	my $dbh = DBI->connect(
@@ -149,4 +183,5 @@
 	return $dbh;
     }
+    
     # default to a SQLite database
     if (defined $args->{db_file}) {
@@ -159,4 +194,5 @@
 	return $dbh;
     }
+
     return;
 }
@@ -182,6 +218,6 @@
 
 The C<status_callback> gets called each time an entry in the
-database is added, updated, or deleted by the C<update_db> and
-C<sync_db> methods. The arguments passed to the callback are
+database is added, updated, or deleted by the C<update> and
+C<sync> methods. The arguments passed to the callback are
 a status code (A, U, or D) and the filename for that entry.
 The default callback just prints these to C<STDERR>:
@@ -224,5 +260,5 @@
     $finder->create_db($db_filename);
 
-Creates a SQLite database in the file named c<$db_filename>.
+Creates a SQLite database in the file named C<$db_filename>.
 
 =cut
@@ -530,9 +566,7 @@
 =head1 TODO
 
-Database maintanence routines (e.g. clear out old entries)
-
-Allow the passing of a DSN or an already created C<$dbh> instead
-of a SQLite database filename; or write driver classes to handle
-database dependent tasks (create_db/destroy_db).
+Store/search ID3v2 tags
+
+Driver classes to handle database dependent tasks?
 
 =head1 SEE ALSO
Index: trunk/t/04-new-db.t
===================================================================
--- trunk/t/04-new-db.t	(revision 34)
+++ trunk/t/04-new-db.t	(revision 34)
@@ -0,0 +1,53 @@
+#!/usr/bin/perl -w
+use strict;
+
+use Test::More;
+
+BEGIN {
+    eval { require DBI };
+    plan skip_all => 'DBI required to use MP3::Find::DB backend' if $@;
+    eval { require DBD::SQLite };
+    plan skip_all => 'DBD::SQLite required to use MP3::Find::DB backend' if $@;
+    eval { require SQL::Abstract };
+    plan skip_all => 'SQL::Abstract required to use MP3::Find::DB backend' if $@;
+    
+    use_ok('MP3::Find::DB') 
+};
+
+plan tests => 7;
+
+my $SEARCH_DIR = 't/mp3s';
+my $DB_FILE = 't/mp3.db';
+my $DSN = "dbi:SQLite:dbname=$DB_FILE";
+my $MP3_COUNT = 1;
+
+# exercise the object using the new methods ("create", "update", "sync")
+
+my $finder = MP3::Find::DB->new(
+    status_callback => sub {},  # be quiet about updates
+);
+isa_ok($finder, 'MP3::Find::DB');
+
+eval { $finder->create  };
+ok($@, 'create dies when not given a database name');
+eval { $finder->update  };
+ok($@, 'update dies when not given a database name');
+
+
+# create a test db
+unlink $DB_FILE;
+$finder->create({ dsn => $DSN });
+ok(-e $DB_FILE, 'db file is there');
+
+my $count = $finder->update({ dsn => $DSN, dirs => $SEARCH_DIR });
+is($count, $MP3_COUNT, 'added all the mp3s to the db');
+
+$count = $finder->sync({ dsn => $DSN });
+is($count, 0, 'sync works properly');
+
+# remove the db
+$finder->destroy_db($DB_FILE);
+ok(!-e $DB_FILE, 'db file is gone');
+
+#TODO: get some test mp3s
+#TODO: write a set of common set of test querys and counts for all the backends