lib: API to retrieve database revision and UUID

This exposes the committed database revision to library users along
with a UUID that can be used to detect when revision numbers are no
longer comparable (e.g., because the database has been replaced).

diff --git a/lib/database-private.h b/lib/database-private.h
index 5c5a2bb2e51b416f0a0e9840acf5133d247bf9df..4e932572ac7a7ea9f45c5328989cf1b1dade1955 100644 (file)
--- a/lib/database-private.h
+++ b/lib/database-private.h
@@ -170,6 +170,7 @@ struct _notmuch_database {
      * under a higher revision number, which can be generated with
      * notmuch_database_new_revision. */
     unsigned long revision;
+    const char *uuid;
 
     Xapian::QueryParser *query_parser;
     Xapian::TermGenerator *term_gen;

diff --git a/lib/database.cc b/lib/database.cc
index 52e2e8f16187bfc4dcd17b81c02473b95ebc2660..fc78769318cce7d15f0e950a3b638d2f68a6a920 100644 (file)
--- a/lib/database.cc
+++ b/lib/database.cc
@@ -992,6 +992,8 @@ notmuch_database_open_verbose (const char *path,
            notmuch->revision = 0;
        else
            notmuch->revision = Xapian::sortable_unserialise (last_mod);
+       notmuch->uuid = talloc_strdup (
+           notmuch, notmuch->xapian_db->get_uuid ().c_str ());
 
        notmuch->query_parser = new Xapian::QueryParser;
        notmuch->term_gen = new Xapian::TermGenerator;
@@ -1666,6 +1668,15 @@ DONE:
     return NOTMUCH_STATUS_SUCCESS;
 }
 
+unsigned long
+notmuch_database_get_revision (notmuch_database_t *notmuch,
+                               const char **uuid)
+{
+    if (uuid)
+       *uuid = notmuch->uuid;
+    return notmuch->revision;
+}
+
 /* We allow the user to use arbitrarily long paths for directories. But
  * we have a term-length limit. So if we exceed that, we'll use the
  * SHA-1 of the path for the database term.

diff --git a/lib/notmuch.h b/lib/notmuch.h
index b1f5bfa161f77853b8c4e40a90605c6595e1ab91..8639b383f3352c2e7842fc47de94101b9f490860 100644 (file)
--- a/lib/notmuch.h
+++ b/lib/notmuch.h
@@ -467,6 +467,24 @@ notmuch_database_begin_atomic (notmuch_database_t *notmuch);
 notmuch_status_t
 notmuch_database_end_atomic (notmuch_database_t *notmuch);
 
+/**
+ * Return the committed database revision and UUID.
+ *
+ * The database revision number increases monotonically with each
+ * commit to the database.  Hence, all messages and message changes
+ * committed to the database (that is, visible to readers) have a last
+ * modification revision <= the committed database revision.  Any
+ * messages committed in the future will be assigned a modification
+ * revision > the committed database revision.
+ *
+ * The UUID is a NUL-terminated opaque string that uniquely identifies
+ * this database.  Two revision numbers are only comparable if they
+ * have the same database UUID.
+ */
+unsigned long
+notmuch_database_get_revision (notmuch_database_t *notmuch,
+                               const char **uuid);
+
 /**
  * Retrieve a directory object from the database for 'path'.
  *

diff --git a/test/T570-revision-tracking.sh b/test/T570-revision-tracking.sh
new file mode 100755 (executable)
index 0000000..e0a5703
--- /dev/null
+++ b/test/T570-revision-tracking.sh
@@ -0,0 +1,37 @@
+#!/usr/bin/env bash
+test_description="database revision tracking"
+
+. ./test-lib.sh || exit 1
+
+add_email_corpus
+
+test_begin_subtest "notmuch_database_get_revision"
+test_C ${MAIL_DIR} <<'EOF'
+#include <stdio.h>
+#include <string.h>
+#include <notmuch.h>
+int main (int argc, char** argv)
+{
+   notmuch_database_t *db;
+   notmuch_status_t stat;
+   unsigned long revision;
+   const char *uuid;
+
+   unsigned long rev;
+
+   stat = notmuch_database_open (argv[1], NOTMUCH_DATABASE_MODE_READ_ONLY, &db);
+   if (stat)
+       fputs ("open failed\n", stderr);
+   revision = notmuch_database_get_revision (db, &uuid);
+   printf("%s\t%lu\n", uuid, revision);
+}
+EOF
+notmuch_uuid_sanitize < OUTPUT > CLEAN
+cat <<'EOF' >EXPECTED
+== stdout ==
+UUID   53
+== stderr ==
+EOF
+test_expect_equal_file EXPECTED CLEAN
+
+test_done

diff --git a/test/test-lib.sh b/test/test-lib.sh
index 0bf7163e9f34863c9671689cdca98dcca0cfd85b..126911fb385aacb7aa087ab9c7c099419c7641fd 100644 (file)
--- a/test/test-lib.sh
+++ b/test/test-lib.sh
@@ -720,6 +720,11 @@ notmuch_date_sanitize ()
     sed \
        -e 's/^Date: Fri, 05 Jan 2001 .*0000/Date: GENERATED_DATE/'
 }
+
+notmuch_uuid_sanitize ()
+{
+    sed 's/[0-9a-f]\{8\}-[0-9a-f]\{4\}-[0-9a-f]\{4\}-[0-9a-f]\{4\}-[0-9a-f]\{12\}/UUID/g'
+}
 # End of notmuch helper functions
 
 # Use test_set_prereq to tell that a particular prerequisite is available.