From: dan Date: Thu, 14 Feb 2019 17:51:38 +0000 (+0000) Subject: Add documentation file doc/shared_schema.md to describe the change on this branch. X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=a5150d4f0505c48d1d5b065634b3e3a2ffa81044;p=thirdparty%2Fsqlite.git Add documentation file doc/shared_schema.md to describe the change on this branch. FossilOrigin-Name: a5f8067dde1e8974f779ab838a02416a7dd9d20d253af860d08d635cfede6fee --- diff --git a/doc/shared_schema.md b/doc/shared_schema.md new file mode 100644 index 0000000000..16baf91081 --- /dev/null +++ b/doc/shared_schema.md @@ -0,0 +1,85 @@ + +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. + + + diff --git a/manifest b/manifest index af80ddb0f4..572217a478 100644 --- a/manifest +++ b/manifest @@ -1,5 +1,5 @@ -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 @@ -39,6 +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 def187628942d7a8cec7b3184e31e18f7efc9893d28decbc6e283e75374e40a4 F doc/vfs-shm.txt e101f27ea02a8387ce46a05be2b1a902a021d37a F ext/README.md fd5f78013b0a2bc6f0067afb19e6ad040e89a10179b4f6f03eee58fac5f169bd F ext/async/README.txt e12275968f6fde133a80e04387d0e839b0c51f91 @@ -1808,7 +1809,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 441cabb62fe14bbef8b19066941426eeb2de128564ec2bfb762228fdae794447 aa61435a4c3800f023788081c1342ad6a05a41449a424fa6c039d5ca46072256 -R 96528ba9e3d3a3edef94be4823ee5551 +P 577d1638362666a8220401d0d0d8bfb3c028ab09e7def1e4bf195db37269c22f +R 1acea7f4385670d217f2748b0e41615f U dan -Z f1856b84c58ea8ee4d0aea1ccbbeace0 +Z 3acdb019d8c7c568a8d8932e68a09746 diff --git a/manifest.uuid b/manifest.uuid index 8cbd5b460f..669a682a19 100644 --- a/manifest.uuid +++ b/manifest.uuid @@ -1 +1 @@ -577d1638362666a8220401d0d0d8bfb3c028ab09e7def1e4bf195db37269c22f \ No newline at end of file +a5f8067dde1e8974f779ab838a02416a7dd9d20d253af860d08d635cfede6fee \ No newline at end of file