# SQLAlchemy 0.5.5 Documentation

Search:
Version: 0.5.5 Last Updated: 07/13/2009 15:02:35

# Column and Data Types

SQLAlchemy provides abstractions for most common database data types, and a mechanism for specifying your own custom data types.

The methods and attributes of type objects are rarely used directly. Type objects are supplied to `Table` definitions and can be supplied as type hints to functions for occasions where the database driver returns an incorrect type.

    >>> users = Table('users', metadata,
    ...               Column('id', Integer, primary_key=True)
    ...               Column('login', String(32))
    ...              )

SQLAlchemy will use the `Integer` and `String(32)` type information when issuing a `CREATE TABLE` statement and will use it again when reading back rows `SELECTed` from the database. Functions that accept a type (such as `Column()`) will typically accept a type class or instance; `Integer` is equivalent to `Integer()` with no construction arguments in this case.

## Generic Types

Generic types specify a column that can read, write and store a particular type of Python data. SQLAlchemy will choose the best database column type available on the target database when issuing a `CREATE TABLE` statement. For complete control over which column type is emitted in `CREATE TABLE`, such as `VARCHAR` see SQL Standard Types and the other sections of this chapter.

class `sqlalchemy.types.``String`(length=None, convert_unicode=False, assert_unicode=None)

  Bases: `sqlalchemy.types.Concatenable`, `sqlalchemy.types.TypeEngine`

  The base for all string and character types.

  In SQL, corresponds to VARCHAR. Can also take Python unicode objects and encode to the database’s encoding in bind params (and the reverse for result sets.)

  The length field is usually required when the String type is used within a CREATE TABLE statement, as VARCHAR requires a length on most databases.

class `sqlalchemy.types.``Unicode`(length=None, **kwargs)

  Bases: `sqlalchemy.types.String`

  A variable length Unicode string.

  The `Unicode` type is a `String` which converts Python `unicode` objects (i.e., strings that are defined as `u'somevalue'`) into encoded bytestrings when passing the value to the database driver, and similarly decodes values from the database back into Python `unicode` objects.

  When using the `Unicode` type, it is only appropriate to pass Python `unicode` objects, and not plain `str`. If a bytestring (`str`) is passed, a runtime warning is issued. If you notice your application raising these warnings but you’re not sure where, the Python `warnings` filter can be used to turn these warnings into exceptions which will illustrate a stack trace:

      import warnings
      warnings.simplefilter('error')

  Bytestrings sent to and received from the database are encoded using the dialect’s `encoding`, which defaults to utf-8.

  A synonym for String(length, convert_unicode=True, assert_unicode=’warn’).

class `sqlalchemy.types.``Text`(length=None, convert_unicode=False, assert_unicode=None)

  Bases: `sqlalchemy.types.String`

  A variably sized string type.

  In SQL, usually corresponds to CLOB or TEXT. Can also take Python unicode objects and encode to the database’s encoding in bind params (and the reverse for result sets.)

class `sqlalchemy.types.``UnicodeText`(length=None, **kwargs)

  Bases: `sqlalchemy.types.Text`

  A synonym for Text(convert_unicode=True, assert_unicode=’warn’).

class `sqlalchemy.types.``Integer`(*args, **kwargs)

  Bases: `sqlalchemy.types.TypeEngine`

  A type for `int` integers.

class `sqlalchemy.types.``SmallInteger`(*args, **kwargs)

  Bases: `sqlalchemy.types.Integer`

  A type for smaller `int` integers.

  Typically generates a `SMALLINT` in DDL, and otherwise acts like a normal `Integer` on the Python side.

class `sqlalchemy.types.``Numeric`(precision=10, scale=2, asdecimal=True, length=None)

  Bases: `sqlalchemy.types.TypeEngine`

  A type for fixed precision numbers.

  Typically generates DECIMAL or NUMERIC. Returns `decimal.Decimal` objects by default.

class `sqlalchemy.types.``Float`(precision=10, asdecimal=False, **kwargs)

  Bases: `sqlalchemy.types.Numeric`

  A type for `float` numbers.

