On 12 Jul 2013, at 9:02pm, Richard Hipp <d...@sqlite.org> wrote: > Proposed documentation enhancement here: > http://www.sqlite.org/draft/isolation.html
I hope you don't mind that I posted this publicly. It's a bit strong for a public forum, but I suspect that other readers of this forum might want to chime in and tell me I'm overreacting, or even suggest even better ways of conveying the information concerned. I'm not a fan of the draft version of that page and feel there's scope for improvement before production. It says various things about SQLite but doesn't seem to group them in an order that any particular reader would find useful. Each reader would have to read a lot of text then try to pick through it to figure out what they want to know. And the page as a whole is too long and complicated: I can't tell whether I've gathered the points I need or not. The page seems to talk about two things: A) What is a database connection ? What is the connection between a connection and a database lock. What is the connection between a connection and uncommitted changes ? How do various PRAGMAs (including shared connections) change this ? The major unexpected thing here is how SQLite deals with a case where two different connections (which may be from different apps on different computers) both have uncommitted changes. I think explaining things using this as the key point may make explaining the other aspects unnecessary: they will all come out in the wash. ------------- B) The SQL SELECT operation theoretically happens in an instant, but the SQLite API allows the programmer to execute it bit by bit. What happens if (a) another connection or (b) the same connection makes changes to the database between the start and the end of the operation ? While this page goes into some detail about (B) I think much of this is unnecessary detail and can be replaced by two simple statements: (1) Other connections cannot commit changes until the SELECT is finished. (is this true ?) (2) If changes are made using the same connection as is used for the SELECT, the results are unpredictable, even to the extent that rows may be omitted or returned twice. Once the reader has accepted (2), everything else necessary follows. They already know what they should or shouldn't do. ------------- I'm not even a fan of the summary, which is needed only because the whole page is so long. If one is really needed, then perhaps some of these can be done: Summary item 1 could point to (or perhaps replace) this page <http://www.sqlite.org/transactional.html> [1] with its useful pointer to the WP article on serializability. Item 2 is sometimes false because of the combination of pragmas mentioned in the body of the article. Item 3 needs a statement about when a query starts (is it the _prepare() or the first _step() or sometimes one sometimes another ?). Items 3 and 5 should be rephrased or merged to explain the timeline: _prepare() done here set 1 of changes first _step() done here set 2 of changes more _step()s here set 3 of changes step() returns SQLITE_DONE here Describe for each set whether SELECT will be affected by the changes at all, and whether the changes may cause SELECT to return an inconsistent set of rows. Items 4 and 5 should be merged. Or perhaps item 4 doesn't need to be there at all, since item 5 is so much stronger than it: the results may not only be unpredictable but they may not even make sense. Items 2 and 6 should be rephrased or merged. 6 weakens and modifies (or arguably contradicts) 2. Simon. [1] which is missing a 't' on its last line _______________________________________________ sqlite-users mailing list sqlite-users@sqlite.org http://sqlite.org:8080/cgi-bin/mailman/listinfo/sqlite-users
