Hyperkey Database Basics

Hyperkey Database (HKDB) Files

  • Hyperkey associates keys, which are quoted character strings, with resource values, which typically are filenames, network locations, or URLs. Hyperkey stores these key-value associations in simple text-based database files. There can be any number of database files.
  • These files can be edited using an ordinary text editor such as the Windows Notepad program. In addition, Hyperkey provides database-access functions that will add or modify the database dbrec entries for you.
  • In the default implementation, all keys are stored in a single database file. As time goes on, you may choose to add other database files and link them together.
  • As an example, it is often very convenient to give each major project its own Hyperkey database (or hkdb) so that the project can be easily managed, or copied to other locations with its keys intact.
  • For the purposes of this initial discussion, it will be assumed that there is only one hkdb file.

Simple database entries

  • Inside the database files are database records (or dbrecs) which are single lines that associate a quoted string (key) with one or more resource value(s).
  • In a mature installation, there may be hundreds of key-resource dbrecs within an HKDB file. Each dbrec is a single line, that identifies a single key.
  • As a simple example, we could create a shortcut dbrec that associates the key 'g' with the 'Google' website:

    • "g"    "www.google.com"

  • Then we could launch a browser to open the "www.google.com" web page by the simple command:

    • s g

  • For simple shortcut keys only one resource value is specified, which is the location of the file or URL, as in the example above.
  • When Hyperkey is used to synchronize two locations or do backups, the key's association requires that two locations be specified: the 'local' location and the 'server' location.
  • These are arbitrary designations. Any two locations can be marked as either type when using the key for synchronization. But when keys are used to do backups and restores, the 'local' location is presumed to be where changes will be made, and the 'server' location is presumed to be where the backups will be stored.
  • As a simple example, we could create a backup dbrec that allows us to backup copies of file 'mybook.txt' using the key 'mybook':

    • "mybook"  "C:\Users\Myuser\MyDocs\Books\mybook.txt"  "X:\Ar\MyDocs\Books\mybook.txt"  -f

  • Then we could create 'snapshot' backups as we make modifications to 'mybook.txt' by the simple command:

    • b mybook

  • In this example, the key "mybook" refers to two locations, with the 'local' version being in folder "C:\Users\Myuser\MyDocs\Books" and the 'server' version being in folder "/Server/Ar\MyDocs\Books". If we were to use this key to do backups of file "mybook.txt", the server location would contain the last saved version of the file, while the local version might have the latest revisions. As we do backups, the server side will store one copy of the file for each backup that was done.

Structure of the database files

  • The database file format has a simple organization, but Hyperkey depends upon that file being correctly structured.
  • While in simple cases specifying the full paths of the local and server locations of a key works well, the HKDB files can become tediously unreadable when there are a large number of dbrecs that all refer to the same server locations, especially if the server paths are quite long.
  • The database files therefore are organized to simplify specifying the key associations for local and servers locations.
  • In most projects, the file names associated with a key will terminate with the same sub-paths in both the local and server paths, because the backup (server) copy needs to have the same overall strucure as the original (local). For instance, in the previous example above, the server and local paths of key 'mybook' both end with "MyDocs\Books\mybook.txt".
  • HKDB files make the specifications simpler and clearer by factoring out the trailing portions of paths in common between the local and the server locations.
  • This is done in two ways, within the dbrec, and within the server header records.
  • Factoring shared sub-paths in the dbrec
  • The dbrec record format has an easy way to factor out the duplicate portion of the file paths, making the record smaller and more legible.
  • The basic dbrec records have tab-separated fields and have the following syntax:
    • "<key>"
      <local-res>
      [<server-path>
      [<shared-path>]]
      <dbrec-opt>*
       
      where:
      <local-res>
      :=
      <loc-path> | <url> | <actions>
      <loc-path>>
      :=
      Filename path to local location
      <server-path>
      :=
      Filename path to server location
      <shared-path>
      :=
      Portion of path common to both local and server
      <dbrec-opt>
      :=
      -f
      | <other-opt>
      <other-opt>
      :=
      (Discussed later)
  • The optional <shared-path> field allows the dbrec to specify the trailing portion of the file names that the local and server paths have in common, condensing the record. For example the previous example can be specified as:

    • "mybook"  "C:\Users\Myuser"  "X:\Ar"  "MyDocs\Books\mybook.txt"  -f

  • Notice that the 'local' and 'server' path fields no longer mention the trailing portion of the paths, because they are in the <shared-path> field.
  • Server header records
  • In addition to dbrec records, Hyperkey also uses server header records. These records factor out some or all of the server path from the <server-path> field of the dbrecs that follow them, and have the following syntax:
    • ><integer>[+]
      <server-base-path>
       
      where:
      <server-base-path>
      :=
      Base filename path of server location
  • In the example above, a header record can be added specifying the server path, which factors that portion of the path out of the <server-path> field. Because the entire path was factored out the <server-path> becomes an empty string:

    • >1  X:\Ar
      "mybook"  "C:\Users\Myuser"  ""  "MyDocs\Books\mybook.txt"  -f

  • The server path level (>1 in the above example) defines the depth of the current server base path. This depth specification can be used to create a second level of sub-path factoring.
  • If a server path level with a higher path level and a '+' suffix follows one with a lower path level, the difference in the two paths is factored out, and applied to both the server and the local paths.
  • For example:

    • >1   X:\Ar
      >2+  X:\Ar\MyDocs\Books
      "mybook"  "C:\Users\Myuser"  ""  "mybook.txt"  -f

  • would produce the same result as the examples before.
  • In this example the difference between 'X:\Ar\MyDocs\Books' and 'X:\Ar' is '\MyDocs\Books'. So that substring is appended to both the local and the server path strings, then the factored path substring "mybook.txt" is appended them both.
  • Thus:

    • local  = "C:\Users\Myuser" + "\MyDocs\Books" + "mybook.txt"  = "C:\Users\Myuser\MyDocs\Books\mybook.txt"
      server = "X:\Ar" + "\MyDocs\Books" + "mybook.txt"            = "X:\Ar\MyDocs\Books\mybook.txt"

  • which creates the same paths as the original "mybook" example above.
Previous: Introduction Next: Adding Keys