class `sqlalchemy.types.``DateTime`(timezone=False)

  Bases: `sqlalchemy.types.TypeEngine`

  A type for `datetime.datetime()` objects.

  Date and time types return objects from the Python `datetime` module. Most DBAPIs have built in support for the datetime module, with the noted exception of SQLite. In the case of SQLite, date and time types are stored as strings which are then converted back to datetime objects when rows are returned.

class `sqlalchemy.types.``Date`(*args, **kwargs)

  Bases: `sqlalchemy.types.TypeEngine`

  A type for `datetime.date()` objects.

class `sqlalchemy.types.``Time`(timezone=False)

  Bases: `sqlalchemy.types.TypeEngine`

  A type for `datetime.time()` objects.

class `sqlalchemy.types.``Interval`

  Bases: `sqlalchemy.types.TypeDecorator`

  A type for `datetime.timedelta()` objects.

  The Interval type deals with `datetime.timedelta` objects. In PostgreSQL, the native `INTERVAL` type is used; for others, the value is stored as a date which is relative to the “epoch” (Jan. 1, 1970).

class `sqlalchemy.types.``Boolean`(*args, **kwargs)

  Bases: `sqlalchemy.types.TypeEngine`

  A bool datatype.

  Boolean typically uses BOOLEAN or SMALLINT on the DDL side, and on the Python side deals in `True` or `False`.

class `sqlalchemy.types.``Binary`(length=None)

  Bases: `sqlalchemy.types.TypeEngine`

  A type for binary byte data.

  The Binary type generates BLOB or BYTEA when tables are created, and also converts incoming values using the `Binary` callable provided by each DB-API.

class `sqlalchemy.types.``PickleType`(protocol=2, pickler=None, mutable=True, comparator=None)

  Bases: `sqlalchemy.types.MutableType`, `sqlalchemy.types.TypeDecorator`

  Holds Python objects.

  PickleType builds upon the Binary type to apply Python’s `pickle.dumps()` to incoming objects, and `pickle.loads()` on the way out, allowing any pickleable Python object to be stored as a serialized binary field.

## SQL Standard Types

The SQL standard types always create database column types of the same name when `CREATE TABLE` is issued. Some types may not be supported on all databases.

class `sqlalchemy.types.``INT`(*args, **kwargs)

  Bases: `sqlalchemy.types.Integer`

  The SQL INT or INTEGER type.

`sqlalchemy.types.``INTEGER`
  alias of `INT`

class `sqlalchemy.types.``CHAR`(length=None, convert_unicode=False, assert_unicode=None)

  Bases: `sqlalchemy.types.String`

  The SQL CHAR type.

class `sqlalchemy.types.``VARCHAR`(length=None, convert_unicode=False, assert_unicode=None)

  Bases: `sqlalchemy.types.String`

  The SQL VARCHAR type.

class `sqlalchemy.types.``NCHAR`(length=None, **kwargs)

  Bases: `sqlalchemy.types.Unicode`

  The SQL NCHAR type.

`sqlalchemy.types.``TEXT`
  alias of `Text`

class `sqlalchemy.types.``FLOAT`(precision=10, asdecimal=False, **kwargs)

  Bases: `sqlalchemy.types.Float`

  The SQL FLOAT type.

class `sqlalchemy.types.``NUMERIC`(precision=10, scale=2, asdecimal=True, length=None)

  Bases: `sqlalchemy.types.Numeric`

  The SQL NUMERIC type.

class `sqlalchemy.types.``DECIMAL`(precision=10, scale=2, asdecimal=True, length=None)

  Bases: `sqlalchemy.types.Numeric`

  The SQL DECIMAL type.

class `sqlalchemy.types.``TIMESTAMP`(timezone=False)

  Bases: `sqlalchemy.types.DateTime`

  The SQL TIMESTAMP type.

class `sqlalchemy.types.``DATETIME`(timezone=False)

  Bases: `sqlalchemy.types.DateTime`

  The SQL DATETIME type.

class `sqlalchemy.types.``CLOB`(length=None, convert_unicode=False, assert_unicode=None)

  Bases: `sqlalchemy.types.Text`

  The SQL CLOB type.

