Edgewall Software

Changes between Version 36 and Version 37 of TracDev/DatabaseApi


Ignore:
Timestamp:
Jul 19, 2018, 3:29:10 AM (14 months ago)
Author:
Ryan J Ollos
Comment:

Minor changes.

Legend:

Unmodified
Added
Removed
Modified
  • TracDev/DatabaseApi

    v36 v37  
    1616=== API before Trac 0.12
    1717
    18 //This is how things used to be for Trac 0.5 - 0.11, and is still supported in Trac 0.12, but in new code this style should definitely **not** be used, as it introduces all the problems that the new styles are solving and was removed in [milestone:1.1.2]. See next sections for details. //
     18//This is how things used to be for Trac 0.5 - 0.11, and is still supported until [milestone:1.1.2]. Its use is discouraged for new code.//
    1919
    2020Code accessing the database in Trac go through this layer simply by using the {{{Environment}}} method {{{get_db_cnx()}}} to get a pooled database connection. A database cursor can be obtained from the pooled database connection, and the code uses the cursor in conjunction with SQL statements to implement the behavior:
     
    3232
    3333Note that you should always make sure that `db` won't get garbage collected while `cursor` is still used, as the collection will do a rollback and close the cursors.
    34 Avoid in particular doing `cursor = env.get_db_cnx().cursor()`, see r8878.
     34Avoid statements like `cursor = env.get_db_cnx().cursor()`, see r8878.
    3535
    3636=== Trac 0.12 API
    3737
    38 //The 0.12 style can still be used in 1.0, but for new code we encourage you to focus on the Trac version 1.0 and to adopt the even simpler 1.0 style. See next sections for details. The 0.12 style was removed in [milestone:1.3.1].//
     38//The 0.12 style can still be used in 1.0, but for new code we encourage you to focus on Trac version 1.0 and adopt the even simpler 1.0 style. See next sections for details. The 0.12 style was removed in [milestone:1.3.1].//
    3939
    4040As support for Python 2.3 has been dropped, we could make use of decorators to get rid of some of the boilerplate code:
     
    8383In this example, when `myFunc1()` is called, it first executes the outer transaction (`do_outer_transaction()`) and then executes a nested transaction (`myFunc2()`) from within the outer transaction. The key observation is that '''nested transactions are atomic'''.
    8484
    85 This means that either the ''whole'' (outer) transaction is either committed or aborted. So even if the nested transaction succeeded but the outer transaction fails (an exception is raised at the line with the "commit or rollback" comment), the ''whole'' transaction will be rolled back, i.e. including the changes made by the nested transaction.
     85This means that the ''whole'' (outer) transaction is either committed or aborted. So even if the nested transaction succeeded but the outer transaction fails (an exception is raised at the line with the "commit or rollback" comment), the ''whole'' transaction will be rolled back, i.e. including the changes made by the nested transaction.
    8686
    8787'''Notes:'''
    88  - Do **not** call `commit()` yourself in a transaction, even though this is still possible in the API for backward compatibility reasons. Not only is a commit performed automatically at the proper time (as explained above), but if you call it yourself, you risk to commit from within a nested transaction, possibly leading to an inconsistent state of the database.
     88 - Do **not** call `commit()` yourself in a transaction, even though this is still possible in the API for backward compatibility reasons. Not only is a commit performed automatically at the proper time (as explained above), but if you call it yourself you risk to commit from within a nested transaction, possibly leading to an inconsistent state of the database.
    8989 - Using `env.get_read_db()` within a transaction reuses the same connection. So uncommitted changes made by the transaction will already be visible to the caller of `get_read_db()` (but not outside of the transaction - that is in another thread).
    90  - Uncommited changes of a transaction are only visible to nested transactions in the same thread. Different threads use different database connections and therefore different transactions. To be more precise, the exact detail of what is visible to other threads is database specific and depends to the //isolation level// used.
     90 - Uncommited changes of a transaction are only visible to nested transactions in the same thread. Different threads use different database connections and therefore different transactions. To be more precise, the exact detail of what is visible to other threads is database specific and depends on the //isolation level// used.
    9191
    9292=== API after Trac 1.0 #Trac1.0API
    9393
    9494[=#Trac0.13API]
    95 //This style is supported for version 1.0 and later.
     95//This style is supported for Trac version 1.0 and later.
    9696Starting with [milestone:1.3.1], this is actually the only way, as the deprecated APIs were removed.//
    9797
     
    195195def myFunc5():
    196196    """Returns a dict."""
    197     # Dict comprehensions available in Python 2.7
     197    # Dict comprehensions are available in Python 2.7
    198198    return {a: b for a, b in env.db_query("""
    199199            SELECT a, b
     
    209209=== Configuration
    210210
    211 To determine which database has to be used, Trac looks at the value of the `database` configuration option in [TracIni#trac-database-option trac.ini], which should contain a database connection URI. The default value for this option tells Trac to use an SQLite database inside the environment directory:
     211Trac connects to a database using the database connection URI contained in the [[TracIni#trac-database-option|"[trac] database"]] option of trac.ini. The default value for this option tells Trac to use an SQLite database inside the environment directory:
    212212
    213213{{{#!ini
     
    216216}}}
    217217
    218 The connection URI syntax has been designed to be compatible with that provided by [http://sqlobject.org/SQLObject.html#declaring-the-class SQLObject]. See also the section on SQLObject [http://sqlobject.org/SQLObject.html#declaring-a-connection connections]. The only supported URI schemes at this point are `sqlite`, `postgres` and `mysql`.
     218The connection URI syntax has been designed to be compatible with that provided by [http://sqlobject.org/SQLObject.html#declaring-the-class SQLObject]. See also the section on SQLObject [http://sqlobject.org/SQLObject.html#declaring-a-connection connections]. The supported URI schemes are `sqlite`, `postgres` and `mysql`, though additional schemes can be provided by plugins.
    219219
    220220=== Pooled Connections