++++
News
++++

.. contents:: Contents:
   :backlinks: none

SQLObject 0.6.1
===============

Interface Changes
-----------------

* The long broken and unused ``DBMConnection`` has been removed.

* Added a connection parameter to all class methods (patch 974755)

* Connection objects have a ``.module`` attribute, which points to
  the DB-API module.  This is useful for getting access to the
  exception objects.

Features
--------

* New ``UnicodeCol()`` that converts to and from Unicode
  in the database.  See docs_.

.. _docs: SQLObject.html#subclasses-of-col

* Added indexing (from Jeremy Fitzhardinge).  See `the
  documentation`__ for more.

.. __: SQLObject.html#indexes

* All connections are explicitly closed, not just garbage collected.
  Many database drivers don't close database connections properly when
  the connection object is garbage collected.

* New ``distinct`` option to selects, like ``MyClass.select(...,
  distinct=True)``

* You can now do
  ``MyClass.selectBy(joinedTable=joinedTableInstance)``, where before
  you had to do
  ``MyClass.selectBy(joinedTableID=joinedTableInstance.id)``.  (From
  Dave Cook)

SQLObject 0.6
=============

Interface Changes
-----------------

* Lazy updates.  Add ``_lazyUpdate=True`` to your class, and updates
  will only be written when you call ``obj.syncUpdate()`` or
  ``obj.sync()`` (``sync`` also refetches the data from the database,
  which ``syncUpdate`` does not do).  When enabled, instances have a
  property ``dirty``, which indicates if they have pending updates.
  Inserts are still done immediately.

* Separated database drivers (PostgresConnection, MySQLConnection,
  etc.) into separate packages.  You can access the driver through
  URIs, like ``mysql://user:pass@host/dbname`` -- to set drivers after
  class creation you should use `sqlobject.connectionForURI()`.

* The ``SQLObject`` package has been renamed to ``sqlobject``.  This
  makes it similar to several other packages, and emphasizes the
  distinction between the ``sqlobject`` package and the ``SQLObject``
  class.

* Class instantiation now creates new rows (like `.new()` used to
  do), and the `.get()` method now retrieves objects that already have
  rows (like class instantiation used to do).

* We're now using a Subversion repository instead of CVS.  It is
  located at http://svn.colorstudy.com/trunk/SQLObject

* If you pass ``forceDBName=True`` to the ``*Col`` constructors, then
  your column name doesn't have to be restricted to a-z, 0-9, and _.

* ``*Col`` constructors now support cascade: ``cascade=None``
  (default) means no constraint; ``cascade=True`` means that if the
  foreign key is deleted, the object will be deleted;
  ``cascade=False`` means that the delete will fail;
  ``cascade="null"`` means that the column will be set to NULL.  The
  constraints are only implemented in the DBMS, not in SQLObject
  (i.e., they will not work in databases like MySQL and SQLite).

* New ``_create(id, **kw)`` method that can be overridden to intercept
  and modify attempts to insert rows in the database.

* You can specify ``_idType`` in your class, like ``_idType = str``.
  The default type is ``int``; i.e., IDs are coerced to integers.
  This is a temporary interface; a more general specifier for primary
  keys will be added later.

* New classmethod ``createTableSQL()`` method for SQLObject classes,
  which returns the SQL that can be used to create the table.  Analog
  to ``createTable()``.

Bugs
----

* SQLite booleans fixed.

* You can now use ``sqlite:/:memory:`` to store the database in
  memory.

* Some bugs resolved when caching is turned off (SF 956847)

SQLObject 0.5.3
===============

Bugs
----

* Python 2.2 booleans fixed (SF: 903488)

* Longs (e.g., ``1L``) get converted properly (SF: 939965)

SQLObject 0.5.2
===============

We're now using Subversion instead of CVS.  The repository is located
at svn://colorstudy.com/trunk/SQLObject

Interface Changes
-----------------

* If you commit or rollback a transaction, you must call
  ``trans.begin()`` to restart the transaction.  Any database access on
  the transaction inbetween commit/rollback and being will result in an
  AssertionError.  (It's also acceptable to create a new transaction
  object instead of reusing the old one, but objects in that
  transaction will be invalid)

Bugs
----

* Using .select() would hold on to a connection, and also release it
  back to the connection pool.  Very un-threadsafe and all-around
  bad.
* Fixed bug which did not release connections after database (query)
  error.
* When setting columns that use validators, the Pythonic
  (vs. database) representation wasn't being stored in the column.
  Now we roundtrip (through toPython and fromPython) the values when
  they get set.
* PostgreConnection is back to using sequences for ID generation,
  instead of oids.  Long explanation -- oids can be unindexed in some
  versions of Postgres, or not even exist.
