Иерархия типов¶

Типы данных «CamelCase»¶

Рудиментарные типы имеют имена «CamelCase», такие как String, Numeric, Integer и DateTime. Все непосредственные подклассы TypeEngine являются типами «CamelCase». Типы «CamelCase» в максимально возможной степени независимы от базы данных, что означает, что все они могут быть использованы на любом бэкенде базы данных, где они будут вести себя таким образом, который соответствует этому бэкенду, чтобы создать желаемое поведение.

Примером прямого типа данных «CamelCase» является String. На большинстве бэкендов использование этого типа данных в table specification будет соответствовать типу базы данных VARCHAR, используемому на целевом бэкенде, передавая строковые значения в базу данных и из нее, как в примере ниже:

from sqlalchemy import MetaData
from sqlalchemy import Table, Column, Integer, String

metadata_obj = MetaData()

user = Table(
    "user",
    metadata_obj,
    Column("user_name", String, primary_key=True),
    Column("email_address", String(60)),
)

При использовании определенного класса TypeEngine в определении Table или в общем выражении SQL, если аргументы не требуются, он может быть передан как сам класс, то есть без инстанцирования его с помощью (). Если аргументы необходимы, как, например, аргумент длины 60 в столбце "email_address" выше, тип может быть инстанцирован.

Другой тип данных «CamelCase», который выражает более специфическое для бэкенда поведение, - это тип данных Boolean. В отличие от String, который представляет строковый тип данных, который есть во всех базах данных, не каждый бэкенд имеет настоящий «булевый» тип данных; некоторые используют целые числа или BIT значения 0 и 1, некоторые имеют булевые литеральные константы true и false, а другие нет. Для этого типа данных Boolean может отображаться BOOLEAN на бэкенде, таком как PostgreSQL, BIT на бэкенде MySQL и SMALLINT на Oracle. Поскольку данные отправляются и принимаются из базы данных с использованием этого типа, в зависимости от используемого диалекта он может интерпретировать числовые или булевы значения Python.

Типичное приложение SQLAlchemy, скорее всего, захочет использовать в основном типы «CamelCase» в общем случае, поскольку они, как правило, обеспечивают наилучшее базовое поведение и автоматически переносятся на все бэкенды.

Ссылка на общий набор типов данных «CamelCase» находится ниже по ссылке Общие типы «CamelCase».

Типы данных «UPPERCASE»¶

В отличие от типов «CamelCase» существуют типы данных «UPPERCASE». Эти типы данных всегда наследуются от определенного типа данных «CamelCase» и всегда представляют собой точный тип данных. При использовании типа данных «UPPERCASE» имя типа всегда отображается в точности так, как оно задано, без учета того, поддерживает ли его текущий бэкенд. Поэтому использование типов «UPPERCASE» в приложении SQLAlchemy указывает на то, что требуются определенные типы данных, что подразумевает, что приложение обычно, без дополнительных шагов, будет ограничено теми бэкендами, которые используют тип именно так, как он задан. Примерами типов UPPERCASE являются VARCHAR, NUMERIC, INTEGER и TIMESTAMP, которые наследуются непосредственно от ранее упомянутых типов «CamelCase» String, Numeric, Integer и DateTime соответственно.

Типы данных «UPPERCASE», которые являются частью sqlalchemy.types, являются обычными типами SQL, которые обычно ожидаются доступными как минимум на двух бэкендах, если не больше.

Ссылка на общий набор типов данных «UPPERCASE» находится ниже в Стандартный SQL и типы «UPPERCASE» нескольких поставщиков.

Специфические для бэкенда типы данных «UPPERCASE»¶

Большинство баз данных также имеют свои собственные типы данных, которые либо полностью специфичны для этих баз данных, либо добавляют дополнительные аргументы, специфичные для этих баз данных. Для таких типов данных определенные диалекты SQLAlchemy предоставляют специфичные для бэкенда «UPPERCASE» типы данных, для типа SQL, который не имеет аналогов в других бэкендах. Примерами специфических для бэкенда прописных типов данных являются JSONB в PostgreSQL, IMAGE в SQL Server и TINYTEXT в MySQL.

Определенные бэкенды могут также включать типы данных «UPPERCASE», которые расширяют аргументы, доступные в том же типе данных «UPPERCASE», который находится в модуле sqlalchemy.types. Например, при создании строкового типа данных MySQL можно указать специфические для MySQL аргументы, такие как charset или national, которые доступны в MySQL версии VARCHAR в виде параметров VARCHAR.charset и VARCHAR.national, доступных только для MySQL.

Документация API для типов, специфичных для бэкенда, находится в документации для конкретного диалекта, перечисленной в Диалекты.

Использование «UPPERCASE» и типов, специфичных для бэкенда, для нескольких бэкендов¶

Рассмотрение наличия типов «UPPERCASE» и «CamelCase» приводит к естественному случаю использования типов данных «UPPERCASE» для опций, специфичных для бэкенда, но только когда этот бэкенд используется. Чтобы связать вместе системы «CamelCase», не зависящие от базы данных, и «UPPERCASE», специфичные для бэкенда, используется метод TypeEngine.with_variant(), чтобы составить типы вместе для работы с определенным поведением на конкретных бэкендах.

Например, для использования типа данных String, но при работе на MySQL, чтобы использовать параметр VARCHAR.charset из VARCHAR при создании таблицы на MySQL, TypeEngine.with_variant() может быть использован следующим образом:

from sqlalchemy import MetaData
from sqlalchemy import Table, Column, Integer, String
from sqlalchemy.dialects.mysql import VARCHAR

metadata_obj = MetaData()

user = Table(
    "user",
    metadata_obj,
    Column("user_name", String(100), primary_key=True),
    Column(
        "bio",
        String(255).with_variant(VARCHAR(255, charset="utf8"), "mysql"),
    ),
)

В приведенном выше определении таблицы столбец "bio" будет иметь строковое поведение на всех бэкендах. На большинстве бэкендов он будет отображаться в DDL как VARCHAR. Однако на MySQL (на это указывают URL базы данных, начинающиеся с mysql), он будет отображаться как VARCHAR(255) CHARACTER SET utf8.

Общие типы «CamelCase»¶

Общие типы задают столбец, который может читать, записывать и хранить определенный тип данных Python. SQLAlchemy при выпуске оператора CREATE TABLE выберет наилучший тип столбца базы данных, доступный в целевой базе данных. Для полного контроля над тем, какой тип столбца выдается в CREATE TABLE, например VARCHAR, смотрите Стандартный SQL и типы «UPPERCASE» нескольких поставщиков и другие разделы этой главы.

Стандартный SQL и типы «UPPERCASE» нескольких поставщиков¶

Эта категория типов относится к типам, которые либо являются частью стандарта SQL, либо потенциально встречаются в подмножестве бэкендов баз данных. В отличие от «общих» типов, типы стандарта SQL/мультипроизводителей не имеют нет гарантии работы на всех бэкендах, и будут работать только на тех бэкендах, которые явно поддерживают их по имени. То есть, тип всегда будет выдавать свое точное имя в DDL при выдаче CREATE TABLE.