Skip to content

Commit

Permalink
Remove some outdated information from advanced.html and features.html
Browse files Browse the repository at this point in the history
  • Loading branch information
@katzyn
katzyn committed May 25, 2021
1 parent 3ce222c commit 9ad427e
Show file tree
Hide file tree
Showing 2 changed files with 10 additions and 97 deletions.
44 changes: 2 additions & 42 deletions h2/src/docsrc/html/advanced.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -214,7 +214,7 @@ <h2 id="transaction_isolation">Transaction Isolation</h2>
Transaction isolation is provided for all data manipulation language (DML) statements.
</p>
<p>
The default MVStore engine supports read uncommitted, read committed, repeatable read, snapshot,
H2 supports read uncommitted, read committed, repeatable read, snapshot,
and serializable (partially, see below) isolation levels:
</p>
<ul>
Expand Down Expand Up @@ -249,30 +249,6 @@ <h2 id="transaction_isolation">Transaction Isolation</h2>
<code>SET SESSION CHARACTERISTICS AS TRANSACTION ISOLATION LEVEL SERIALIZABLE</code>
</li>
</ul>
<p>
The PageStore engine supports read uncommitted, read committed, and serializable isolation levels:
</p>
<ul>
<li><b>Read uncommitted</b><br />
This level means that transaction isolation is disabled.
This level is not supported by PageStore engine if multi-threaded mode is enabled.
To enable, execute the SQL statement
<code>SET SESSION CHARACTERISTICS AS TRANSACTION ISOLATION LEVEL READ UNCOMMITTED</code>
</li>
<li><b>Read committed</b><br />
This is the default level.
Read locks are released immediately after executing the statement, but write locks are kept until the transaction commits.
To enable, execute the SQL statement
<code>SET SESSION CHARACTERISTICS AS TRANSACTION ISOLATION LEVEL READ COMMITTED</code>
</li>
<li><b>Serializable</b><br />
Both read locks and write locks are kept until the transaction commits.
To enable, execute the SQL statement
<code>SET SESSION CHARACTERISTICS AS TRANSACTION ISOLATION LEVEL SERIALIZABLE</code>
</li>
</ul>
<p>If repeatable read isolation level is requested when using a PageStore engine it is replaced
with serializable isolation level.</p>
<ul>
<li><b>Dirty reads</b><br />
Means a connection can read uncommitted changes made by another connection.<br />
Expand All @@ -291,7 +267,7 @@ <h2 id="transaction_isolation">Transaction Isolation</h2>

<h3 id="mvcc">Multi-Version Concurrency Control (MVCC)</h3>
<p>
With default MVStore engine delete, insert and update operations only issue a shared lock on the table.
Insert and update operations only issue a shared lock on the table.
An exclusive lock is still used when adding or removing columns or when dropping the table.
Connections only 'see' committed data, and own changes. That means, if connection A updates
a row but doesn't commit this change yet, connection B will see the old value.
Expand All @@ -300,22 +276,6 @@ <h3 id="mvcc">Multi-Version Concurrency Control (MVCC)</h3>
database waits until it can apply the change, but at most until the lock timeout expires.
</p>

<h3>Table Level Locking (PageStore engine)</h3>
<p>
With PageStore engine to make sure all connections only see consistent data, table level locking is used.
This mechanism does not allow high concurrency, but is very fast.
Shared locks and exclusive locks are supported.
Before reading from a table, the database tries to add a shared lock to the table
(this is only possible if there is no exclusive lock on the object by another connection).
If the shared lock is added successfully, the table can be read. It is allowed that
other connections also have a shared lock on the same object. If a connection wants
to write to a table (update or delete a row), an exclusive lock is required. To get the
exclusive lock, other connection must not have any locks on the object. After the
connection commits, all locks are released.
This database keeps all locks in memory.
When a lock is released, and multiple connections are waiting for it, one of them is picked at random.
</p>

<h3>Lock Timeout</h3>
<p>
If a connection cannot get a lock on an object, the connection waits for some amount
Expand Down
63 changes: 8 additions & 55 deletions h2/src/docsrc/html/features.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -652,30 +652,16 @@ <h3>Multithreading Support</h3>
</p>
<p>
An application can use multiple threads that access the same database at the same time.
With default MVStore engine threads that use different connections can use the database concurrently.
With PageStore engine requests to the same database are synchronized,
that means that if one thread executes a long running query, the other threads need to wait.
Threads that use different connections can use the database concurrently.
</p>