* When turning caching off and using transactions, got an attribute
  error on rollback.
* Rollback or commit didn't find objects that were expired from the
  cache but still in memory.
* Rollback or commit didn't free the connection object, so as you
  created more transactions it stole connections and didn't put them
  back in the pool.

SQLObject 0.5.1
===============

Released: 12-Nov-2003

Interface Changes
-----------------

* Select results no longer have a __len__ method (i.e., you can't do
  ``len(Person.select(Person.q.firstName=='Bob'))``).  There is now a
  ``.count()`` method instead.  ``__len__`` gets called implicitly in
  several circumstances, like ``list()``, which causes potentially
  expensive queries to ``COUNT(*)``.

Bugs
----

* Objects retrieved from a join now respect the transaction context of
  the original instance.
* ``.select().reversed()`` works.

SQLObject 0.5
=============

Released: 1-Nov-2003

Features
--------

* Firebird_ support.

* Database-specific literal quoting (motivation: MySQL and Postgres
  use backslashes, Firebird and SQLite do not).

* Generic conversion/validation can be added to columns.

* BoolCol for portable boolean columns (BOOL on Postgres, INT on
  MySQL, etc.)

* Non-integer IDs.  (Automatic table creation is not supported for
  non-integer IDs)

* Explicit IDs for new instances/rows (required for non-integer IDs).

* Instances can be synced with the database (in case there have been
  updates to the object since it was first fetched).

* Instances can be expired, so that they will be synced when they are
  next accessed.

.. _Firebird: http://firebird.sourceforge.net/

Interface Changes
-----------------

* `SQLBuilder.sqlRepr` renamed to `SQLBuilder.sqlrepr`, signature
  changed to ``sqlrepr(value, databaseName)`` to quote ``value``,
  where ``databaseName`` is one of ``"mysql"``, ``"postgres"``,
  ``"sqlite"``, ``"firebird"``.

* ``sqlRepr`` magic method renamed to ``__sqlrepr__``, and takes new
  ``databaseName`` argument.

* When using explicit booleans, use ``Col.TRUE`` and ``Col.FALSE`` for
  backward compatibility with Python 2.2.  This is not required for
  ``BoolCol``, however (which converts all true values to TRUE and
  false values to FALSE)

* SQLObject has a ``sqlrepr`` method, so you can construct queries
  with something like ``"WHERE last_name = %s" %
  Person.sqlrepr('Bob')``

Bugs
----

* Released all locks with ``finally:``, so that bugs won't cause
  frozen locks.

* Tons of transaction fixes.  Transactions pretty much work.

* A class can have multiple foreign keys pointing to the same table
  (e.g., ``spouse = ForeignKey("Person"); supervisor =
  ForeignKey("Person")``)

SQLObject 0.4
=============

Features
--------

* You can specify columns in a new, preferred manner::

      class SomeObject(SQLObject):
          someColumn = Col()

  Equivalent to::

      class SomeObject(SQLObject):
          _columns = [Col('someColumn')]

  Ditto joins.

* Cache objects have a clear method, which empties all objects.
  However, weak references to objects *are* maintained, so the
  integrity of the cache can be ensured.

* SQLObject subclasses can be further subclassed, adding or removing
  column definitions (as well as changing settings like connection,
  style, etc).  Each class still refers to a single concrete table in
  the database -- the class hierarchy is not represented in the
  database.

* Each SQLObject subclass can have an associated style, as given in
  the `_style` attribute.  This object is used to map between Python
  and database names (e.g., the column name for a Python attribute).
  Some samples are available in the `Style` module.

* Postgres support for `_fromDatabase` (reading a table definition from
  the database, and creating a class from that).

* Postgres id columns more permissive, you don't have to create a
  specially named sequence (or implicitly create that sequence through
  ``SERIAL``).  lastoid is used instead.

* MySQL uses ``localhost`` as the default host, and the empty string
  as the default password.

* Added functions for use with queries: `ISNULL`, `ISNOTNULL`.  ``==``
  and ``!=`` can be used with None, and is translated into `ISNULL`,
  `ISNOTNULL`.

* Classes can be part of a specific registry.  Since classes are
  referred to by name in several places, the names have to be unique.
  This can be problematic, so you can add a class variable `_registry`,
  the value of which should be a string.  Classes references are
  assumed to be inside that registry, and class names need only be
  unique among classes in that registry.

* ``SomeClass.select()`` selects all, instead of using
  ``SomeClass.select('all')``.  You can also use None instead of
  ``'all'``.

* Trying to fetch non-existent objects raises `SQLObjectNotFound`,
  which is a subclass of the builtin exception `LookupError`.
  This may not be raised if `_cacheValues` is False and you use
  the ID to fetch an object (but alternateID fetches will raise
  the exception in either case).