class `sqlalchemy.types.``BLOB`(length=None)

  Bases: `sqlalchemy.types.Binary`

  The SQL BLOB type.

class `sqlalchemy.types.``BOOLEAN`(*args, **kwargs)

  Bases: `sqlalchemy.types.Boolean`

  The SQL BOOLEAN type.

class `sqlalchemy.types.``SMALLINT`(*args, **kwargs)

  Bases: `sqlalchemy.types.SmallInteger`

  The SQL SMALLINT type.

class `sqlalchemy.types.``DATE`(*args, **kwargs)

  Bases: `sqlalchemy.types.Date`

  The SQL DATE type.

class `sqlalchemy.types.``TIME`(timezone=False)

  Bases: `sqlalchemy.types.Time`

  The SQL TIME type.

## Vendor-Specific Types

Database-specific types are also available for import from each database’s dialect module. See the sqlalchemy.databases reference for the database you’re interested in.

For example, MySQL has a `BIGINTEGER` type and PostgreSQL has an `INET` type. To use these, import them from the module explicitly:

    from sqlalchemy.databases.mysql import MSBigInteger, MSEnum

    table = Table('foo', meta,
        Column('id', MSBigInteger),
        Column('enumerates', MSEnum('a', 'b', 'c'))
    )

Or some PostgreSQL types:

    from sqlalchemy.databases.postgres import PGInet, PGArray

    table = Table('foo', meta,
        Column('ipaddress', PGInet),
        Column('elements', PGArray(str))
        )

## Custom Types

User-defined types may be created to match special capabilities of a particular database or simply for implementing custom processing logic in Python.

The simplest method is implementing a `TypeDecorator`, a helper class that makes it easy to augment the bind parameter and result processing capabilities of one of the built in types.

To build a type object from scratch, subclass :class:TypeEngine.

class `sqlalchemy.types.``TypeDecorator`(*args, **kwargs)

  Bases: `sqlalchemy.types.AbstractType`

  Allows the creation of types which add additional functionality to an existing type.

  Typical usage:

      import sqlalchemy.types as types

      class MyType(types.TypeDecorator):
          # Prefixes Unicode values with "PREFIX:" on the way in and
          # strips it off on the way out.

          impl = types.Unicode

          def process_bind_param(self, value, dialect):
              return "PREFIX:" + value

          def process_result_value(self, value, dialect):
              return value[7:]

          def copy(self):
              return MyType(self.impl.length)

  The class-level “impl” variable is required, and can reference any TypeEngine class. Alternatively, the load_dialect_impl() method can be used to provide different type classes based on the dialect given; in this case, the “impl” variable can reference `TypeEngine` as a placeholder.

  The reason that type behavior is modified using class decoration instead of subclassing is due to the way dialect specific types are used. Such as with the example above, when using the mysql dialect, the actual type in use will be a `sqlalchemy.databases.mysql.MSString` instance. `TypeDecorator` handles the mechanics of passing the values between user-defined `process_` methods and the current dialect-specific type in use.

  `__init__`(*args, **kwargs)
  `adapt_operator`(op)

    Given an operator from the sqlalchemy.sql.operators package, translate it to a new operator based on the semantics of this type.

    By default, returns the operator unchanged.

  `bind_processor`(dialect)
  `compare_values`(x, y)
  `copy`()
  `copy_value`(value)
  `dialect_impl`(dialect, **kwargs)
  `get_col_spec`()
  `get_dbapi_type`(dbapi)
  `is_mutable`()
  `load_dialect_impl`(dialect)

    Loads the dialect-specific implementation of this type.

    by default calls dialect.type_descriptor(self.impl), but can be overridden to provide different behavior.

  `process_bind_param`(value, dialect)
  `process_result_value`(value, dialect)
  `result_processor`(dialect)

