Documentation Source Text

Check-in [1344ab631b]
Login

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

Overview
Comment:Small amount of progress on fileio.html.
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA1: 1344ab631b51c729c2ac0be5bf36abdd536892cc
User & Date: dan 2008-09-25 18:51:57
Context
2008-09-26
21:38
Add documentation on the TRUNCATE journal mode. check-in: 715819ca53 user: drh tags: trunk
2008-09-25
18:51
Small amount of progress on fileio.html. check-in: 1344ab631b user: dan tags: trunk
2008-09-24
18:52
Trying for improvements in the appearance of the syntax in lang*.html. check-in: 4bae4cc5b7 user: drh tags: trunk
Changes
Hide Diffs Unified Diffs Ignore Whitespace Patch

Changes to pages/fileio.in.

1294
1295
1296
1297
1298
1299
1300
1301





1302
1303
1304
1305
1306




1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317


1318
1319
1320
1321
1322
1323
1324
....
1387
1388
1389
1390
1391
1392
1393











1394
1395
1396
1397
1398
1399
1400
....
1471
1472
1473
1474
1475
1476
1477





1478
1479






1480
1481



1482





















1483
1484
1485
1486
1487
1488
1489
1490
....
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
        to persistent storage, then the <i>journal file</i> will be used
        to restore the database to a known good state following system
        recovery.
  </ul>

  <p>
    The <i>page cache</i> is used to buffer modifications to the database
    file image before they are written to the <i>database file</i>.





    Often, all changes for an entire <i>write transaction</i> are accumulated
    within the <i>page cache</i>. In this case no write operations are 
    performed on the database file until the user commits the transaction.

<p class=todo> this section is suspect from this point on.





  <p>
    Even if an application or system failure does not occur while a
    <i>write transaction</i> is in progress, a rollback operation to restore
    the database file to the state that it was in before the transaction
    started may be required. This may occur if the user explicitly requests
    transaction rollback (i.e. by issuing a "ROLLBACK" command), or 
    automatically, as a result of encountering an SQL constraint (see
    <cite>sql_sqlitert_requirements</cite>). For this reason, the original
    page content is stored in the <i>journal file</i> before the page is 
    even modified within the <i>page cache</i>.



  REQ H21025
    Before modifying or adding any in-memory <i>page cache</i> pages in 
    preparation for writing to the <i>database file</i>, the 
    <i>database connection</i> shall open a <i>write transaction</i> on 
    the database file.

................................................................................
      Following this may be a second <i>journal header</i> followed by a
      seconds set of zero or more <i>journal records</i> and so on. There
      is no limit to the number of <i>journal headers</i> a journal file
      may contain. Following the <i>journal headers</i> and their accompanying
      sets of <i>journal records</i> may be the optional <i>master journal
      pointer</i>. Or, the file may simply end.












    <h3 id=journal_header_format>Journal Header Format</h3>

    <p>
      A <i>journal header</i> is <i>sector-size</i> bytes in size, where <i>
      sector-size</i> is the value returned by the xSectorSize method of
      the file handle opened on the database file. Only the first 28 bytes
      of the <i>journal header</i> are used, the remainder may contain garbage
................................................................................
			this <i>journal record</i>, stored as a 4 byte
			big-endian unsigned integer.
      <tr><td>4<td><i>page-size<td>
			This field contains the original data for the page,
			exactly as it appeared in the database file before the
			<i>write transaction</i> began.
      <tr><td style="white-space: nowrap">4 + <i>page-size</i><td>4<td>





    </table>







  <h3>Master Journal Pointer</h3>




  <h2>Write Transactions</h2>





















  <h3>Beginning a Write Transaction</h3>
    <p>
      Before any database pages may be modified within the <i>page cache</i>,
      the <i>database connection</i> must open a <i>write transaction</i>. 
      Opening a <i>write transaction</i> requires that the <i>database
      connection</i> obtains a <i>reserved lock</i> (or greater) on the 
      <i>database file</i>. Because a obtaining a <i>reserved lock</i> on
      a <i>database file</i> guarantees that no other <i>database
................................................................................

    <p class=todo>
      Reqirements describing the details of opening a <i>write transaction</i>.

    <p class=todo>
      Reqirement for error handling?

  <h3 id=journalling_a_page>Journalling a Database Page</h3>

    <p>
      Before modifying a database page within the <i>page cache</i>, the
      page must be <i>journalled</i>. <i>Journalling a page</i> is the
      process of copying that pages original data into the journal file
      so that it can be recovered if the <i>write transaction</i> is rolled
      back.







|
>
>
>
>
>
|
|
|
<
<
>
>
>
>











>
>







 







>
>
>
>
>
>
>
>
>
>
>







 







>
>
>
>
>


>
>
>
>
>
>


>
>
>
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|







 







|







1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309


