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 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.
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.
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’).
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.)
Bases: sqlalchemy.types.Text
A synonym for Text(convert_unicode=True, assert_unicode=’warn’).
Bases: sqlalchemy.types.TypeEngine
A type for int integers.
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.
Bases: sqlalchemy.types.TypeEngine
A type for fixed precision numbers.
Typically generates DECIMAL or NUMERIC. Returns decimal.Decimal objects by default.
Bases: sqlalchemy.types.Numeric
A type for float numbers.
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.
Bases: sqlalchemy.types.TypeEngine
A type for datetime.date() objects.
Bases: sqlalchemy.types.TypeEngine
A type for datetime.time() objects.
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).
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.
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.
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.
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.
Bases: sqlalchemy.types.Integer
The SQL INT or INTEGER type.
Bases: sqlalchemy.types.Integer
The SQL INT or INTEGER type.
Bases: sqlalchemy.types.String
The SQL CHAR type.
Bases: sqlalchemy.types.String
The SQL VARCHAR type.
Bases: sqlalchemy.types.Unicode
The SQL NCHAR type.
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.)
Bases: sqlalchemy.types.Float
The SQL FLOAT type.
Bases: sqlalchemy.types.Numeric
The SQL NUMERIC type.
Bases: sqlalchemy.types.Numeric
The SQL DECIMAL type.
Bases: sqlalchemy.types.DateTime
The SQL TIMESTAMP type.
Bases: sqlalchemy.types.DateTime
The SQL DATETIME type.
Bases: sqlalchemy.types.Text
The SQL CLOB type.
Bases: sqlalchemy.types.Binary
The SQL BLOB type.
Bases: sqlalchemy.types.Boolean
The SQL BOOLEAN type.
Bases: sqlalchemy.types.SmallInteger
The SQL SMALLINT type.
Bases: sqlalchemy.types.Date
The SQL DATE type.
Bases: sqlalchemy.types.Time
The SQL TIME type.
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))
)
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.
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.
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.
Loads the dialect-specific implementation of this type.
by default calls dialect.type_descriptor(self.impl), but can be overridden to provide different behavior.
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))
)
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.
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.
Return the corresponding type object from the underlying DB-API, if any.
This can be useful for calling setinputsizes(), for example.
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.
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.
Bases: object
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.
Return the corresponding type object from the underlying DB-API, if any.
This can be useful for calling setinputsizes(), for example.
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.
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.
Bases: object
A mixin that marks a type as supporting ‘concatenation’, typically strings.
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.