class `sqlalchemy.types.``TypeEngine`(*args, **kwargs)

  Bases: `sqlalchemy.types.AbstractType`

  Base for built-in types.

  May be sub-classed to create entirely new types. Example:

      import sqlalchemy.types as types

      class MyType(types.TypeEngine):
          def __init__(self, precision = 8):
              self.precision = precision

          def get_col_spec(self):
              return "MYTYPE(%s)" % self.precision

          def bind_processor(self, dialect):
              def process(value):
                  return value
              return process

          def result_processor(self, dialect):
              def process(value):
                  return value
              return process

  Once the type is made, it’s immediately usable:

      table = Table('foo', meta,
          Column('id', Integer, primary_key=True),
          Column('data', MyType(16))
          )

  `__init__`(*args, **kwargs)
  `adapt`(cls)
  `adapt_operator`(op)

    Given an operator from the sqlalchemy.sql.operators package, translate it to a new operator based on the semantics of this type.

    By default, returns the operator unchanged.

  `bind_processor`(dialect)

    Return a conversion function for processing bind values.

    Returns a callable which will receive a bind parameter value as the sole positional argument and will return a value to send to the DB-API.

    If processing is not necessary, the method should return `None`.

  `compare_values`(x, y)
    Compare two values for equality.
  `copy_value`(value)
  `dialect_impl`(dialect, **kwargs)
  `get_col_spec`()
    Return the DDL representation for this type.
  `get_dbapi_type`(dbapi)

    Return the corresponding type object from the underlying DB-API, if any.

    This can be useful for calling `setinputsizes()`, for example.

  `get_search_list`()
    return a list of classes to test for a match when adapting this type to a dialect-specific type.
  `is_mutable`()

    Return True if the target Python type is ‘mutable’.

    This allows systems like the ORM to know if a column value can be considered ‘not changed’ by comparing the identity of objects alone.

    Use the `MutableType` mixin or override this method to return True in custom types that hold mutable values such as `dict`, `list` and custom objects.

  `result_processor`(dialect)

    Return a conversion function for processing result row values.

    Returns a callable which will receive a result row column value as the sole positional argument and will return a value to return to the user.

    If processing is not necessary, the method should return `None`.

class `sqlalchemy.types.``AbstractType`(*args, **kwargs)

  Bases: `object`

  `__init__`(*args, **kwargs)
  `adapt_operator`(op)

    Given an operator from the sqlalchemy.sql.operators package, translate it to a new operator based on the semantics of this type.

    By default, returns the operator unchanged.

  `bind_processor`(dialect)
    Defines a bind parameter processing function.
  `compare_values`(x, y)
    Compare two values for equality.
  `copy_value`(value)
  `get_dbapi_type`(dbapi)

    Return the corresponding type object from the underlying DB-API, if any.

    This can be useful for calling `setinputsizes()`, for example.

  `is_mutable`()

    Return True if the target Python type is ‘mutable’.

    This allows systems like the ORM to know if a column value can be considered ‘not changed’ by comparing the identity of objects alone.

    Use the `MutableType` mixin or override this method to return True in custom types that hold mutable values such as `dict`, `list` and custom objects.

  `result_processor`(dialect)
    Defines a result-column processing function.

class `sqlalchemy.types.``MutableType`

  Bases: `object`

  A mixin that marks a Type as holding a mutable object.

  `copy_value()` and `compare_values()` should be customized as needed to match the needs of the object.

  `__init__`()
    x.__init__(...) initializes x; see x.__class__.__doc__ for signature
  `compare_values`(x, y)
    Compare x == y.
  `copy_value`(value)
    Unimplemented.
  `is_mutable`()
    Return True, mutable.

class `sqlalchemy.types.``Concatenable`

  Bases: `object`

  A mixin that marks a type as supporting ‘concatenation’, typically strings.

  `__init__`()
    x.__init__(...) initializes x; see x.__class__.__doc__ for signature
  `adapt_operator`(op)
    Converts an add operator to concat.

class `sqlalchemy.types.``NullType`(*args, **kwargs)

  Bases: `sqlalchemy.types.TypeEngine`

  An unknown type.

  NullTypes will stand in if `Table` reflection encounters a column data type unknown to SQLAlchemy. The resulting columns are nearly fully usable: the DB-API adapter will handle all translation to and from the database data type.

  NullType does not have sufficient information to particpate in a `CREATE TABLE` statement and will raise an exception if encountered during a `create()` operation.