Webware for Python

Update of /cvsroot/webware/Webware/MiddleKit/Docs
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv18927/Docs

Modified Files:
	RelNotes-X.Y.html UsersGuide.html 
Log Message:
- split obj ref SQL columns in two (class id and obj id)
- merge SQLGenerater.config into Settings.config
- see release notes for details


Index: RelNotes-X.Y.html
===================================================================
RCS file: /cvsroot/webware/Webware/MiddleKit/Docs/RelNotes-X.Y.html,v
retrieving revision 1.3
retrieving revision 1.4
diff -C2 -d -r1.3 -r1.4
*** RelNotes-X.Y.html	4 Dec 2003 06:58:57 -0000	1.3
--- RelNotes-X.Y.html	24 Feb 2004 02:04:13 -0000	1.4
***************
*** 18,22 ****
  		not be interpreted as comments in Mozilla 1.2.1
  	-->
! 	<title>CGIWrapper Release Notes</title>
  </head>
  
--- 18,22 ----
  		not be interpreted as comments in Mozilla 1.2.1
  	-->
! 	<title>MiddleKit Release Notes</title>
  </head>
  
***************
*** 29,41 ****
  
  
! <a name=Introduction<h2>Introduction</h2></a>
  <ul>
! 	<li> *
  </ul>
  
! <h2>Major Changes</h2>
! <ul>
! 	<li> *
! </ul>
  
  
--- 29,56 ----
  
  
! <a name=Incompatible><h2>Incompatible Changes</h2></a>
  <ul>
! 	<li> <font color=red>There are some MiddleKit improvements that break compatibility with previous versions of MiddleKit, although all are easy to address. Read below.</font>
  </ul>
  
