- modify what we did in [ticket:2793] so that we can also set the

version id programmatically outside of the generator.   using this system,
we can also leave the version id alone.

3 files changed, 60 insertions, 7 deletions

diff --git a/doc/build/changelog/changelog_09.rst b/doc/build/changelog/changelog_09.rst
index 03cecff2c..27cddd9bf 100644
--- a/doc/build/changelog/changelog_09.rst
+++ b/doc/build/changelog/changelog_09.rst
@@ -51,9 +51,11 @@
 
         The ``version_id_generator`` parameter of ``Mapper`` can now be specified
         to rely upon server generated version identifiers, using triggers
-        or other database-provided versioning features, by passing the value
-        ``False``.  The ORM will use RETURNING when available to immediately
-        load the new version identifier, else it will emit a second SELECT.
+        or other database-provided versioning features, or via an optional programmatic
+        value, by setting ``version_id_generator=False``.
+        When using a server-generated version identfier, the ORM will use RETURNING when
+        available to immediately
+        load the new version value, else it will emit a second SELECT.
 
     .. change::
         :tags: feature, orm
diff --git a/doc/build/changelog/migration_09.rst b/doc/build/changelog/migration_09.rst
index 82314cce4..cf345edbc 100644
--- a/doc/build/changelog/migration_09.rst
+++ b/doc/build/changelog/migration_09.rst
@@ -396,9 +396,12 @@ Server Side Version Counting
 
 The versioning feature of the ORM (now also documented at :ref:`mapper_version_counter`)
 can now make use of server-side version counting schemes, such as those produced
-by triggers or database system columns.   By providing the value ``False``
-to the ``version_id_generator`` parameter, the ORM will fetch the version identifier
-from each row at the same time the INSERT or UPDATE is emitted.   It is strongly
+by triggers or database system columns, as well as conditional programmatic schemes outside
+of the version_id_counter function itself.  By providing the value ``False``
+to the ``version_id_generator`` parameter, the ORM will use the already-set version
+identifier, or alternatively fetch the version identifier
+from each row at the same time the INSERT or UPDATE is emitted.   When using a
+server-generated version identifier, it is strongly
 recommended that this feature be used only on a backend where RETURNING can also
 be used, else the additional SELECT statements will add significant performance
 overhead.   The example provided at :ref:`server_side_version_counter` illustrates
diff --git a/doc/build/orm/mapper_config.rst b/doc/build/orm/mapper_config.rst
index c35e3429c..d35910745 100644
--- a/doc/build/orm/mapper_config.rst
+++ b/doc/build/orm/mapper_config.rst
@@ -1237,7 +1237,7 @@ subsequent value.
 .. _server_side_version_counter:
 
 Server Side Version Counters
------------------------------
+----------------------------
 
 The ``version_id_generator`` can also be configured to rely upon a value
 that is generated by the database.  In this case, the database would need
@@ -1311,6 +1311,54 @@ e.g. Postgresql, Oracle, SQL Server (though SQL Server has
 
     Support for server side version identifier tracking.
 
+Programmatic or Conditional Version Counters
+---------------------------------------------
+
+When ``version_id_generator`` is set to False, we can also programmatically
+(and conditionally) set the version identifier on our object in the same way
+we assign any other mapped attribute.  Such as if we used our UUID example, but
+set ``version_id_generator`` to ``False``, we can set the version identifier
+at our choosing::
+
+    import uuid
+
+    class User(Base):
+        __tablename__ = 'user'
+
+        id = Column(Integer, primary_key=True)
+        version_uuid = Column(String(32))
+        name = Column(String(50), nullable=False)
+
+        __mapper_args__ = {
+            'version_id_col':version_uuid,
+            'version_id_generator': False
+        }
+
+    u1 = User(name='u1', version_uuid=uuid.uuid4())
+
+    session.add(u1)
+
+    session.commit()
+
+    u1.name = 'u2'
+    u1.version_uuid = uuid.uuid4()
+
+    session.commit()
+
+We can update our ``User`` object without incrementing the version counter
+as well; the value of the counter will remain unchanged, and the UPDATE
+statement will still check against the previous value.  This may be useful
+for schemes where only certain classes of UPDATE are sensitive to concurrency
+issues::
+
+    # will leave version_uuid unchanged
+    u1.name = 'u3'
+    session.commit()
+
+.. versionadded:: 0.9.0
+
+    Support for programmatic and conditional version identifier tracking.
+
 
 Class Mapping API
 =================