serialize - Persistent storage for relations
This manpage describes a set of commands that are used for saving the values of relvars on external storage. All of the output commands below take an optional pattern argument. If present, then the command is applied to relvars that match the given pattern. Otherwise by default all relvars are considered. All of the input commands below take an optional namespace argument. If present, then the command will restore the relvars relative to the given namespace. Otherwise, relvars are restored relative to the global namespace. Upon serialization and output, the entire relvar name path is maintained. This allows relvars to be restored to their same relative positions in a different namespace from which they were originally taken. Since TclRAL manages relvar names using namespace-like syntax, this may be used to manage distinct sets of relvars without risking naming conflicts.
The serialize command returns a string that represents the values and constraints for all of the relvars contained within namespace. The string returned by serialize may be given to deserialize to restore the values of the relvars.
The serializeToFile command invokes serialize and places the resulting serialization string into the file given by fileName.
The deserialize command restores the values and constraints on a set of relvars. The serialization argument must be a value returned from the serialize command. If the namespace argument is given, then the relvars and constraints are placed in the given namespace which need not exist prior to invoking the command. The deserialize command also uses a set of heuristics to attempt to deserialize relvar data originally composed by the 0.8.X revisions of ral. If it determines that the data may be from an older version, then deserialize-0.8.X is invoked to restore the values. The deserialize-0.8.X command may be invoked directly, see below.
The deserializeFromFile command reads the file given by the fileName argument and invokes deserialize on its contents.
The merge command merges the relvars and constraints contained in serialization. If namespace is given then the merge is into that namespace and otherwise the merge is into the global namespace. The merge attempts to do a union of the relvars and constraints onto those already existing. The merge is done strictly be name with no consideration of structure, meaning that any relvars or constraints in serialization that do not currently exist are created, but existing relvars and constraints whose names match those in serialization have their structure preserved. The relation values of the relvars contained in serialization are unioned against the existing relvar by the same name. The return value of the command is a list of relvar names for which the union operation fails. The union of relvar values is carried out in a transaction.
The mergeFromFile command invokes ::ral::merge on the contents of the file given by the fileName argument.
The deserialize-0.8.X command provides a way to read relvar values and constraints that were stored using the 0.8.X revisions of ral.
The deserializeFromFile-0.8.X command invokes deserialize-0.8.X on the contents of the fileName file.
The storeToMk command stores the state of a set of relvars into a metaKit database. Each relvar is stored in a separate metaKit view. Several additional views are created to hold system catalog information. The additional views have names that start with __ral. If fileName exists already, it is renamed to be fileName~ before a new file is created with the current state of the relvars.
The loadFromMk command restores the state of a set of relvars from the information contained in a metaKit database. That database must have been created using the storeToMk command.
The mergeFromMk command merges the contents of the metakit contained in fileName into the namespace given by namespace. The rules of merging are the same as described for the merge command above.
The storeToSQLite command stores the state of a set of relvars into a SQLite database. Each relvar is stored in a separate SQL table. The schema created for the relvars includes referential (a.k.a. foreign key) constraints and creates indices for both identifiers and foreign key references. No all TclRAL constraints can be enforced by an SQL database, but many as can be mapped to SQL foreign key references. Several additional tables are created to hold system catalog information. The additional tables have names that start with __ral and they hold information that allows the relvar state to be restored exactly. If fileName exists already, it is renamed to be fileName~ before a new file is created with the current state of the relvars.
The loadFromSQLite command restores the state of a set of relvars from the information contained in a SQLite database. That database must have been created using the storeToSQLite command.
The dump command returns a Tcl script that when evaluated will restore the state of a set of relvars to be the same as when the dump command was executed. The dump command is another form of serialization for a set of relvars and is often useful when creating Tcl packages that create an empty schema of relvars.
The dumpToFile invokes the dump command and writes the resulting script to the file given by fileName.
The format used generated by serialize and expected by deserialize is a Tcl list consisting of eight elements. List elements form a dictionary whose keys denote the parts of the serialization and whose values contain the relvar information as described below.
Version <library version>
Relvars <list of relvar defs>
<relvar name>
<relation heading>
<list of relvar identifiers>
Constraints <list of constraints>
association | partition | correlation
<constraint definition>
<association constraint definition>
<association name> <relvar name> <attribute list> <mult/cond> <relvar name> <attribute list> <mult/cond>
<partition constraint definition>
<partition name> <superset> <attribute list> <subset1> <attribute list> <subset2> <attribute list> ...
<correlation constraint definition>
<?-complete?> <correlation name> <relvar name> <attribute list> <mult/cond> <relvar name> <attribute list> <attribute list> <mult/cond> <relvar name> <attribute list>
Values <list of relvar names/relation values>
<relvar name>
<relation value>
Copyright © 2004 - 2010 by G. Andrew Mangogna