From: dan <dan@noemail.net>
Date: Tue, 26 Feb 2019 16:36:21 +0000 (+0000)
Subject: Update doc/shared_schema.md to describe the shell tool ".shared-schema" dot-command.
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=22b16ac3d0da1cf4813b63eec15b8c90fe14d432;p=thirdparty%2Fsqlite.git

Update doc/shared_schema.md to describe the shell tool ".shared-schema" dot-command.

FossilOrigin-Name: 0ce2092a5968d75d014fdc238391c362a9600c28bf18cdc631e98259a5278712
---

diff --git a/doc/shared_schema.md b/doc/shared_schema.md
index 38c325289a..a8a7d32a35 100644
--- a/doc/shared_schema.md
+++ b/doc/shared_schema.md
@@ -31,6 +31,65 @@ SQLITE&#95;DBSTATUS&#95;SCHEMA&#95;USED sqlite3&#95;db&#95;status() verb
 distributes the memory used for a shared schema object evenly between all
 database connections that share it.
 
+## The ".shared-schema" Command
+
+The shell tool on this branch contains a special dot-command to help with
+managing databases. The ".shared-schema" dot-command can be used to test
+whether or not two databases are similar enough to share in-memory schemas,
+and to fix minor problems that prevent them from doing so. To test if
+two or more database are compatible, one database is opened directly using 
+the shell tool and the following command issued:
+
+        .shared-schema check <database-1> [<database-2>]...
+
+where &lt;database-1;&gt; etc. are replaced with the names of database files
+on disk. For each database specified on the command line, a single line of
+output is produced. If the database can share an in-memory schema with the
+main database opened by the shell tool, the output is of the form:
+
+        <database> is compatible
+
+Otherwise, if the database cannot share a schema with the main db, the output
+is of the form:
+
+        <database> is NOT compatible (<reason>)
+
+where &lt;reason&gt; indicates the cause of the incompatibility. &lt;reason&gt;
+is always one of the following.
+
+<ul>
+  <li> <b>objects</b> - the databases contain a different set schema objects
+  (tables, indexes, views and triggers).
+
+  <li> <b>SQL</b> - the databases contain the same set of objects, but the SQL
+  statements used to create them were not the same.
+
+  <li> <b>root pages</b> - the databases contain the same set of objects created
+  by the same SQL statements, but the root pages are not the same.
+
+  <li> <b>order of sqlite&#95;master rows</b> - the databases contain the same
+  set of objects created by the same SQL statements with the same root pages,
+  but the order of the rows in the sqlite&#95;master tables are different.
+
+  <li> <b>schema cookie</b> - the database schemas are compatible, but the 
+  schema cookie values ("PRAGMA schema&#95;version") are different.
+</ul>
+
+The final three problems in the list above can be fixed using the
+.shared-schema command. To modify such a database so that it can share a 
+schema with the main database, the following shell command is used:
+
+        .shared-schema fix <database-1> [<database-2>]...
+
+If a database can be modified so that it may share a schema with the main
+database opened by the shell tool, output is as follows:
+
+        Fixing <database>... <database> is compatible
+
+If a database does not require modification, or cannot be modified such that
+it can share a schema with the main database, the output of "fix" is identical
+to that of the "check" command.
+
 ## Implementation Notes
 
 A single Schema object is never used by more than one database simultaneously,
diff --git a/manifest b/manifest
index 0f1a6af284..5b13c039df 100644
--- a/manifest
+++ b/manifest
@@ -1,5 +1,5 @@
-C Add\snew\stest\sfile\sreuse5.test.\sFor\stesting\sthe\sshell\stool\s".shared-schema"\scommand.
-D 2019-02-26T16:13:43.604
+C Update\sdoc/shared_schema.md\sto\sdescribe\sthe\sshell\stool\s".shared-schema"\sdot-command.
+D 2019-02-26T16:36:21.259
 F .fossil-settings/empty-dirs dbb81e8fc0401ac46a1491ab34a7f2c7c0452f2f06b54ebb845d024ca8283ef1
 F .fossil-settings/ignore-glob 35175cdfcf539b2318cb04a9901442804be81cd677d8b889fcc9149c21f239ea
 F Makefile.in 56456706c4da271309914c756c9c8ea537685f1c79f8785afa72f968d6810482
@@ -39,7 +39,7 @@ F contrib/sqlitecon.tcl 210a913ad63f9f991070821e599d600bd913e0ad
 F doc/F2FS.txt c1d4a0ae9711cfe0e1d8b019d154f1c29e0d3abfe820787ba1e9ed7691160fcd
 F doc/lemon.html 24956ab2995e55fe171e55bdd04f22b553957dc8bb43501dbb9311e30187e0d3
 F doc/pager-invariants.txt 27fed9a70ddad2088750c4a2b493b63853da2710
-F doc/shared_schema.md 327dbde6dd7d8cc2d7f0efadf4237a7724af6fbc35125d8e6965d1e2253ced81
+F doc/shared_schema.md 1d3dee7a9f5a1b360a49c2310cd9ccf3c645be08bbe41ff5c3382455cf2ff981
 F doc/vfs-shm.txt e101f27ea02a8387ce46a05be2b1a902a021d37a
 F ext/README.md fd5f78013b0a2bc6f0067afb19e6ad040e89a10179b4f6f03eee58fac5f169bd
 F ext/async/README.txt e12275968f6fde133a80e04387d0e839b0c51f91
@@ -1813,7 +1813,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 7d8e8a957235479fba568e1d3ff2cdfe4695184ee1a7ac64bce905a993725164
-R 6413f829102abca209f662f93d696844
+P fa6008d547c6b24108a26e022f3f427fa19ffae006c88fee9de97d2244521de0
+R 1567a476e8cdb3371b0365a07a5c3e11
 U dan
-Z c2c3e0d5a31997ac258189b5e4aa26d6
+Z 4484645d45cf50908886b561d1cf845d
diff --git a/manifest.uuid b/manifest.uuid
index a2a150bb98..ffe72040a1 100644
--- a/manifest.uuid
+++ b/manifest.uuid
@@ -1 +1 @@
-fa6008d547c6b24108a26e022f3f427fa19ffae006c88fee9de97d2244521de0
\ No newline at end of file
+0ce2092a5968d75d014fdc238391c362a9600c28bf18cdc631e98259a5278712
\ No newline at end of file