Documentation Source Text

Check-in [8bb233e0af]
Login

Many hyperlinks are disabled.
Use anonymous login to enable hyperlinks.

Overview
Comment:Update documentation to describe how pragma journal_mode will work as long as there is no pending transaction.
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA1:8bb233e0afd7ed2ea2b743428f65cb0381bf103f
User & Date: drh 2009-04-20 17:43:48
Context
2009-04-21
16:14
Added a new FAQ to explain how the syntax diagrams are created. check-in: 74c109fae7 user: drh tags: trunk
2009-04-20
17:43
Update documentation to describe how pragma journal_mode will work as long as there is no pending transaction. check-in: 8bb233e0af user: drh tags: trunk
13:29
Update the documentation to explain that the journal_mode must be set prior to the first transaction. CVSTrac ticket #3811. check-in: 3a4c37b08b user: drh tags: trunk
Changes
Hide Diffs Unified Diffs Ignore Whitespace Patch

Changes to pages/lang.in.

336
337
338
339
340
341
342





343
344
345
346
347
348
349
are any pending queries.  Both read-only and read/write queries will
cause a ROLLBACK to fail.  A ROLLBACK must fail if there are pending
read operations (unlike COMMIT which can succeed) because bad things
will happen if memory image of the database is changed out from under
an active query.
</p>






<h3>Response To Errors Within A Transaction</h3>

<p>If certain kinds of errors occur within a transaction, the
transaction may or may not be rolled back automatically.  The
errors that cause the behavior include:</p>

<ul>







>
>
>
>
>







336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
are any pending queries.  Both read-only and read/write queries will
cause a ROLLBACK to fail.  A ROLLBACK must fail if there are pending
read operations (unlike COMMIT which can succeed) because bad things
will happen if memory image of the database is changed out from under
an active query.
</p>

<p>
If [PRAGMA journal_mode] is set to OFF (thus disabling the rollback journal
file) then the behavior of the ROLLBACK command is undefined.
</p>

<h3>Response To Errors Within A Transaction</h3>

<p>If certain kinds of errors occur within a transaction, the
transaction may or may not be rolled back automatically.  The
errors that cause the behavior include:</p>

<ul>

Changes to pages/pragma.in.

331
332
333
334
335
336
337
338

339
340
341
342
343
344
345
...
363
364
365
366
367
368
369


370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390

391
392
393
394
395
396
397
    changes the journaling mode for a specific database connection.
    Use "main" for the main database (the database that was opened by
    the original [sqlite3_open()], [sqlite3_open16()], or
    [sqlite3_open_v2()] interface call) and use "temp" for database
    that holds TEMP tables.  The 3rd form changes the journaling mode
    on all databases and it changes the default journaling mode that
    will be used for new databases added by subsequent [ATTACH]
    commands.</p>


    <p>The DELETE journaling mode is the normal behavior.  In the DELETE
    mode, the rollback journal is deleted at the conclusion of each
    transaction.  Indeed, the delete operation is the action that causes
    the transaction to commit.
    (See the documented titled <a href="atomiccommit.html">
    Atomic Commit In SQLite</a> for additional detail.)</p>
................................................................................
    the middle of a transaction when the MEMORY journaling mode is set,
    then the database file will very likely go corrupt.</p>

    <p>The OFF journaling mode disables the rollback journal completely.
    No rollback journal is ever created and hence there is never a rollback
    journal to delete.  The OFF journaling mode disables the atomic
    commit and rollback capabilities of SQLite. The [ROLLBACK] command


    no longer works. If the application crashes
    in the middle of a transaction when the OFF journaling mode is
    set, then the database file will very likely go corrupt.</p>

    <p>In order for a change in journal_mode to be effective, that change must 
    occur prior to executing any transaction on the database file.  
    Attempt to change the journal mode after the first transaction has been 
    executed might report success and might 
    report the new journal mode is set, when
    in reality the original journal mode could still be in force.  It is
    undefined whether or not a journal_mode change is effective after one
    or more transactions have been run.  The only reliable way to modify
    the journal mode is to change it prior to the first transaction.
    If an application must change the journal_mode after one or more
    transactions have occurred, the only reliable way to do so is to
    close and reopen the database connection.</p>

    <p>Note that the journal_mode for an [in-memory database]
    is either MEMORY or OFF and can not be changed to a different value.
    An attempt to change the journal_mode of an [in-memory database] to
    any setting other than MEMORY or OFF is silently ignored.</p>

</li>

<tcl>Subsection journal_size_limit</tcl>
<li><p><b>
    PRAGMA journal_size_limit<br>
    PRAGMA journal_size_limit = </b><i>N</i> <b>;</b>








|
>







 







>
>
|



<
<
<
<
<
<
<
<
<
<
<
<
<



|
>







331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
...
364
365
366
367
368
369
370
371
372
373
374
375
376













377
378
379
380
381
382
383
384
385
386
387
388
    changes the journaling mode for a specific database connection.
    Use "main" for the main database (the database that was opened by
    the original [sqlite3_open()], [sqlite3_open16()], or
    [sqlite3_open_v2()] interface call) and use "temp" for database
    that holds TEMP tables.  The 3rd form changes the journaling mode
    on all databases and it changes the default journaling mode that
    will be used for new databases added by subsequent [ATTACH]
    commands.  The new journal mode is returned.  If the journal mode
    could not be changed, the original journal mode is returned.</p>

    <p>The DELETE journaling mode is the normal behavior.  In the DELETE
    mode, the rollback journal is deleted at the conclusion of each
    transaction.  Indeed, the delete operation is the action that causes
    the transaction to commit.
    (See the documented titled <a href="atomiccommit.html">
    Atomic Commit In SQLite</a> for additional detail.)</p>
................................................................................
    the middle of a transaction when the MEMORY journaling mode is set,
    then the database file will very likely go corrupt.</p>

    <p>The OFF journaling mode disables the rollback journal completely.
    No rollback journal is ever created and hence there is never a rollback
    journal to delete.  The OFF journaling mode disables the atomic
    commit and rollback capabilities of SQLite. The [ROLLBACK] command
    no longer works; it behaves in an undefined way.  Applications must
    avoid using the [ROLLBACK] command when the journal mode is OFF.
    If the application crashes
    in the middle of a transaction when the OFF journaling mode is
    set, then the database file will very likely go corrupt.</p>














    <p>Note that the journal_mode for an [in-memory database]
    is either MEMORY or OFF and can not be changed to a different value.
    An attempt to change the journal_mode of an [in-memory database] to
    any setting other than MEMORY or OFF is ignored.  Note also that
    the journal_mode cannot be changed while a transaction is active.</p>
</li>

<tcl>Subsection journal_size_limit</tcl>
<li><p><b>
    PRAGMA journal_size_limit<br>
    PRAGMA journal_size_limit = </b><i>N</i> <b>;</b>