YeltsinDB/table_file_v0.md

# Table file structure (v0)

Notice that this version is not supported now. Use v1 documentation instead.

## Table file version changelog

### v0.2
+ Added table "write incomplete" flag.

### v0.1
Initial version.

## v0.x specification

1. `TBL!` file signature (4 bytes) **could be `TBL?` if an operation on a table is incompleted**
2. Table file version (2 bytes)
3. The offset to the first page in a table. (8 bytes)
4. The offset to the last page in a table. (8 bytes)
5. The offset to the last available *free* page (8 bytes)
6. Pages (64 KiB each)
    1. Page flags (1 byte)
    2. Next page offset (8 bytes) **could be 0 if last page**
    3. Row count (2 bytes)
    4. Rows
        1. Row flags (1 byte)
        2. Row data

## Table file version specification

In the further time, it's planned to rewrite the file structure, so it's useful to have a version marker.

|     15-8      |      7-0      |
|---------------|---------------|
| Major version | Minor version |

That means that the first byte defines major version, and the second one defines minor version.

If tables with different versions are binary-compatible with each other, their major version must be the same. 

## Page flags specification

|  7  |  6  |  5  |  4  |  3  |  2  |  1  |  0  |
|-----|-----|-----|-----|-----|-----|-----|-----|
| RSV | RSV | RSV | RSV | RSV | RSV | RSV | DEL |

- **RSV** -- reserved for further usage.
- **DEL** -- free page flag. 

## Row flags specification

See "Page flags specification" above.

## Free pages

A page can be called *free* iff all its rows are deleted. 
If there is a free page, there actions are being done:

1. Set `DEL` page flag ((6.1) |= FLAG_DEL)
2. If a page is **not** the first one, replace next page offset in the previous page with a value in current page 
((previous 6.2) = (6.2))
3. Put last available free page as the next page ((6.2) = 5)
4. Set current page offset as the offset to the last available free page ((5) = current_page_offset)

## File signature

*Since v0.2* a file signature could be `TBL?`, which signals for incomplete table write operation.
If that signature is detected, the state of a table should be reverted to that it was before failed
transaction.