* Can order by descending order, with the `reversed` option to
  the `select` method, or by prefixing the column with a ``"-"``.

* Ordering with joins works better -- you can order with multiple
  columns, as well as descending ordering.

Col and Join
~~~~~~~~~~~~

* `Join` constructors have an argument `orderBy`, which is the name
  of a Python attribute to sort results by.  If not given, the
  appropriate class's `_defaultOrder` will be used.  None implies
  no sorting (and ``orderBy=None`` will override `_defaultOrder`).

* `ForeignKey` class (subclass of `Col`), for somewhat easier/clearer
  declaration of foreign keys.

* `Col` (and subclasses) can take a `sqlType` argument, which is used
  in table definitions.  E.g., ``Col(sqlType="BOOLEAN")`` can be used
  to create a ``BOOLEAN`` column, even though no `BooleanCol` exists.

* `alternateID` (a specifier for columns) implies ``NOT NULL``.  Also
  implies ``UNIQUE``.

* `unique` (a specifier for columns) added.

* `DecimalCol` and `CurrencyCol` added.

* `EnumCol` uses constraints on Postgres (if you use `createTable`).

Bugs
----

* `DateTimeCol` uses ``TIMESTAMP`` for Postgres.  Note that the
  Python type name is used for column names, not necessarily the
  SQL standard name.

* Foreign key column names are slightly more permissive.  They still
  need to end in ``id``, but it's case insensitive.

* _defaultOrder should be the python attribute's name, not the database
  name.

* SomeClass.q.colName uses proper Python attributes for colName, and
  proper database names when executed in the database.

* SQLite select results back to being proper iterator.

* SomeClass.q.colName now does proper translation to database names,
  using dbName, etc., instead of being entirely algorithm-driven.

* Raise `TypeError` if you pass an unknown argument to the `new`
  method.

* You can override the _get_* or _set_* version of a property without
  overriding the other.

* Python 2.3 compatible.

* Trying to use ``Col('id')`` or ``id = Col()`` will raise an
  exception, instead of just acting funky.

* ``ForeignKey`` columns return None if the associated column is
  NULL in the database (used to just act weird).

* Instantiating an object with an id of None will give an error,
  instead of just acting weird.

Internal
--------

* `Col` class separated into `Col` and `SOCol` (and same for all other
  `*Col` classes).  `Col` defines a column, `SOCol` is that definition
  bound to a particular SQLObject class.

* Instance variable ``_SO_columns`` holds the `SOCol` instances.

SQLObject 0.3
=============

Features
--------

* Table creation (SQL schema generation) via new class method
  `createTable`.  And of course a `dropTable` method to go with.

* Add and remove columns at runtime, optionally modifying the
  schema in the database (via ``ALTER``).  (Does not work in
  SQLite)

* New column classes (see `Col` module), indicates type

* Classes can be created by parsing an already existant table
  (MySQL only).

* Objects are not cached indefinitely.  Cached objects are expired
  into a weak dictionary (it allows objects to be garbage collected if
  nowhere else in the program is using the object, but until it is
  collected it's still available to the cache).  Some cache control,
  pass ``nocache=True`` to your connection object to eliminate as much
  caching as possible.  See `Cache` module for a bit more.

* New DBMConnection, implements a database-like backend without any
  database to speak of, including queries (so long as you use
  `SQLBuilder` and don't generate your where clauses manually).
  Actual SQL generation is done entirely by the database connection,
  allowing portability across very different backends.

* Postgres table IDs should be created with type ``SERIAL`` (which
  implicitly creates a sequence).

* New `_defaultOrder` class variable gives a default for the
  `orderBy` parameter to `select` queries.

Bugs
----

* LIMIT/OFFSET (select result slicing) works in Postgres and SQLite.

* ``tableExists`` method from DBConnection works in same.

* mxDateTime not required (never should have been, always just an
  option).

SQLObject 0.2.1
===============

Bugs
----

* Fixed caching of new objects

Features
--------

* SQLite_ support

* Select statements are lazily generated, retrieve full rows for
  speed, and are slicable (`select docs`_).

* `alternateID` option for `Col` objects -- select individual objects
  via UNIQUE columns, e.g., a username (`Col docs`_).

.. _SQLite: http://sqlite.org/

.. _select docs: SQLObject.html#selecting-multiple-objects

.. _Col docs: SQLObject.html#col-class-specifying-columns

.. image:: https://sourceforge.net/sflogo.php?group_id=74338&type=10
   :target: https://sourceforge.net/projects/sqlobject
   :class: noborder
   :align: center
   :height: 15
   :width: 80
   :alt: Get SQLObject at SourceForge.net. Fast, secure and Free Open Source software downloads