/ Check-in [100137c7]
Login

Many hyperlinks are disabled.
Use anonymous login to enable hyperlinks.

Overview
Comment:Enhance ext/zonefile/README.md to describe the currently available functionality.
Downloads: Tarball | ZIP archive | SQL archive
Timelines: family | ancestors | descendants | both | zonefile
Files: files | file ages | folders
SHA3-256:100137c7f68b2d9a329d6d43e6c0a81b6ac843678b670ab6cce5f510bc58b7a8
User & Date: dan 2018-02-13 19:01:08
Context
2018-02-13
20:08
Fix handling of maxAutoFrameSize parameter. check-in: d65e5855 user: dan tags: zonefile
19:01
Enhance ext/zonefile/README.md to describe the currently available functionality. check-in: 100137c7 user: dan tags: zonefile
18:02
Remove, for now, the "priority" column from the zonefile_files virtual table. check-in: 8bf5154b user: dan tags: zonefile
Changes
Hide Diffs Unified Diffs Ignore Whitespace Patch

Changes to ext/zonefile/README.md.

1
























































































2
3
4
5
6
7
8
9
..
18
19
20
21
22
23
24
25
26
27

























































































Notes:

  *  Contrary to the spec, the implementation uses 32-bit (not 16-bit) frame
     numbers. So the KeyOffsetPair structure becomes:

     KeyOffsetPair
     {
       uint64  key;
................................................................................
  *  Multi-byte integer values are big-endian.

  *  The offsets in the ZoneFileIndex.byteOffsetZoneFrame[] array are
     relative to the offset in ZoneFileHeader.byteOffsetFrames. This is
     necessary as we may not know the offset of the start of the frame data
     until after the ZoneFileIndex structure is compressed.

  *  Currently there is no support for encryption or compression.



>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|







 







|


1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
...
106
107
108
109
110
111
112
113
114
115

# The Zonefile Extension

## Functionality

### Creating Zonefile Files

To create a new zonefile, first create a database table with the following
schema:

>     CREATE TABLE data(
>       k INTEGER PRIMARY KEY,
>       frame INTEGER DEFAULT -1,   -- frame number.  Automatic if -1
>       idx INTEGER DEFAULT -1,     -- index of entry within frame.  Auto if -1
>       v BLOB
>     );

The table may be created in a persistent or temporary database and may
take any name, but must contain the columns above. The table must be 
populated with a row for each key intended to appear in the new zonefile
file.

Once the table is populated, a zonefile is created using the following
SQL:

>     SELECT zonefile_write(<file>, <table> [, <parameters>]);

where &lt;file&gt; is the name of the file to create on disk, &lt;table&gt; 
is the name of the database table to read and optional argument 
&lt;parameters&gt; is a JSON object containing various attributes that
influence creation of the zonefile file. 

Currently the only &lt;parameters&gt; attribute supported is 
<i>maxAutoFrameSize</i>, which sets the maximum frame size in bytes for
automatically generated zonefile frames. 

For example, to create a zonefile named "test.zonefile" based on the
contents of database table "test_input" and with a maximum automatic
frame size of 4096 bytes:

>     SELECT zonefile_write('test.zonefile', 'test_input',
>       '{"maxAutoFrameSize":4096}'
>     );

### Using (Reading) Zonefile Files

To create a new zonefile table:

>     CREATE VIRTUAL TABLE z1 USING zonefile;

This creates two virtual tables in the database schema. One read-only table
named "z1", with a schema equivalent to:

>     CREATE TABLE z1(  -- this whole table is read-only
>       k INTEGER PRIMARY KEY,
>       v BLOB,
>       fileid INTEGER,
>       frame INTEGER,
>       ofst INTEGER,
>       sz INTEGER
>     );

And a read-write table named "z1_files" with a schema like:

>     CREATE TABLE z1_files(
>       filename TEXT PRIMARY KEY,
>       ekey BLOB,         -- encryption key
>       fileid INTEGER,    -- read-only
>       header JSON HIDDEN -- read-only
>     );

Both tables are initially empty. To add a zonefile to the index, insert a
row into the "z1_files" table:

>     INSERT INTO z1_files(filename) VALUES(<filename>);

Currently, any value provided for any column other than "filename" is 
ignored. Files are removed from the index by deleting rows from the
z1_files table:

>     DELETE FROM z1_files WHERE filename = <filename>;

Once zonefile files have been added to the index, their contents are 
visible in table "z1". To retrieve the value associated with a single
key from one of the zonefile files in the index:

>     SELECT v FROM z1 WHERE k = <key>;


## Notes

  *  Contrary to the spec, the implementation uses 32-bit (not 16-bit) frame
     numbers. So the KeyOffsetPair structure becomes:

     KeyOffsetPair
     {
       uint64  key;
................................................................................
  *  Multi-byte integer values are big-endian.

  *  The offsets in the ZoneFileIndex.byteOffsetZoneFrame[] array are
     relative to the offset in ZoneFileHeader.byteOffsetFrames. This is
     necessary as we may not know the offset of the start of the frame data
     until after the ZoneFileIndex structure is compressed.

  *  Currently there is no support at all for encryption or compression.