Scylla Documentation Logo Documentation
  • Server
    • Scylla Open Source
    • Scylla Enterprise
    • Scylla Alternator
  • Cloud
    • Scylla Cloud
    • Scylla Cloud Docs
  • Tools
    • Scylla Manager
    • Scylla Monitoring Stack
    • Scylla Operator
  • Drivers
    • CQL Drivers
    • DynamoDB Drivers
Download
Menu

Caution

You're viewing documentation for a previous version of Scylla Python Driver. Switch to the latest stable version.

Scylla Python Driver Object Mapper Upgrade Guide

Upgrade Guide¶

This is an overview of things that changed as the cqlengine project was merged into scylla-driver. While efforts were taken to preserve the API and most functionality exactly, conversion to this package will still require certain minimal updates (namely, imports).

THERE IS ONE FUNCTIONAL CHANGE, described in the first section below.

Functional Changes¶

List Prepend Reversing¶

Legacy cqlengine included a workaround for a Cassandra bug in which prepended list segments were reversed (CASSANDRA-8733). As of this integration, this workaround is removed. The first released integrated version emits a warning when prepend is used. Subsequent versions will have this warning removed.

Date Column Type¶

The Date column type in legacy cqlengine used a timestamp CQL type and truncated the time. Going forward, the Date type represents a date for Cassandra 2.2+ (PYTHON-245). Users of the legacy functionality should convert models to use DateTime (which uses timestamp internally), and use the build-in datetime.date for input values.

Remove cqlengine¶

To avoid confusion or mistakes using the legacy package in your application, it is prudent to remove the cqlengine package when upgrading to the integrated version.

The driver setup script will warn if the legacy package is detected during install, but it will not prevent side-by-side installation.

Organization¶

Imports¶

cqlengine is now integrated as a sub-package of the driver base package ‘cassandra’. Upgrading will require adjusting imports to cqlengine. For example:

from cassandra.cqlengine import columns

is now:

from cassandra.cqlengine import columns

Package-Level Aliases¶

Legacy cqlengine defined a number of aliases at the package level, which became redundant when the package was integrated for a driver. These have been removed in favor of absolute imports, and referring to cannonical definitions. For example, cqlengine.ONE was an alias of cassandra.ConsistencyLevel.ONE. In the integrated package, only the cassandra.ConsistencyLevel remains.

Additionally, submodule aliases are removed from cqlengine in favor of absolute imports.

These aliases are removed, and not deprecated because they should be straightforward to iron out at module load time.

Exceptions¶

The legacy cqlengine.exceptions module had a number of Exception classes that were variously common to the package, or only used in specific modules. Common exceptions were relocated to cqlengine, and specialized exceptions were placed in the module that raises them. Below is a listing of updated locations:

Exception class

New module

CQLEngineException

cassandra.cqlengine

ModelException

cassandra.cqlengine.models

ValidationError

cassandra.cqlengine

UndefinedKeyspaceException

cassandra.cqlengine.connection

LWTException

cassandra.cqlengine.query

IfNotExistsWithCounterColumn

cassandra.cqlengine.query

UnicodeMixin Consolidation¶

class UnicodeMixin was defined in several cqlengine modules. This has been consolidated to a single definition in the cqlengine package init file. This is not technically part of the API, but noted here for completeness.

API Deprecations¶

This upgrade served as a good juncture to deprecate certain API features and invite users to upgrade to new ones. The first released version does not change functionality – only introduces deprecation warnings. Future releases will remove these features in favor of the alternatives.

Float/Double Overload¶

Previously there was no Double column type. Doubles were modeled by specifying Float(double_precision=True). This inititializer parameter is now deprecated. Applications should use Double for CQL double, and Float for CQL float.

Schema Management¶

cassandra.cqlengine.management.create_keyspace is deprecated. Instead, use the new replication-strategy-specific functions that accept explicit options for known strategies:

  • create_keyspace_simple()

  • create_keyspace_network_topology()

cassandra.cqlengine.management.delete_keyspace is deprecated in favor of a new function, drop_keyspace(). The intent is simply to make the function match the CQL verb it invokes.

Model Inheritance¶

The names for class attributes controlling model inheritance are changing. Changes are as follows:

  • Replace ‘polymorphic_key’ in the base class Column definition with discriminator_column

  • Replace the ‘__polymorphic_key__’ class attribute the derived classes with __discriminator_value__