<h3>Locking, Lock-Timeout, Deadlocks</h3>
<p>
Please note MVCC is enabled in version 1.4.x by default, when using the MVStore.
In this case, table level locking is not used.

If <a href="advanced.html#mvcc">multi-version concurrency</a> is not used,
the database uses table level locks to give each connection a consistent state of the data.
There are two kinds of locks: read locks (shared locks) and write locks (exclusive locks).
All locks are released when the transaction commits or rolls back.
When using the default transaction isolation level 'read committed', read locks are already released after each statement.
</p><p>
If a connection wants to reads from a table, and there is no write lock on the table,
then a read lock is added to the table. If there is a write lock, then this connection waits
for the other connection to release the lock. If a connection cannot get a lock for a specified time,
then a lock timeout exception is thrown.
</p><p>
Usually, <code>SELECT</code> statements will generate read locks. This includes subqueries.
Statements that modify data use write locks. It is also possible to lock a table exclusively without modifying data,
Statements that modify data use write locks on the modified rows.
It is also possible to issue write locks without modifying data,
using the statement <code>SELECT ... FOR UPDATE</code>.
Data definition statements may issue exclusive locks on tables.
The statements <code>COMMIT</code> and
<code>ROLLBACK</code> releases all open locks.
The commands <code>SAVEPOINT</code> and
Expand All @@ -696,18 +682,18 @@ <h3>Locking, Lock-Timeout, Deadlocks</h3>
SCRIPT;</td>
</tr>
<tr>
<td>Write</td>
<td>Write (row-level)</td>
<td class="notranslate">SELECT * FROM TEST WHERE 1=0 FOR UPDATE;</td>
</tr>
<tr>
<td>Write</td>
<td>Write (row-level)</td>
<td class="notranslate">INSERT INTO TEST VALUES(1, 'Hello');<br />
INSERT INTO TEST SELECT * FROM TEST;<br />
UPDATE TEST SET NAME='Hi';<br />
DELETE FROM TEST;</td>
</tr>
<tr>
<td>Write</td>
<td>Exclusive</td>
<td class="notranslate">ALTER TABLE TEST ...;<br />
CREATE INDEX ... ON TEST ...;<br />
DROP INDEX ...;</td>
Expand All @@ -721,19 +707,9 @@ <h3>Locking, Lock-Timeout, Deadlocks</h3>
<code>SET DEFAULT_LOCK_TIMEOUT &lt;milliseconds&gt;</code>. The default lock timeout is persistent.
</p>

<h3>Avoiding Deadlocks</h3>
<p>
To avoid deadlocks, ensure that all transactions lock the tables in the same order
(for example in alphabetical order), and avoid upgrading read locks to write locks.
Both can be achieved using explicitly locking tables using <code>SELECT ... FOR UPDATE</code>.
</p><p>
Note that delete, insert and update operations issue table level locks with PageStore engine,
but does not issue them with default MVStore engine.
</p>

<h2 id="database_file_layout">Database File Layout</h2>
<p>
The following files are created for persistent databases when the default MVStore engine is used:
The following files are created for persistent databases:
</p>
<table class="main">
<tr><th>File Name</th><th>Description</th><th>Number of Files</th></tr>
Expand Down Expand Up @@ -764,29 +740,6 @@ <h2 id="database_file_layout">Database File Layout</h2>
</td><td>
0 or 1 per database
</td></tr>
</table>

<p>
The following file is created for persistent databases when PageStore engine is used:
</p>
<table class="main">
<tr><th>File Name</th><th>Description</th><th>Number of Files</th></tr>
<tr><td class="notranslate">
test.h2.db
</td><td>
Database file.<br />
Contains the transaction log, indexes, and data for all tables.<br />
Format: <code>&lt;database&gt;.h2.db</code>
</td><td>
1 per database
</td></tr>
</table>

<p>
The following files are created for persistent databases by both MVStore and PageStore engines:
</p>
<table class="main">
<tr><th>File Name</th><th>Description</th><th>Number of Files</th></tr>
<tr><td class="notranslate">
test.lock.db
</td><td>
Expand Down

0 comments on commit 9ad427e

Please sign in to comment.