--- /dev/null
+
+Shared-Schema Mode Notes
+========================
+
+This branch contains a patch to allow SQLite connections to share schemas
+between database connections within the same process in order to save memory.
+Schemas may be shared between multiple databases attached to the same or
+distinct connection handles.
+
+To activate shared-schemas, a database connection must be opened using the
+sqlite3_open_v2() API with the SQLITE_OPEN_SHARED_SCHEMA
+flag specified. The main database and any attached databases will then share
+an in-memory Schema object with any other database opened within the process
+for which:
+
+ * the contents of the sqlite_master table, including all object names,
+ SQL statements and root pages are identical, and
+ * have the same values for the schema-cookie.
+
+Temp databases (those populated with "CREATE TEMP TABLE" and similar
+statements) never share schemas.
+
+Connections opened with the SQLITE_OPEN_SHARED_SCHEMA flag
+specified may not modify any database schema except that belonging to the
+temp database in anyway. This includes creating or dropping database
+objects, vacuuming the database, or running ANALYZE when the
+sqlite_stat\[14\] tables do not exist.
+
+If the schema of a database attached to an
+SQLITE_OPEN_SHARED_SCHEMA database handle is corrupt, or if
+corruption is encountered while parsing the database schema, then the
+database is treated as empty. This usually means that corruption results in
+a "no such table: xxx" error instead of a more specific error message.
+
+For SQLITE_OPEN_SHARED_SCHEMA connections, the
+SQLITE_DBSTATUS_SCHEMA_USED sqlite3_db_used() distributes
+the memory used for a shared schema object evenly between all database
+connections that share it.
+
+## Implementation Notes
+
+A single Schema object is never used by more than database simultaneously,
+regardless of whether or not those databases are attached to the same or
+different database handles. Instead, a pool of schema objects is maintained
+for each unique sqlite_master-contents/schema-cookie combination
+opened within the process. Each time database schemas are required by a
+connection, for example as part of an sqlite3_prepare\*(),
+sqlite3_blob_open() or sqlite3_blob_open() call, it obtains
+the minimum number of schemas required from the various schema-pools, returning
+them at the end of the call. This means that a single schema-pool only ever
+contains more than one copy of the schema if:
+
+ * Two threads require schemas from the same pool at the same time, or
+ * A single sqlite3_prepare\*() call requires schemas for two or more
+ attached databases that use the same schema-pool.
+
+The size of a schema-pool never shrinks. Each schema pool always maintains
+a number of schema objects equal to the highwater mark of schema objects
+simultaneously required by clients.
+
+This approach is preferred to allowing multiple databases to use the same
+Schema object simultaneously for three reasons:
+
+ * The Schema object is not completely read-only. For example, the
+ Index.zIdxAff string is allocated lazily.
+ * Throughout the statement compiler, SQLite uses variables like
+ Table.pSchema and Index.pSchema with the sqlite3SchemaToIndex() routine
+ in order to determine which attached database a Table or Index object
+ resides in. This mechanism does not work if the same Schema may be
+ used by two or more attached databases.
+ * It may be easier to modify this approach in order to allow
+ SQLITE_OPEN_SHARED_SCHEMA connections to modify database
+ schemas, should that be required.
+
+SQLITE_OPEN_SHARED_SCHEMA connections do not store their
+virtual-table handles in the Table.pVTable list of each table. This would not
+work, as (a) there is no guarantee that a connection will be assigned the same
+Schema object each time it requests one from a schema-pool and (b) a single
+Schema (and therefore Table) object may correspond to tables in two or more
+databases attached to a single connection. Instead, all virtual-table handles
+associated with a single database are stored in a linked-list headed at
+Db.pVTable.
+
+
+
-C Merge\slatest\strunk\sinto\sthis\sbranch.
-D 2019-02-14T15:56:59.827
+C Add\sdocumentation\sfile\sdoc/shared_schema.md\sto\sdescribe\sthe\schange\son\sthis\sbranch.
+D 2019-02-14T17:51:38.838
F .fossil-settings/empty-dirs dbb81e8fc0401ac46a1491ab34a7f2c7c0452f2f06b54ebb845d024ca8283ef1
F .fossil-settings/ignore-glob 35175cdfcf539b2318cb04a9901442804be81cd677d8b889fcc9149c21f239ea
F Makefile.in 56456706c4da271309914c756c9c8ea537685f1c79f8785afa72f968d6810482
F doc/F2FS.txt c1d4a0ae9711cfe0e1d8b019d154f1c29e0d3abfe820787ba1e9ed7691160fcd
F doc/lemon.html 24956ab2995e55fe171e55bdd04f22b553957dc8bb43501dbb9311e30187e0d3
F doc/pager-invariants.txt 27fed9a70ddad2088750c4a2b493b63853da2710
+F doc/shared_schema.md def187628942d7a8cec7b3184e31e18f7efc9893d28decbc6e283e75374e40a4
F doc/vfs-shm.txt e101f27ea02a8387ce46a05be2b1a902a021d37a
F ext/README.md fd5f78013b0a2bc6f0067afb19e6ad040e89a10179b4f6f03eee58fac5f169bd
F ext/async/README.txt e12275968f6fde133a80e04387d0e839b0c51f91
F vsixtest/vsixtest.vcxproj.data 2ed517e100c66dc455b492e1a33350c1b20fbcdc
F vsixtest/vsixtest.vcxproj.filters 37e51ffedcdb064aad6ff33b6148725226cd608e
F vsixtest/vsixtest_TemporaryKey.pfx e5b1b036facdb453873e7084e1cae9102ccc67a0
-P 441cabb62fe14bbef8b19066941426eeb2de128564ec2bfb762228fdae794447 aa61435a4c3800f023788081c1342ad6a05a41449a424fa6c039d5ca46072256
-R 96528ba9e3d3a3edef94be4823ee5551
+P 577d1638362666a8220401d0d0d8bfb3c028ab09e7def1e4bf195db37269c22f
+R 1acea7f4385670d217f2748b0e41615f
U dan
-Z f1856b84c58ea8ee4d0aea1ccbbeace0
+Z 3acdb019d8c7c568a8d8932e68a09746
projects / thirdparty / sqlite.git / commitdiff
