From 6217a01583e81277b451b23146645c12a940d357 Mon Sep 17 00:00:00 2001 From: hvlad Date: Mon, 11 May 2020 23:18:57 +0300 Subject: [PATCH] Update documentation. --- doc/README.read_consistency.md | 51 +++++++++++++++++++++++----------- 1 file changed, 35 insertions(+), 16 deletions(-) diff --git a/doc/README.read_consistency.md b/doc/README.read_consistency.md index fca9b49253..0cc2fda7cd 100644 --- a/doc/README.read_consistency.md +++ b/doc/README.read_consistency.md @@ -70,6 +70,9 @@ scope of higher block, and old block is released when OIT moves out of lower blo Block size could be set in firebird.conf using new setting **TipCacheBlockSize**. Default value is 4MB and it could keep 512K transactions. +**CONCURRENCY** transactions now uses **database snapshot** described above. Thus instead of taking +a private copy of TIP at own start it just keeps value of global Commit Number at a moment. + # Statement level read consistency for read-committed transactions ## Not consistent read problem @@ -109,14 +112,16 @@ view of database, of course. The obvious solution to not consistent read problem is to make read-committed transaction to use stable database snapshot while statement is executed. Each new top-level statement create own database snapshot to see data committed recently. With snapshots based on commit order it is very -cheap operation. Nested statements (triggers, nested stored procedures and functions, dynamic -statements, etc) uses same database snapshot created by top-level statement. +cheap operation. Let name this snapshot as **statement-level snapshot** further. Nested statements +(triggers, nested stored procedures and functions, dynamic statements, etc) uses same +statement-level snapshot created by top-level statement. To support this solution new transaction isolation level is introduced: **READ COMMITTED READ CONSISTENCY** Old read-committed isolation modes (**RECORD VERSION** and **NO RECORD VERSION**) are still -allowed but considered as legacy and not recommended to use. +allowed, works as before (i.e. not using statement-level snapshots) and could be considered +as legacy in the future versions of Firebird. So, there are three kinds of read-committed transactions now: - READ COMMITTED READ CONSISTENCY @@ -165,18 +170,28 @@ Notes: the application if not handled - UPDATE\DELETE triggers will fire multiply times for the same record if statement execution was restarted and record is updated\deleted again +- statement restart usually fully transparent to the applications and no special actions should + be taken by developers to handle it in any way. The only exception is the code with side effects + that is out of transactional control, such as: + - usage of external tables, sequences or context variables; + - sending e-mails using UDF; + - committed autonomous transactions or external queries, and so on + + Take into account that such code could be executed more than once if update conflict happens +- there is no special tools to detect restart but it could be easy done using code with side + effects as described above, for example - using context variable - by historical reasons isc_update_conflict reported as secondary error code with primary error code isc_deadlock. -### Precommitted transactions +### Read-committed read only transactions -READ COMMITTED READ ONLY transactions marked as committed immediately when transaction started. -This is correct if read-committed transaction needs no database snapshot. But it is not correct -to mark READ CONSISTENCY READ ONLY transaction as committed as it can break statement-level -snapshot consistency. Therefore READ CONSISTENCY READ ONLY transactions is not precommitted -on start. Other kinds of READ COMMITTED READ ONLY transactions ([NO] RECORD VERSION) works as -before and marked as committed when such transaction started. +READ COMMITTED *READ ONLY* transactions marked as committed immediately when transaction started. +Also such transactions do not inhibit regular garbage collection and not delays advance of OST +marker. READ CONSISTENCY READ ONLY transactions still marked as committed on start but, to not +let regular garbage collection to break future statement-level snapshots, it delays movement of +OST marker in the same way as SNAPSHOT transactions. Note, this delays *regular* (traditional) +garbage collection only, *intermediate* GC (see below) is not affected. ### Support for new READ COMMITTED READ CONSISTENCY isolation level #### SQL syntax @@ -192,19 +207,20 @@ Parameter Buffer (TPB): *isc_tpb_read_consistency* #### Configuration setting -In the future versions of Firebird old kinds of read-committed transactions could be removed. -To help test existing applications with new READ COMMITTED READ CONSISTENCY isolation level -new configuration setting is introduced: +It is recommended to use READ COMMITTED READ CONSISTENCY mode whenever read-committed isolation +is feasible. To help test existing applications with new READ COMMITTED READ CONSISTENCY isolation +level new configuration setting is introduced: *ReadConsistency* If ReadConsistency set to 1 (by default) engine ignores [NO] RECORD VERSION flags and makes all read-committed transactions READ COMMITTED READ CONSISTENCY. -Set ReadConsistency to 0 to allow old engine behavior - flags [NO] RECORD VERSION takes effect as -in previous Firebird versions. READ COMMITTED READ CONSISTENCY isolation level should be specified -explicitly. +If ReadConsistency is set to 0 - flags [NO] RECORD VERSION takes effect as in previous Firebird +versions. READ COMMITTED READ CONSISTENCY isolation level should be specified explicitly by +application - in TPB or using SQL syntax. +The setting is per-database. # Garbage collection of intermediate record versions @@ -241,3 +257,6 @@ Garbage collection of intermediate record versions run by: - background garbage collector in SuperServer - every user attachment after update or delete record - table scan at index creation + +Traditional way of garbage collection (regular GC) is not changed and still works the same way +as in previous Firebird versions.