Changeset 33911 in project


Ignore:
Timestamp:
03/27/17 23:45:30 (8 months ago)
Author:
zbigniew
Message:

wiki/sql-de-lite: release 0.7.1

File:
1 edited

Legend:

Unmodified
Added
Removed
  • wiki/eggref/4/sql-de-lite

    r32354 r33911  
    3131==== Built-in library
    3232
    33 SQLite 3.7.11 is included in the egg and will be linked in statically
    34 if the system library is missing or older than 3.7.11.  The built-in
     33SQLite 3.17.0 is included in the egg and will be linked in statically
     34if the system library is missing or older than 3.17.0.  The built-in
    3535library is compiled with FTS3 and FTS4 (full text search) enabled.
    3636
     
    3939
    4040To force the use of the built-in library, pass the {{sql-de-lite-internal-lib}}
    41 feature to {{chicken-install}}.  This requires Chicken 4.5.1 or later.
     41feature to {{chicken-install}}.
    4242
    4343 chicken-install -D sql-de-lite-internal-lib sql-de-lite
     
    4949
    5050To force the use of an external library, pass the {{sql-de-lite-external-lib}}
    51 feature to {{chicken-install}}.  This requires Chicken 4.5.1 or later.
     51feature to {{chicken-install}}.
    5252
    5353 chicken-install -D sql-de-lite-external-lib sql-de-lite
     
    107107<procedure>(close-database db)</procedure>
    108108
    109 Closes the database connection {{db}}.
    110 
    111 The prepared statement cache is flushed prior to closing, finalizing
    112 all cached statements.  Transient statements must be finalized
    113 manually, or the close will fail.  (The high-level query/exec
    114 interface does this for you.)
     109Closes the database connection {{db}}. All prepared statements are finalized
     110before closing the database.
    115111
    116112'''Note.'''  Prior to 0.5.0, we did finalize transient statements as
     
    120116and crash.
    121117
     118'''Note.''' Prior to 0.7.0, transient (non-cached) statements had to be
     119finalized manually before closing the database, typically with the query and
     120exec high-level interface. Now all statements are finalized regardless of
     121caching status.
     122
    122123<procedure>(database-closed? db)</procedure>
    123124
     
    129130
    130131Looks up a prepared statement in the statement cache.  If not found,
    131 it prepares a new statement and caches it, returning the statement.  If
    132 found, the statement is reset if need be, and returned.  An exception
    133 is thrown if a statement we pulled from cache is currently running --- in
    134 other words, has been stepped at least once and has not yet returned
    135 {{SQLITE_DONE}}. (NB: warn and reset would also be acceptable
    136 behavior.)
     132it prepares a new statement.  Returns a statement object.
    137133
    138134Preparing a SQL statement consisting entirely of whitespace or comment
     
    141137Returns a {{#<sqlite-statement>}} object.
    142138
     139'''Note.''' Prior to 0.7.0, an exception was thrown if a statement
     140we pulled from cache is currently running. Statements are no longer
     141cached while running.
     142
    143143<procedure>(prepare-transient db sql)</procedure>
    144144
     
    146146procedure is subject to removal.
    147147
    148 You ''must'' be sure to finalize all transient statements prior to
    149 closing the database.  For a safer option, use {{sql/transient}}
    150 with {{query}} or {{exec}}.
    151 
    152148<parameter>(prepared-cache-size n) [default: 100]</parameter>
    153149
     
    160156the statement cache is unique per connection.
    161157
    162 Set capacity to 0 to disable the cache; this is not recommended.
    163 All statements will become effectively transient, and must be
    164 finalized manually.  Using {{sql}} with {{query}} and {{exec}}
    165 will take care of this for you.
     158Set capacity to 0 to disable the cache.
    166159
    167160==== Stepping the statement
     
    192185<procedure>(finalize statement)</procedure>
    193186
    194 Finalize {{statement}}.  Finalizing a finalized statement or a cached
    195 statement is a no-op.  Finalizing a statement on a closed database is
    196 also a no-op.  Cached statements are finalized as they expire, and all
    197 other statements known to the SQLite library are automatically
    198 finalized when the database is closed, so it is rarely necessary to
    199 call this directly.
    200 
    201 Transient statements (statements deliberately prepared to bypass the
    202 cache, including those that are prepared when cache size is zero) must
    203 be finalized either by using this procedure or the {{query}} /
    204 {{exec}} interface.
     187Finalize {{statement}}.  Usually, the statement is reset and added to the
     188statement cache.  If the statement is transient, or cannot be cached for some
     189reason, it is finalized immediately.
     190
     191Finalizing a finalized statement, or a statement on a closed database, is a
     192no-op.
    205193
    206194<procedure>(resurrect statement)</procedure>
    207195
    208 Resurrects a previously finalized statement {{s}} or, if still alive, just
    209 resets it.  Returns {{s}}, which is also modified in place.
    210 
    211 Resurrection is accomplished either by pulling a previously prepared
    212 SQLite statement from the cache, or if it is not cached, by
    213 re-preparing the original SQL associated with the statement.
    214 Afterwards, the statement may be used normally.
     196Resurrects a previously finalized statement {{s}} by pulling it from the cache,
     197or if it was not cached, by re-preparing the original SQL associated with the
     198statement. 
     199
     200Returns {{s}}, which is also modified in place.
    215201
    216202==== Binding parameters
     
    382368compiling them until and unless they are actually used.
    383369
    384 Additionally, {{sql}} is safer.  For example, when the statement cache
    385 is disabled, an error that occurs between {{prepare}} and {{query}}
    386 may leak an unfinalized statement.  An error occurring between {{sql}}
    387 and {{query}} is no problem, because preparation is deferred until
    388 safely inside {{query}}.  The same goes for {{sql/transient}},
    389 which bypasses the cache completely.
    390 
    391370<procedure>(sql/transient db sql-str)</procedure>
    392371
    393 Equivalent to {{(sql db sql-str)}}, but the statement will not be
     372Equivalent to {{(sql db sql-str)}}, but the statement will never be
    394373cached; it is prepared anew every time it is resurrected.
    395374
    396 {{sql/transient}} is recommended over {{prepare-transient}} for
    397 the same reasons mentioned in {{sql}}.
    398 
    399375==== Query
    400376
     
    402378
    403379Resurrects statement {{s}}, binds {{args}} to {{s}} using
    404 {{bind-parameters}}, and performs a {{query*}}.  If the statement is
    405 transient, it is finalized immediately afterward, even if an exception
    406 occurs.
     380{{bind-parameters}}, performs a {{query*}} and {{finalize}}s the
     381statement.
    407382
    408383{{query}} is the usual way to perform a query unless you need to bind
     
    591566
    592567Resurrects statement {{s}}, binds {{args}} to {{s}} using
    593 {{bind-parameters}}, and performs an {{exec*}}.  If {{s}} is
    594 transient, it is finalized immediately afterward, even if an exception
    595 occurs.
     568{{bind-parameters}}, performs an {{exec*}}, and {{finalize}}s the
     569statement.
    596570
    597571<procedure>(exec* s)</procedure>
     
    636610named convenience functions instead of the optional parameter.
    637611
    638 The transaction is committed with {{(commit db)}} if {{thunk}} returns
    639 a true value.  Escaping or re-entering the dynamic extent of {{thunk}}
    640 will not commit or rollback the in-progress transaction.  However, if
    641 an exception occurs during {{thunk}}, or {{thunk}} returns {{#f}}, or
    642 the commit fails, the transaction will be rolled back with {{(rollback db)}}.  If this rollback fails, that is a critical error and you should likely abort.
     612The transaction is committed with {{(commit db)}} if {{thunk}} returns a true
     613value.  Escaping or re-entering the dynamic extent of {{thunk}} will not commit
     614or rollback the in-progress transaction.  However, if an exception occurs
     615during {{thunk}}, or {{thunk}} returns {{#f}}, or the commit fails, the
     616transaction will be rolled back with {{(rollback db)}}.  If this rollback
     617fails, that is a critical error and you should likely abort.
    643618
    644619==== rollback
     
    865840<procedure>(flush-cache! db)</procedure>
    866841
    867 Flush the prepared statement cache,
     842Flush the prepared statement cache. All cached statements will be finalized (in the
     843underlying library sense).
    868844
    869845<procedure>(finalized? statement)</procedure>
     
    896872==== Version history
    897873
     874; 0.7.1 : Upgrade to SQLite 3.17.0
     875; 0.7.0 : Defer caching statements until they are finalized, so the cache never contains running statements. Fixes a cache-expiration bug found by ''andyjpb''; also transient statements no longer need to be finalized manually, and duplicate SQL may be prepared. Remove deprecated milliseconds->time identifier (wasamasa).
    898876; 0.6.6 : Move to [[https://bitbucket.org/ursetto/sql-de-lite/|bitbucket]]; dummy update for henrietta-cache
    899877; 0.6.5 : Upgrade to SQLite 3.8.9
Note: See TracChangeset for help on using the changeset viewer.