Fields

Fields let you customize the behavior of the Columns. They accept any parameter that regular Pydantic Fields do, plus a few extra parameters that are specific to your database.

GLOBALiceaxe.field.Field

Field

Create a new database field with optional database-specific configurations.

This function extends Pydantic's Field with additional database functionality. It accepts all standard Pydantic Field parameters plus all the database-specific parameters defined in DBFieldInfo.

Field = __get_db_field() 
Code
from iceaxe import Field
from iceaxe.base import TableBase

class User(TableBase):
    id: int = Field(primary_key=True)
    username: str = Field(unique=True, index=True)
    settings: dict = Field(is_json=True, default_factory=dict)
    department_id: int = Field(foreign_key="departments.id")
CLASSiceaxe.field.DBFieldInfo

DBFieldInfo

Extended field information for database fields, building upon Pydantic's FieldInfo. This class adds database-specific attributes and functionality for field configuration in SQL databases, particularly PostgreSQL.

This class is used internally by the Field constructor to store metadata about database columns, including constraints, foreign keys, and PostgreSQL-specific configurations.

Class Constructor

  • Name
    kwargs
    Type
    Unpack[DBFieldInputs]
    Description

    Default: {}

    Keyword arguments that configure the field's behavior. Includes all standard Pydantic field options plus database-specific options.

Class Attributes

  • Name
    primary_key
    Type
    bool
    Description

    Indicates if this field serves as the primary key for the table. When True, this field will be used as the unique identifier for rows.

  • Name
    autoincrement
    Type
    bool
    Description

    Controls whether the field should automatically increment. By default, this is True for primary key fields that have no default value set.

  • Name
    postgres_config
    Type
    PostgresFieldBase | None
    Description

    Custom PostgreSQL configuration for the field. Allows for type-specific customization of PostgreSQL parameters.

  • Name
    foreign_key
    Type
    str | None
    Description

    Specifies a foreign key relationship to another table. Format should be "table_name.column_name" if set.

  • Name
    unique
    Type
    bool
    Description

    When True, enforces that all values in this column must be unique. Creates a unique constraint in the database.

  • Name
    index
    Type
    bool
    Description

    When True, creates an index on this column to optimize query performance.

  • Name
    check_expression
    Type
    str | None
    Description

    SQL expression for a CHECK constraint on this column. Allows for custom validation rules at the database level.

  • Name
    is_json
    Type
    bool
    Description

    Indicates if this field should be stored as JSON in the database. When True, the field's value will be JSON serialized before storage.

Class Methods

  • Name
    extend_field
    Return type
    Description

    Helper function to extend a Pydantic FieldInfo with database-specific attributes.

  • Name
    to_db_value
    Return type
    Description

Postgres Types

Some primitives (like datetimes) allow for more configuration in Postgres than their types do in Python. In these cases we provide additional configuration classes that can be passed to postgres_config within the Field.

CLASSiceaxe.postgres.PostgresFieldBase

PostgresFieldBase

Extensions to python core types that specify addition arguments used by Postgres.

CLASSiceaxe.postgres.PostgresDateTime

PostgresDateTime

Extension to Python's datetime type that specifies additional Postgres-specific configuration. Used to customize the timezone behavior of datetime fields in Postgres.

Class Attributes

  • Name
    timezone
    Type
    bool
    Description

    Whether the datetime field should include timezone information in Postgres. If True, maps to TIMESTAMP WITH TIME ZONE. If False, maps to TIMESTAMP WITHOUT TIME ZONE. Defaults to False.

Code
from iceaxe import Field, TableBase
class Event(TableBase):
    id: int = Field(primary_key=True)
    created_at: datetime = Field(postgres_config=PostgresDateTime(timezone=True))
CLASSiceaxe.postgres.PostgresTime

PostgresTime

Extension to Python's time type that specifies additional Postgres-specific configuration. Used to customize the timezone behavior of time fields in Postgres.

Class Attributes

  • Name
    timezone
    Type
    bool
    Description

    Whether the time field should include timezone information in Postgres. If True, maps to TIME WITH TIME ZONE. If False, maps to TIME WITHOUT TIME ZONE. Defaults to False.

Code
from iceaxe import Field, TableBase
class Schedule(TableBase):
    id: int = Field(primary_key=True)
    start_time: time = Field(postgres_config=PostgresTime(timezone=True))