1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
....
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
....
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
....
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
        to persistent storage, then the <i>journal file</i> will be used
        to restore the database to a known good state following system
        recovery.
  </ul>

  <p>
    The <i>page cache</i> is used to buffer modifications to the database
    file image before they are written to the <i>database file</i>. When
    the contents of a page is required to be modified as the results of
    an operation within a <i>write transaction</i>, the modified copy is
    stored in the <i>page cache</i>. Similarly, if new pages are appended
    to the end of a database file, they are added to the <i>page cache</i>
    instead of being immediately written to the database file within the
    file-system. Often, all changes for an entire <i>write transaction</i> 
    are accumulated within the <i>page cache</i>. In this case no write 
    operations are performed on the database file until the user commits 


    the transaction. Otherwise, changes are buffered within the <i>page
    cache</i> until some internal limit or condition is reached (see section
    <cite>page_cache_algorithms</cite>), and then written to the database
    file.

  <p>
    Even if an application or system failure does not occur while a
    <i>write transaction</i> is in progress, a rollback operation to restore
    the database file to the state that it was in before the transaction
    started may be required. This may occur if the user explicitly requests
    transaction rollback (i.e. by issuing a "ROLLBACK" command), or 
    automatically, as a result of encountering an SQL constraint (see
    <cite>sql_sqlitert_requirements</cite>). For this reason, the original
    page content is stored in the <i>journal file</i> before the page is 
    even modified within the <i>page cache</i>.

  <p class=todo> From here on this section needs changing

  REQ H21025
    Before modifying or adding any in-memory <i>page cache</i> pages in 
    preparation for writing to the <i>database file</i>, the 
    <i>database connection</i> shall open a <i>write transaction</i> on 
    the database file.

................................................................................
      Following this may be a second <i>journal header</i> followed by a
      seconds set of zero or more <i>journal records</i> and so on. There
      is no limit to the number of <i>journal headers</i> a journal file
      may contain. Following the <i>journal headers</i> and their accompanying
      sets of <i>journal records</i> may be the optional <i>master journal
      pointer</i>. Or, the file may simply end.

    <p>
      This section only describes the format of the journal file and the
      various objects that make it up. But because a journal file may be
      read by an SQLite process following recovery from a system failure
      (<i>hot journal rollback</i>, see section
      <cite>hot_journal_rollback</cite>) it is also important to describe
      the way the file is created and populated within the file-system
      using a combination of <i>write file</i>, <i>sync file</i> and
      <i>truncate file</i> operations. These are described in section
      <cite>write_transactions</cite>.

    <h3 id=journal_header_format>Journal Header Format</h3>

    <p>
      A <i>journal header</i> is <i>sector-size</i> bytes in size, where <i>
      sector-size</i> is the value returned by the xSectorSize method of
      the file handle opened on the database file. Only the first 28 bytes
      of the <i>journal header</i> are used, the remainder may contain garbage
................................................................................
			this <i>journal record</i>, stored as a 4 byte
			big-endian unsigned integer.
      <tr><td>4<td><i>page-size<td>
			This field contains the original data for the page,
			exactly as it appeared in the database file before the
			<i>write transaction</i> began.
      <tr><td style="white-space: nowrap">4 + <i>page-size</i><td>4<td>
			This field contains a checksum value, calculated based
			on the contents of the journaled database page data
			(the previous field) and the values stored in the
			<i>checksum initializer</i> field of the preceding
			<i>journal header</i>.
    </table>

    <p>
      The set of <i>journal records</i> that follow a <i>journal header</i>
      in a <i>journal file</i> are packed tightly together. There are no
      alignment requirements for <i>journal records</i> as there are for
      <i>journal headers</i>.

  <h3>Master Journal Pointer</h3>

    <p class=todo>
      Come back and do this....

  <h2 id=write_transactions>Write Transactions</h2>

    <p>
      This section describes the progression of an SQLite <i>write
      transaction</i>. From the point of view of the systems described in
      this document, most <i>write transactions</i> consist of three steps:

    <ol>
      <li>The <i>write transaction</i> is opened. This process is described
          in section <cite>opening_a_write_transaction</cite>.
      <li>The end-user executes DML or DDL SQL statements that require the
          structure of the database file of the database file to be modified.
	  These modifications may be any combination of operations to modify 
	  the content of existing database pages, append new database pages
	  to the end of the file, or truncate (discard) database pages from
	  the end of the database file. This is described in detail in 
	  section <cite>journalling_a_page</cite>.
      <li>The <i>write transaction</i> is concluded and the changes made
          permanently committed to the database.
    </ol>


  <h3 id=opening_a_write_transaction>Beginning a Write Transaction</h3>
    <p>
      Before any database pages may be modified within the <i>page cache</i>,
      the <i>database connection</i> must open a <i>write transaction</i>. 
      Opening a <i>write transaction</i> requires that the <i>database
      connection</i> obtains a <i>reserved lock</i> (or greater) on the 
      <i>database file</i>. Because a obtaining a <i>reserved lock</i> on
      a <i>database file</i> guarantees that no other <i>database
................................................................................

    <p class=todo>
      Reqirements describing the details of opening a <i>write transaction</i>.

    <p class=todo>
      Reqirement for error handling?

  <h3 id=journalling_a_page>Modifying, Adding or Truncating a Database Page</h3>

    <p>
      Before modifying a database page within the <i>page cache</i>, the
      page must be <i>journalled</i>. <i>Journalling a page</i> is the
      process of copying that pages original data into the journal file
      so that it can be recovered if the <i>write transaction</i> is rolled
      back.