Changes between Version 36 and Version 37 of TracDev/DatabaseApi

Timestamp:

Jul 19, 2018, 3:29:10 AM (6 years ago)

Author:

Ryan J Ollos

Comment:

Minor changes.

TracDev/DatabaseApi

@@ -16 +16 @@
 === API before Trac 0.12
 
-//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. //
+//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.//
 
 Code 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:
@@ -32 +32 @@
 
 Note 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.
-Avoid in particular doing `cursor = env.get_db_cnx().cursor()`, see r8878.
+Avoid statements like `cursor = env.get_db_cnx().cursor()`, see r8878.
 
 === Trac 0.12 API
 
-//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].//
+//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].//
 
 As support for Python 2.3 has been dropped, we could make use of decorators to get rid of some of the boilerplate code:
@@ -83 +83 @@
 In 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'''.
 
-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.
+This 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.
 
 '''Notes:'''
- - 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.
+ - 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.
  - 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).
- - 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.
+ - 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.
 
 === API after Trac 1.0 #Trac1.0API
 
 [=#Trac0.13API]
-//This style is supported for version 1.0 and later.
+//This style is supported for Trac version 1.0 and later.
 Starting with [milestone:1.3.1], this is actually the only way, as the deprecated APIs were removed.//
 
@@ -195 +195 @@
 def myFunc5():
     """Returns a dict."""
-    # Dict comprehensions available in Python 2.7
+    # Dict comprehensions are available in Python 2.7
     return {a: b for a, b in env.db_query("""
             SELECT a, b
@@ -209 +209 @@
 === Configuration
 
-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:
+Trac 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:
 
 {{{#!ini
@@ -216 +216 @@
 }}}
 
-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`.
+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 supported URI schemes are `sqlite`, `postgres` and `mysql`, though additional schemes can be provided by plugins.
 
 === Pooled Connections