17.3. SQL table names

Objects streamed to the instance of ccs::serialization::storage are called top-level objects. All other objects are non-top-level objects. The set of all top-level and non-top-level objects stored into one instance of the storage class is termed the "object set".

Database files can have more than one object set. This is done by specifying a different name for each object set. The name is specified during the construction of the instance of the storage class. The default name is "T". This name is used as the prefix for all of the tables created for the object set. The table names will be the prefix followed by an unsigned integer value starting at zero. This prefix must satisfy the naming constraints of SQL tables, which effectively means that it should always start with an alphabetic character, and not a numeric digit. If the name ends with a numeric digit then "_" will be appended to the name to prevent table name conflicts from occurring.

Assume we are using the default name "T". Table T0 will contain two columns: a column named id (a.k.a. ROWID) of type INTEGER PRIMARY KEY, and a column named C0 of type TEXT. The first row of T0 (ie, the row with ROWID=1) will contain an integer value that corresponds to the last table in the object set. For example, if the value is 18, then this object set will exists in tables T0, T1, T2, ..., T17, T18. By storing the last table's name, the library will know which tables it needs to delete to reset the object set's contents (whether it will reset the contents is determined by the second parameter to the constructor of the storage class). Subsequent rows in T0 will have column C0 containing the value of the top-level objects streamed to the storage instance.

If the object is not one of the "native SQL types", ie, it is not an integer, floating point value, string, std::tm, or binary data blob, then column C0 will contain the name, row index, row count and column count of where the object's data is stored in the database. For example, storing an instance of the Person class (see the Quick Tutorial section above) will cause a table with 5 columns to be created: a ROWID column, an INTEGER column for the gender, a TEXT column for the name, a TEXT column for the address, and an INTEGER column for the age. Suppose this is created in table T7. Then if the first Person object stored in the database is a top-level object, it will be in a row in table T0 with a column C0 value of "7;0;1;4". The 7 refers to table 7, the 0 is the row index (ie, the first row), the 1 is the row count (only one object was stored), and the 4 is the column count (the count does not include the ROWID column). This is, effectively, a "pointer" to the stored data, and is used for all non-native SQL types that are stored in the database.