The functionality is unchanged – the intent here is to make the names and language around these attributes more precise. For now, the old names are just deprecated, and the mapper will emit warnings if they are used. The old names will be removed in a future version.

The example below shows a simple translation:

Before:

class Pet(Model):
    __table_name__ = 'pet'
    owner_id = UUID(primary_key=True)
    pet_id = UUID(primary_key=True)
    pet_type = Text(polymorphic_key=True)
    name = Text()

class Cat(Pet):
    __polymorphic_key__ = 'cat'

class Dog(Pet):
    __polymorphic_key__ = 'dog'

After:

class Pet(models.Model):
    __table_name__ = 'pet'
    owner_id = UUID(primary_key=True)
    pet_id = UUID(primary_key=True)
    pet_type = Text(discriminator_column=True)
    name = Text()

class Cat(Pet):
    __discriminator_value__ = 'cat'

class Dog(Pet):
    __discriminator_value__ = 'dog'

TimeUUID.from_datetime¶

This function is deprecated in favor of the core utility function uuid_from_time().

PREVIOUS
Object Mapper
NEXT
Models
  • 3.21.0
    • 3.25.4
    • 3.24.8
    • 3.22.3
    • 3.21.0
  • API Documentation
    • cassandra - Exceptions and Enums
    • cassandra.cluster - Clusters and Sessions
    • cassandra.policies - Load balancing and Failure Handling Policies
    • cassandra.auth - Authentication
    • cassandra.graph - Graph Statements, Options, and Row Factories
    • cassandra.metadata - Schema and Ring Topology
    • cassandra.metrics - Performance Metrics
    • cassandra.query - Prepared Statements, Batch Statements, Tracing, and Row Factories
    • cassandra.pool - Hosts and Connection Pools
    • cassandra.protocol - Protocol Features
    • cassandra.encoder - Encoders for non-prepared Statements
    • cassandra.decoder - Data Return Formats
    • cassandra.concurrent - Utilities for Concurrent Statement Execution
    • cassandra.connection - Low Level Connection Info
    • cassandra.util - Utilities
    • cassandra.timestamps - Timestamp Generation
    • cassandra.io.asyncioreactor - asyncio Event Loop
    • cassandra.io.asyncorereactor - asyncore Event Loop
    • cassandra.io.eventletreactor - eventlet-compatible Connection
    • cassandra.io.libevreactor - libev Event Loop
    • cassandra.io.geventreactor - gevent-compatible Event Loop
    • cassandra.io.twistedreactor - Twisted Event Loop
    • cassandra.cqlengine.models - Table models for object mapping
    • cassandra.cqlengine.columns - Column types for object mapping models
    • cassandra.cqlengine.query - Query and filter model objects
    • cassandra.cqlengine.connection - Connection management for cqlengine
    • cassandra.cqlengine.management - Schema management for cqlengine
    • cassandra.cqlengine.usertype - Model classes for User Defined Types
    • cassandra.datastax.graph - Graph Statements, Options, and Row Factories
    • cassandra.datastax.graph.fluent
    • cassandra.datastax.graph.fluent.query
    • cassandra.datastax.graph.fluent.predicates
  • Installation
  • Getting Started
  • Upgrading
  • Execution Profiles
  • Performance Notes
  • Paging Large Queries
  • Lightweight Transactions (Compare-and-set)
  • Security
  • User Defined Types
  • Object Mapper
    • Upgrade Guide
    • Models
    • Making Queries
    • Batch Queries
    • Connections
    • Third party integrations
    • Frequently Asked Questions
  • Working with Dates and Times
  • Frequently Asked Questions
  • Create an issue
  • Edit this page

On this page

  • Upgrade Guide
    • Functional Changes
      • List Prepend Reversing
      • Date Column Type
    • Remove cqlengine
    • Organization
      • Imports
      • Package-Level Aliases
      • Exceptions
      • UnicodeMixin Consolidation
    • API Deprecations
      • Float/Double Overload
      • Schema Management
      • Model Inheritance
      • TimeUUID.from_datetime
Logo
Docs Contact Us About Us
Mail List Icon Slack Icon
© ScyllaDB 2021 and © DataStax 2013-2017
Powered by Sphinx 4.3.2 & ScyllaDB Theme 1.2.2