From: dan Date: Tue, 13 Feb 2018 19:01:08 +0000 (+0000) Subject: Enhance ext/zonefile/README.md to describe the currently available X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=3f9402e1151376acbdc2ee258eeb667474b3bfff;p=thirdparty%2Fsqlite.git Enhance ext/zonefile/README.md to describe the currently available functionality. FossilOrigin-Name: 100137c7f68b2d9a329d6d43e6c0a81b6ac843678b670ab6cce5f510bc58b7a8 --- diff --git a/ext/zonefile/README.md b/ext/zonefile/README.md index d70b07e835..ac79d3e1de 100644 --- a/ext/zonefile/README.md +++ b/ext/zonefile/README.md @@ -1,5 +1,93 @@ -Notes: +# 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(, [, ]); + +where <file> is the name of the file to create on disk, <table> +is the name of the database table to read and optional argument +<parameters> is a JSON object containing various attributes that +influence creation of the zonefile file. + +Currently the only <parameters> attribute supported is +maxAutoFrameSize, 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(); + +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 = ; + +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 = ; + + +## Notes * Contrary to the spec, the implementation uses 32-bit (not 16-bit) frame numbers. So the KeyOffsetPair structure becomes: @@ -22,6 +110,6 @@ Notes: 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. + * Currently there is no support at all for encryption or compression. diff --git a/manifest b/manifest index 4fa25bd681..22ad5f1504 100644 --- a/manifest +++ b/manifest @@ -1,5 +1,5 @@ -C Remove,\sfor\snow,\sthe\s"priority"\scolumn\sfrom\sthe\szonefile_files\svirtual\stable. -D 2018-02-13T18:02:00.303 +C Enhance\sext/zonefile/README.md\sto\sdescribe\sthe\scurrently\savailable\nfunctionality. +D 2018-02-13T19:01:08.333 F .fossil-settings/empty-dirs dbb81e8fc0401ac46a1491ab34a7f2c7c0452f2f06b54ebb845d024ca8283ef1 F .fossil-settings/ignore-glob 35175cdfcf539b2318cb04a9901442804be81cd677d8b889fcc9149c21f239ea F Makefile.in 7a3f714b4fcf793108042b7b0a5c720b0b310ec84314d61ba7f3f49f27e550ea @@ -408,7 +408,7 @@ F ext/session/test_session.c eb0bd6c1ea791c1d66ee4ef94c16500dad936386 F ext/userauth/sqlite3userauth.h 7f3ea8c4686db8e40b0a0e7a8e0b00fac13aa7a3 F ext/userauth/user-auth.txt e6641021a9210364665fe625d067617d03f27b04 F ext/userauth/userauth.c 3410be31283abba70255d71fd24734e017a4497f -F ext/zonefile/README.md 1b5c62cad3ec25d48b28f2550d390768fdfef6d088ff9db8af676ab64f6c4530 +F ext/zonefile/README.md fd8039cb0b421059ef90d014b4d71a1e376cb7d1210e80a896d76908708669e4 F ext/zonefile/zonefile.c 212c9a8778759c292685a0915ff5bcbdb9d279c2fe791021572617971c896c5b F ext/zonefile/zonefile1.test 8904658bd8332dc0d0c77c0c74c9c83dce4123a442bb971d5baf00170f6d0afe F install-sh 9d4de14ab9fb0facae2f48780b874848cbf2f895 x @@ -1708,7 +1708,7 @@ F vsixtest/vsixtest.tcl 6a9a6ab600c25a91a7acc6293828957a386a8a93 F vsixtest/vsixtest.vcxproj.data 2ed517e100c66dc455b492e1a33350c1b20fbcdc F vsixtest/vsixtest.vcxproj.filters 37e51ffedcdb064aad6ff33b6148725226cd608e F vsixtest/vsixtest_TemporaryKey.pfx e5b1b036facdb453873e7084e1cae9102ccc67a0 -P fdb6c0c5dc5a67ca16dfafc6e677f73936f36e357a2ff288b4958ddee0544603 -R 7ee10389f1633a4ccc7da396851ded16 +P 8bf5154bc6e31e206931d97c743eadaba4ef938c11e006082d795439dadaeb8f +R ac88557d5661bd1ac981fca2d5815858 U dan -Z 0a6dede478fe88813cd34fe2d513e5c6 +Z 857bf6fa80777d961d06ea17c5dbe1b2 diff --git a/manifest.uuid b/manifest.uuid index 27cdec9c18..994eb4acdd 100644 --- a/manifest.uuid +++ b/manifest.uuid @@ -1 +1 @@ -8bf5154bc6e31e206931d97c743eadaba4ef938c11e006082d795439dadaeb8f \ No newline at end of file +100137c7f68b2d9a329d6d43e6c0a81b6ac843678b670ab6cce5f510bc58b7a8 \ No newline at end of file