[tor-commits] [stem/master] Versioning for manual's sqlite schema

[atagar at torproject.org]

commit 20d95610e29e7fd60a38512d96a5094d0200e2ae
Author: Damian Johnson <atagar at torproject.org>
Date:   Mon Aug 28 12:35:38 2017 -0700

    Versioning for manual's sqlite schema
    
    We'll adjust the schema from time to time so we need to be able to detect if a
    loaded database is compatable with us.
---
 stem/cached_tor_manual.sqlite | Bin 217088 -> 217088 bytes
 stem/manual.py                |  16 ++++++++++++----
 2 files changed, 12 insertions(+), 4 deletions(-)

diff --git a/stem/cached_tor_manual.sqlite b/stem/cached_tor_manual.sqlite
index b35a3c5e..81d0b230 100644
Binary files a/stem/cached_tor_manual.sqlite and b/stem/cached_tor_manual.sqlite differ
diff --git a/stem/manual.py b/stem/manual.py
index 9537c740..e520f2f8 100644
--- a/stem/manual.py
+++ b/stem/manual.py
@@ -84,6 +84,7 @@ Category = stem.util.enum.Enum('GENERAL', 'CLIENT', 'RELAY', 'DIRECTORY', 'AUTHO
 GITWEB_MANUAL_URL = 'https://gitweb.torproject.org/tor.git/plain/doc/tor.1.txt'
 CACHE_PATH = os.path.join(os.path.dirname(__file__), 'cached_tor_manual.sqlite')
 DATABASE = None  # cache database connections
+SCHEMA_VERSION = 1  # version of the schema used by our sqlite cache
 
 CATEGORY_SECTIONS = OrderedDict((
   ('GENERAL OPTIONS', Category.GENERAL),
@@ -357,7 +358,8 @@ class Manual(object):
 
     :returns: :class:`~stem.manual.Manual` with our bundled manual information
 
-    :raises: **IOError** if a **path** was provided and we were unable to read it
+    :raises: **IOError** if a **path** was provided and we were unable to read
+      it or the schema is out of date
     """
 
     # TODO: drop _from_config_cache() with stem 2.x
@@ -376,7 +378,13 @@ class Manual(object):
       raise IOError("%s doesn't exist" % path)
 
     with sqlite3.connect(path) as conn:
-      name, synopsis, description, man_commit, stem_commit = conn.execute('SELECT name, synopsis, description, man_commit, stem_commit FROM metadata').fetchone()
+      try:
+        name, synopsis, description, man_commit, stem_commit, schema = conn.execute('SELECT name, synopsis, description, man_commit, stem_commit, schema FROM metadata').fetchone()
+      except sqlite3.OperationalError as exc:
+        raise IOError('Failed to read database metadata from %s: %s' % (path, exc))
+
+      if schema != SCHEMA_VERSION:
+        raise IOError("Stem's current manual schema version is %s, but %s was version %s" % (SCHEMA_VERSION, path, schema))
 
       commandline = dict(conn.execute('SELECT name, description FROM commandline').fetchall())
       signals = dict(conn.execute('SELECT name, description FROM signals').fetchall())
@@ -528,13 +536,13 @@ class Manual(object):
 
   def _save_as_sqlite(self, path):
     with sqlite3.connect(path + '.new') as conn:
-      conn.execute('CREATE TABLE metadata(name TEXT, synopsis TEXT, description TEXT, man_commit TEXT, stem_commit TEXT)')
+      conn.execute('CREATE TABLE metadata(name TEXT, synopsis TEXT, description TEXT, man_commit TEXT, stem_commit TEXT, schema NUMBER)')
       conn.execute('CREATE TABLE commandline(name TEXT PRIMARY KEY, description TEXT)')
       conn.execute('CREATE TABLE signals(name TEXT PRIMARY KEY, description TEXT)')
       conn.execute('CREATE TABLE files(name TEXT PRIMARY KEY, description TEXT)')
       conn.execute('CREATE TABLE torrc(key TEXT PRIMARY KEY, name TEXT, category TEXT, usage TEXT, summary TEXT, description TEXT, position NUMBER)')
 
-      conn.execute('INSERT INTO metadata(name, synopsis, description, man_commit, stem_commit) VALUES (?,?,?,?,?)', (self.name, self.synopsis, self.description, self.man_commit, self.stem_commit))
+      conn.execute('INSERT INTO metadata(name, synopsis, description, man_commit, stem_commit, schema) VALUES (?,?,?,?,?,?)', (self.name, self.synopsis, self.description, self.man_commit, self.stem_commit, SCHEMA_VERSION))
 
       for k, v in self.commandline_options.items():
         conn.execute('INSERT INTO commandline(name, description) VALUES (?,?)', (k, v))