! <h3>Obj Ref Columns</h3>
! 
! <p> A long standing flaw in MiddleKit was the use of 64-bit integer SQL columns to store references/pointers to objects. The first 32-bits were for the class id and the second 32-bits were for the object id. These are difficult to work with from SQL. For example, an object reference to (classId=1, objId=1) showed as 4294967297 in SQL and couldn't not be readily joined with other tables.
! 
! <p> The new approach is to break these values into two SQL columns. If the attribute name is "foo" then the SQL columns will be named "fooClassId" and "fooObjId". If, for some reason, you don't like those suffixes, you can customize them through the setting <a href=UsersGuide.html#Configuration_ObjRefSuffixes >ObjRefSuffixes</a>. As always, the class ids are stored in the _MKClassIds table that MiddleKit automatically generates.
! 
! <p> <font color=red>If you are upgrading Webware then your database schema will no longer be compatible with MiddleKit.</font> The easy way to fix this is to set UseBigIntObjRefColumns to True in Settings.config (see <a href=UsersGuide.html#Configuration_UseBigIntObjRefColumns>User's Guide - Configuration</a> for more information). This will give you the old behavior. The hard way is to fix up your schema and migrate the data from the old columns to the new.
! 
! 
! <h3>SQLGenerator.config</h3>
! 
! <p> There used to be another config file, besides Settings.config, named SQLGenerator.config, with a single setting, DropStatements. That file is no longer used and the setting has been moved to Settings.config. If you have a SQLGenerator.config in your model directories, move the setting over.
! 
! 
! <h3>MS SQL Support</h3>
! 
! <p> The <span class=name>float</span> type now yields a SQL type of <span class=name>float</span> rather than <span class=name>decimal</span>, because that matches the semantics of Python's float type more closely (perhaps identically). If you want decimal, use decimal; it is a valid MiddleKit datatype.
! 
! <p> The serial primary key field is now typed as int instead of bigint. This matches the MiddleKit approach for other databases and also allows object id columns to be foreign keys to this primary key (MS SQL will give an error if an int column tries to reference a bigint column).
  
  
***************
*** 48,53 ****
  <h2>Improvements and Refinements</h2>
  <ul>
! 	<li>Improved error message when there are errors in the model (instead of 
! 		cryptic tracebacks).  In many cases the filename of the model and the 
  	line number are printed, along with the error message.
  </ul>
--- 63,68 ----
  <h2>Improvements and Refinements</h2>
  <ul>
! 	<li>Improved error message when there are errors in the model (instead of
! 		cryptic tracebacks).  In many cases the filename of the model and the
  	line number are printed, along with the error message.
  </ul>

Index: UsersGuide.html
===================================================================
RCS file: /cvsroot/webware/Webware/MiddleKit/Docs/UsersGuide.html,v
retrieving revision 1.24
retrieving revision 1.25
diff -C2 -d -r1.24 -r1.25
*** UsersGuide.html	12 Feb 2003 06:27:59 -0000	1.24
--- UsersGuide.html	24 Feb 2004 02:04:13 -0000	1.25
***************
*** 258,262 ****
  <p> <span class=filename>Settings.config</span> is the primary configuration file.
  
! <p> The <span class=name>Package</span> setting can be used to declare the package that your set of middle objects are contained by. This is useful for keeping your middle objects packaged away from other parts of your programs, thereby reducing the chances of a name conflict. This is the recommended way of using MK.
  
  <p> An example <a name=filename>Settings.config</a>:
--- 258,262 ----
  <p> <span class=filename>Settings.config</span> is the primary configuration file.
  
! <p> <a name=Configuration_Package></a>The <span class=name>Package</span> setting can be used to declare the package that your set of middle objects are contained by. This is useful for keeping your middle objects packaged away from other parts of your programs, thereby reducing the chances of a name conflict. This is the recommended way of using MK.
  
  <p> An example <a name=filename>Settings.config</a>:
***************
*** 274,278 ****
  
  
! <p> The <span class=name>SQLLog</span> setting can be used to get MiddleKit to echo all SQL statements to 'stdout', 'stderr' or a filename. For filenames, an optional 'Mode' setting inside SQLLog can be used to write over or append to an existing file. The default is write. Here are some examples:
  
  <pre>{
--- 274,278 ----
  
  
! <p> <a name=Configuration_SQLLog></a> The <span class=name>SQLLog</span> setting can be used to get MiddleKit to echo all SQL statements to 'stdout', 'stderr' or a filename. For filenames, an optional 'Mode' setting inside SQLLog can be used to write over or append to an existing file. The default is write. Here are some examples:
  
  <pre>{
***************
*** 289,293 ****
  
  
! <p> The <span class=name>Database</span> setting overrides the database name, which is otherwise assumed to be same name as the model. This is particularly useful if you are running two instances of the same application on one host.
  
  <pre>{
--- 289,293 ----
  
  
! <p> <a name=Configuration_Database></a> The <span class=name>Database</span> setting overrides the database name, which is otherwise assumed to be same name as the model. This is particularly useful if you are running two instances of the same application on one host.
  
  <pre>{
***************
*** 296,300 ****
  
  
! <p> The <span class=name>DeleteBehavior</span> setting can be used to change what MiddleKit does when you delete objects.
  The default behavior is "delete" which means that objects are deleted from the SQL database when they are deleted from the MiddleKit object store.
  But setting DeleteBehavior to "mark" causes an extra SQL datetime column called "deleted" to be added to each SQL table, and records that are deleted from the object store in MiddleKit are kept in SQL tables with the deleted field set to the date/time when the object was deleted.
--- 296,300 ----
  
  
! <p> <a name=Configuration_DeleteBehavior></a> The <span class=name>DeleteBehavior</span> setting can be used to change what MiddleKit does when you delete objects.
  The default behavior is "delete" which means that objects are deleted from the SQL database when they are deleted from the MiddleKit object store.
  But setting DeleteBehavior to "mark" causes an extra SQL datetime column called "deleted" to be added to each SQL table, and records that are deleted from the object store in MiddleKit are kept in SQL tables with the deleted field set to the date/time when the object was deleted.
***************
*** 305,309 ****
  }</pre>
  
! <p> The <span class=name>SQLConnectionPoolSize</span> setting is used to create a <a href=../../MiscUtils/Docs/index.html>MiscUtils</a>.DBPool instance for use by the store. For DB API modules with a threadsafety of only 1 (such as MySQLdb), this is particularly useful (in one benchmark, the speed up was 15 - 20%). Simply set the size of the pool in order to have one created and used:
  
  <pre>{
--- 305,309 ----
  }</pre>
  
! <p> <a name=Configuration_SQLConnectionPoolSize></a> The <span class=name>SQLConnectionPoolSize</span> setting is used to create a <a href=../../MiscUtils/Docs/index.html>MiscUtils</a>.DBPool instance for use by the store. For DB API modules with a threadsafety of only 1 (such as MySQLdb), this is particularly useful (in one benchmark, the speed up was 15 - 20%). Simply set the size of the pool in order to have one created and used:
  
  <pre>{
***************
*** 311,317 ****
  }</pre>
  
- <p> The <span class=name>UsePickledClassesCache</span> setting defaults to 1 and causes MiddleKit to cache the <span class=filename>Classes.csv</span> text file as a binary pickle file named <span class=filename>Classes.pickle.cache</span>. This reduces subsequent load times by about 40%. The cache will be ignored if it can't be read, is older than the CSV file, has a different Python version, etc. You don't normally even need to think about this, but if for some reason you would like to turn off the use of the cache, you can do so through this setting.
  
! <p> <span class=filename>SQLGenerator.config</span> has one setting: <span class=name>DropStatements</span> whose potential values are:
  
  <ul>
--- 311,333 ----
  }</pre>
  
  
! <p> <a name=Configuration_ObjRefSuffixes></a> The <span class=name>ObjRefSuffixes</span> controls the suffixes that are appended for the names of the two SQL column that are created for each obj ref attribute. The suffixes must be different from each other.
! 
! <pre>{
!     'ObjRefSuffixes': ('ClassId', 'ObjId'),  # the default
! }</pre>
! 
! 
! <p> <a name=Configuration_UseBigIntObjRefColumns></a> The <span class=name>UseBigIntObjRefColumns</span> causes MiddleKit to store object references in 64-bit fields, instead of in two fields (one for the class id and one for the obj id). You would only do this for a legacy MiddleKit application. Turning this on obsoletes the ObjRefSuffixes setting.
! 
! <pre>{
!     'UseBigIntObjRefColumns': True,  # use single 64-bit obj ref fields
! }</pre>
! 
! 
! 
! <p> <a name=Configuration_UsePickledClassesCache></a> The <span class=name>UsePickledClassesCache</span> setting defaults to 1 and causes MiddleKit to cache the <span class=filename>Classes.csv</span> text file as a binary pickle file named <span class=filename>Classes.pickle.cache</span>. This reduces subsequent load times by about 40%. The cache will be ignored if it can't be read, is older than the CSV file, has a different Python version, etc. You don't normally even need to think about this, but if for some reason you would like to turn off the use of the cache, you can do so through this setting.
! 
! <p> <a name=Configuration_DropStatements></a> The <span class=name>DropStatements</span> setting has these potential values:
  
  <ul>
***************
*** 320,325 ****
  </ul>
  
- <p> An example <a name=filename>SQLGenerator.config</a>:
- 
  <pre>{
      'DropStatements': 'database',  # database, tables
--- 336,339 ----