Skip to content

API Reference

Database Constants

DatabaseConnectionType

Bases: Enum

Enum for database connection types.

Source code in src/supabase_pydantic/db/constants.py 
13
14
15
16
17
class DatabaseConnectionType(Enum):
    """Enum for database connection types."""

    LOCAL = 'local'
    DB_URL = 'db_url'

DatabaseUserDefinedType

Bases: str, Enum

Enum for database user defined types.

Source code in src/supabase_pydantic/db/constants.py 
20
21
22
23
24
25
26
class DatabaseUserDefinedType(str, Enum):
    """Enum for database user defined types."""

    DOMAIN = 'DOMAIN'
    COMPOSITE = 'COMPOSITE'
    ENUM = 'ENUM'
    RANGE = 'RANGE'

RelationType

Bases: str, Enum

Enum for relation types.

Source code in src/supabase_pydantic/db/constants.py 
 4
 5
 6
 7
 8
 9
10
class RelationType(str, Enum):
    """Enum for relation types."""

    ONE_TO_ONE = 'One-to-One'
    ONE_TO_MANY = 'One-to-Many'
    MANY_TO_MANY = 'Many-to-Many'
    MANY_TO_ONE = 'Many-to-One'  # When a table has a foreign key to another table (e.g., File -> Project)

Core Constants

FrameWorkType

Bases: Enum

Enum for framework types.

Source code in src/supabase_pydantic/core/constants.py 
11
12
13
14
class FrameWorkType(Enum):
    """Enum for framework types."""

    FASTAPI = 'fastapi'

OrmType

Bases: Enum

Enum for file types.

Source code in src/supabase_pydantic/core/constants.py 
4
5
6
7
8
class OrmType(Enum):
    """Enum for file types."""

    PYDANTIC = 'pydantic'
    SQLALCHEMY = 'sqlalchemy'

WriterClassType

Bases: Enum

Enum for writer class types.

Source code in src/supabase_pydantic/core/constants.py 
17
18
19
20
21
22
23
24
class WriterClassType(Enum):
    """Enum for writer class types."""

    BASE = 'base'  # The main Row model with all fields
    BASE_WITH_PARENT = 'base_with_parent'
    PARENT = 'parent'
    INSERT = 'insert'  # Model for insert operations - auto-generated fields optional
    UPDATE = 'update'  # Model for update operations - all fields optional

Utility Constants

AppConfig

Bases: TypedDict

Configuration for the Supabase Pydantic tool.

Source code in src/supabase_pydantic/utils/constants.py 
 4
 5
 6
 7
 8
 9
10
class AppConfig(TypedDict, total=False):
    """Configuration for the Supabase Pydantic tool."""

    default_directory: str
    overwrite_existing_files: bool
    nullify_base_schema: bool
    disable_model_prefix_protection: bool

ToolConfig

Bases: TypedDict

Configuration for the Supabase Pydantic tool.

Source code in src/supabase_pydantic/utils/constants.py 
13
14
15
16
class ToolConfig(TypedDict):
    """Configuration for the Supabase Pydantic tool."""

    supabase_pydantic: AppConfig

Database Models

ColumnInfo dataclass

Bases: AsDictParent

Column information.

Source code in src/supabase_pydantic/db/models.py 
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
@dataclass
class ColumnInfo(AsDictParent):
    """Column information."""

    name: str
    post_gres_datatype: str
    datatype: str
    user_defined_values: list[str] | None = field(default_factory=list)
    unique_partners: list[str] | None = field(default_factory=list)
    alias: str | None = None
    default: str | None = None
    max_length: int | None = None
    is_nullable: bool | None = True
    primary: bool = False
    is_unique: bool = False
    is_foreign_key: bool = False
    constraint_definition: str | None = None
    is_identity: bool = False  # For auto-generated identity columns
    enum_info: EnumInfo | None = None  # New field for enum metadata
    array_element_type: str | None = None  # Stores element type for array columns
    description: str | None = None  # Stores the description of the column

    def __str__(self) -> str:
        """Return a string representation of the column."""
        return f'ColumnInfo({self.name}, {self.post_gres_datatype})'

    @property
    def has_default(self) -> bool:
        """Check if the column has a default value."""
        return self.default is not None

    @property
    def is_generated(self) -> bool:
        """Check if the column is auto-generated (identity or serial)."""
        return self.is_identity or (self.default is not None and 'nextval' in str(self.default).lower())

    def orm_imports(self, orm_type: OrmType = OrmType.PYDANTIC) -> set[str | None]:
        """Get the unique import statements for a column."""
        imports = set()  # future proofing in case multiple imports are needed
        if orm_type == OrmType.SQLALCHEMY:
            i = get_sqlalchemy_type(self.post_gres_datatype, ('Any', 'from sqlalchemy import Column'))[1]
        else:
            i = get_pydantic_type(self.post_gres_datatype)[1]
        imports.add(i)
        return imports

    def orm_datatype(self, orm_type: OrmType = OrmType.PYDANTIC) -> str:
        """Get the datatype for a column."""
        if orm_type == OrmType.SQLALCHEMY:
            sql_datatype: str = get_sqlalchemy_type(self.post_gres_datatype)[0]
            return sql_datatype

        pydantic_datatype: str = get_pydantic_type(self.post_gres_datatype)[0]
        return pydantic_datatype

    def is_user_defined_type(self) -> bool:
        """Check if the column is a user-defined type."""
        return self.post_gres_datatype == 'USER-DEFINED'

    def nullable(self) -> bool:
        """Check if the column is nullable."""
        return self.is_nullable if self.is_nullable is not None else False

has_default property

Check if the column has a default value.

is_generated property

Check if the column is auto-generated (identity or serial).

__str__()

Return a string representation of the column.

Source code in src/supabase_pydantic/db/models.py 
121
122
123
def __str__(self) -> str:
    """Return a string representation of the column."""
    return f'ColumnInfo({self.name}, {self.post_gres_datatype})'

is_user_defined_type()

Check if the column is a user-defined type.

Source code in src/supabase_pydantic/db/models.py 
154
155
156
def is_user_defined_type(self) -> bool:
    """Check if the column is a user-defined type."""
    return self.post_gres_datatype == 'USER-DEFINED'

nullable()

Check if the column is nullable.

Source code in src/supabase_pydantic/db/models.py 
158
159
160
def nullable(self) -> bool:
    """Check if the column is nullable."""
    return self.is_nullable if self.is_nullable is not None else False

orm_datatype(orm_type=OrmType.PYDANTIC)

Get the datatype for a column.

Source code in src/supabase_pydantic/db/models.py 
145
146
147
148
149
150
151
152
def orm_datatype(self, orm_type: OrmType = OrmType.PYDANTIC) -> str:
    """Get the datatype for a column."""
    if orm_type == OrmType.SQLALCHEMY:
        sql_datatype: str = get_sqlalchemy_type(self.post_gres_datatype)[0]
        return sql_datatype

    pydantic_datatype: str = get_pydantic_type(self.post_gres_datatype)[0]
    return pydantic_datatype

orm_imports(orm_type=OrmType.PYDANTIC)

Get the unique import statements for a column.

Source code in src/supabase_pydantic/db/models.py 
135
136
137
138
139
140
141
142
143
def orm_imports(self, orm_type: OrmType = OrmType.PYDANTIC) -> set[str | None]:
    """Get the unique import statements for a column."""
    imports = set()  # future proofing in case multiple imports are needed
    if orm_type == OrmType.SQLALCHEMY:
        i = get_sqlalchemy_type(self.post_gres_datatype, ('Any', 'from sqlalchemy import Column'))[1]
    else:
        i = get_pydantic_type(self.post_gres_datatype)[1]
    imports.add(i)
    return imports

ConstraintInfo dataclass

Bases: AsDictParent

Source code in src/supabase_pydantic/db/models.py 
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
@dataclass
class ConstraintInfo(AsDictParent):
    constraint_name: str
    raw_constraint_type: str
    constraint_definition: str
    columns: list[str] = field(default_factory=list)

    def constraint_type(self) -> str:
        """Get the constraint type."""
        constraint_type: str = CONSTRAINT_TYPE_MAP.get(self.raw_constraint_type.lower(), 'OTHER')
        return constraint_type

    def __str__(self) -> str:
        """Return a string representation of the constraint."""
        return f'ConstraintInfo({self.constraint_name}, {self.constraint_type()})'

__str__()

Return a string representation of the constraint.

Source code in src/supabase_pydantic/db/models.py 
94
95
96
def __str__(self) -> str:
    """Return a string representation of the constraint."""
    return f'ConstraintInfo({self.constraint_name}, {self.constraint_type()})'

constraint_type()

Get the constraint type.

Source code in src/supabase_pydantic/db/models.py 
89
90
91
92
def constraint_type(self) -> str:
    """Get the constraint type."""
    constraint_type: str = CONSTRAINT_TYPE_MAP.get(self.raw_constraint_type.lower(), 'OTHER')
    return constraint_type

DatabaseConnectionParams

Bases: BaseModel

Base model for database connection parameters.

Source code in src/supabase_pydantic/db/models.py 
305
306
307
308
class DatabaseConnectionParams(BaseModel):
    """Base model for database connection parameters."""

    conn_type: str = Field(..., description="Connection type identifier (e.g., 'postgresql', 'mysql')")

DirectConnectionParams

Bases: DatabaseConnectionParams

Connection parameters for direct database connection.

Source code in src/supabase_pydantic/db/models.py 
311
312
313
314
315
316
317
318
class DirectConnectionParams(DatabaseConnectionParams):
    """Connection parameters for direct database connection."""

    dbname: str = Field(..., description='Database name')
    user: str = Field(..., description='Username for database connection')
    password: str = Field(..., description='Password for database connection')
    host: str = Field(..., description='Database host')
    port: str = Field(..., description='Database port')

MySQLConnectionParams

Bases: BaseModel

MySQL connection parameters.

Source code in src/supabase_pydantic/db/models.py 
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
class MySQLConnectionParams(BaseModel):
    """MySQL connection parameters."""

    db_url: str | None = None
    dbname: str | None = None
    user: str | None = None
    password: str | None = None
    host: str | None = None
    port: str | None = Field(default='3306', description='MySQL default port is 3306')

    @field_validator('port')
    def validate_port(cls, v: str | int | None) -> str | None:
        """Validate that port is a valid integer."""
        if v is not None:
            if isinstance(v, str):
                try:
                    return str(int(v))
                except ValueError:
                    raise ValueError('Port must be a valid number')
            # Convert int to str to ensure consistent return type
            elif isinstance(v, int):
                return str(v)
        return v

    def to_dict(self) -> dict[str, Any]:
        """Convert to dictionary, excluding None values."""
        # Handle both Pydantic v1 and v2 APIs
        if hasattr(self, 'model_dump'):
            # Pydantic v2
            return {k: v for k, v in self.model_dump().items() if v is not None}
        else:
            # Pydantic v1
            return {k: v for k, v in self.dict().items() if v is not None}

    def is_valid(self) -> bool:
        """Check if parameters are valid for connection."""
        if self.db_url is not None:
            return True
        return all([self.dbname, self.user, self.password, self.host, self.port])

    model_config = ConfigDict(extra='forbid')

is_valid()

Check if parameters are valid for connection.

Source code in src/supabase_pydantic/db/models.py 
420
421
422
423
424
def is_valid(self) -> bool:
    """Check if parameters are valid for connection."""
    if self.db_url is not None:
        return True
    return all([self.dbname, self.user, self.password, self.host, self.port])

to_dict()

Convert to dictionary, excluding None values.

Source code in src/supabase_pydantic/db/models.py 
410
411
412
413
414
415
416
417
418
def to_dict(self) -> dict[str, Any]:
    """Convert to dictionary, excluding None values."""
    # Handle both Pydantic v1 and v2 APIs
    if hasattr(self, 'model_dump'):
        # Pydantic v2
        return {k: v for k, v in self.model_dump().items() if v is not None}
    else:
        # Pydantic v1
        return {k: v for k, v in self.dict().items() if v is not None}

validate_port(v)

Validate that port is a valid integer.

Source code in src/supabase_pydantic/db/models.py 
396
397
398
399
400
401
402
403
404
405
406
407
408
@field_validator('port')
def validate_port(cls, v: str | int | None) -> str | None:
    """Validate that port is a valid integer."""
    if v is not None:
        if isinstance(v, str):
            try:
                return str(int(v))
            except ValueError:
                raise ValueError('Port must be a valid number')
        # Convert int to str to ensure consistent return type
        elif isinstance(v, int):
            return str(v)
    return v

PostgresConnectionParams

Bases: BaseModel

Connection parameters for PostgreSQL database.

Source code in src/supabase_pydantic/db/models.py 
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
class PostgresConnectionParams(BaseModel):
    """Connection parameters for PostgreSQL database."""

    # Either db_url or direct connection params must be provided
    dbname: str | None = Field(None, description='Database name')
    user: str | None = Field(None, description='Username for database connection')
    password: str | None = Field(None, description='Password for database connection')
    host: str | None = Field(None, description='Database host')
    port: str | None = Field(None, description='Database port')
    db_url: str | None = Field(
        None, description='Database connection URL in format: postgresql://username:password@host:port/database'
    )

    @field_validator('db_url')
    def validate_db_url(cls, v: str | None) -> str | None:
        """Validate db_url format."""
        if v is not None:
            # Basic validation that it starts with postgresql://
            if not v.startswith('postgresql://'):
                raise ValueError("PostgreSQL connection URL must start with 'postgresql://'")
        return v

    @field_validator('port')
    def validate_port(cls, v: str | int | None) -> str | None:
        """Validate port is numeric."""
        if v is not None:
            # Convert to int if it's a string
            if isinstance(v, str):
                try:
                    return str(int(v))
                except ValueError:
                    raise ValueError('Port must be a valid number')
            # Convert int to str to ensure consistent return type
            elif isinstance(v, int):
                return str(v)
        return v

    def to_dict(self) -> dict[str, Any]:
        """Convert to dictionary, excluding None values."""
        # Handle both Pydantic v1 and v2 APIs
        if hasattr(self, 'model_dump'):
            # Pydantic v2
            return {k: v for k, v in self.model_dump().items() if v is not None}
        else:
            # Pydantic v1
            return {k: v for k, v in self.dict().items() if v is not None}

    def is_valid(self) -> bool:
        """Check if parameters are valid for connection."""
        if self.db_url is not None:
            return True
        required_direct_params = [self.dbname, self.user, self.password, self.host, self.port]
        return all(param is not None for param in required_direct_params)

    model_config = ConfigDict(extra='forbid')

is_valid()

Check if parameters are valid for connection.

Source code in src/supabase_pydantic/db/models.py 
376
377
378
379
380
381
def is_valid(self) -> bool:
    """Check if parameters are valid for connection."""
    if self.db_url is not None:
        return True
    required_direct_params = [self.dbname, self.user, self.password, self.host, self.port]
    return all(param is not None for param in required_direct_params)

to_dict()

Convert to dictionary, excluding None values.

Source code in src/supabase_pydantic/db/models.py 
366
367
368
369
370
371
372
373
374
def to_dict(self) -> dict[str, Any]:
    """Convert to dictionary, excluding None values."""
    # Handle both Pydantic v1 and v2 APIs
    if hasattr(self, 'model_dump'):
        # Pydantic v2
        return {k: v for k, v in self.model_dump().items() if v is not None}
    else:
        # Pydantic v1
        return {k: v for k, v in self.dict().items() if v is not None}

validate_db_url(v)

Validate db_url format.

Source code in src/supabase_pydantic/db/models.py 
342
343
344
345
346
347
348
349
@field_validator('db_url')
def validate_db_url(cls, v: str | None) -> str | None:
    """Validate db_url format."""
    if v is not None:
        # Basic validation that it starts with postgresql://
        if not v.startswith('postgresql://'):
            raise ValueError("PostgreSQL connection URL must start with 'postgresql://'")
    return v

validate_port(v)

Validate port is numeric.

Source code in src/supabase_pydantic/db/models.py 
351
352
353
354
355
356
357
358
359
360
361
362
363
364
@field_validator('port')
def validate_port(cls, v: str | int | None) -> str | None:
    """Validate port is numeric."""
    if v is not None:
        # Convert to int if it's a string
        if isinstance(v, str):
            try:
                return str(int(v))
            except ValueError:
                raise ValueError('Port must be a valid number')
        # Convert int to str to ensure consistent return type
        elif isinstance(v, int):
            return str(v)
    return v

TableInfo dataclass

Bases: AsDictParent

Source code in src/supabase_pydantic/db/models.py 
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
@dataclass
class TableInfo(AsDictParent):
    name: str
    schema: str = 'public'
    table_type: Literal['BASE TABLE', 'VIEW'] = 'BASE TABLE'
    is_bridge: bool = False  # whether the table is a bridge table
    columns: list[ColumnInfo] = field(default_factory=list)
    foreign_keys: list[ForeignKeyInfo] = field(default_factory=list)
    constraints: list[ConstraintInfo] = field(default_factory=list)
    relationships: list[RelationshipInfo] = field(default_factory=list)
    generated_data: list[dict] = field(default_factory=list)

    def __str__(self) -> str:
        """Return a string representation of the table."""
        return f'TableInfo({self.schema}.{self.name})'

    def add_column(self, column: ColumnInfo) -> None:
        """Add a column to the table."""
        self.columns.append(column)

    def add_foreign_key(self, fk: ForeignKeyInfo) -> None:
        """Add a foreign key to the table."""
        self.foreign_keys.append(fk)

    def add_constraint(self, constraint: ConstraintInfo) -> None:
        """Add a constraint to the table."""
        self.constraints.append(constraint)

    def aliasing_in_columns(self) -> bool:
        """Check if any column within a table has an alias."""
        return any(bool(c.alias is not None) for c in self.columns)

    def table_dependencies(self) -> set[str]:
        """Get the table dependencies (foreign tables) for a table."""
        return set([fk.foreign_table_name for fk in self.foreign_keys])

    def primary_key(self) -> list[str]:
        """Get the primary key for a table."""
        if self.table_type == 'BASE TABLE':
            for constraint in self.constraints:
                if constraint.constraint_type() == 'PRIMARY KEY':
                    return constraint.columns
        return []  # Return an empty list if no primary key is found

    def primary_is_composite(self) -> bool:
        """Check if the primary key is composite."""
        return len(self.primary_key()) > 1

    def get_primary_columns(self, sort_results: bool = False) -> list[ColumnInfo]:
        """Get the primary columns for a table."""
        return self._get_columns(is_primary=True, sort_results=sort_results)

    def get_secondary_columns(self, sort_results: bool = False) -> list[ColumnInfo]:
        """Get the secondary columns for a table."""
        return self._get_columns(is_primary=False, sort_results=sort_results)

    def _get_columns(self, is_primary: bool = True, sort_results: bool = False) -> list[ColumnInfo]:
        """Private function to get the primary or secondary columns for a table."""
        if is_primary:
            res = [c for c in self.columns if c.name in self.primary_key()]
        else:
            res = [c for c in self.columns if c.name not in self.primary_key()]

        if sort_results:
            res.sort(key=lambda x: x.name)

        return res

    def sort_and_separate_columns(
        self, separate_nullable: bool = False, separate_primary_key: bool = False
    ) -> SortedColumns:
        """Sort and combine columns based on is_nullable attribute.

        Args:
            separate_nullable: Whether to separate nullable and non-nullable columns.
            separate_primary_key: Whether to separate primary key and secondary columns.

        Returns:
            A dictionary with keys, nullable, non_nullable, and remaining as keys
            and lists of ColumnInfo objects as values.
        """
        # result: dict[str, list[ColumnInfo]] = {'keys': [], 'nullable': [], 'non_nullable': [], 'remaining': []}
        result: SortedColumns = SortedColumns([], [], [], [])
        if separate_primary_key:
            result.primary_keys = self.get_primary_columns(sort_results=True)
            result.remaining = self.get_secondary_columns(sort_results=True)
        else:
            result.remaining = sorted(self.columns, key=lambda x: x.name)

        if separate_nullable:
            nullable_columns = [column for column in result.remaining if column.is_nullable]  # already sorted
            non_nullable_columns = [column for column in result.remaining if not column.is_nullable]

            # Combine them with non-nullable first
            result.nullable = nullable_columns
            result.non_nullable = non_nullable_columns
            result.remaining = []

        return result

    def has_unique_constraint(self) -> bool:
        """Check if the table has unique constraints."""
        return any(c.constraint_type() == 'UNIQUE' for c in self.constraints)

__str__()

Return a string representation of the table.

Source code in src/supabase_pydantic/db/models.py 
209
210
211
def __str__(self) -> str:
    """Return a string representation of the table."""
    return f'TableInfo({self.schema}.{self.name})'

add_column(column)

Add a column to the table.

Source code in src/supabase_pydantic/db/models.py 
213
214
215
def add_column(self, column: ColumnInfo) -> None:
    """Add a column to the table."""
    self.columns.append(column)

add_constraint(constraint)

Add a constraint to the table.

Source code in src/supabase_pydantic/db/models.py 
221
222
223
def add_constraint(self, constraint: ConstraintInfo) -> None:
    """Add a constraint to the table."""
    self.constraints.append(constraint)

add_foreign_key(fk)

Add a foreign key to the table.

Source code in src/supabase_pydantic/db/models.py 
217
218
219
def add_foreign_key(self, fk: ForeignKeyInfo) -> None:
    """Add a foreign key to the table."""
    self.foreign_keys.append(fk)

aliasing_in_columns()

Check if any column within a table has an alias.

Source code in src/supabase_pydantic/db/models.py 
225
226
227
def aliasing_in_columns(self) -> bool:
    """Check if any column within a table has an alias."""
    return any(bool(c.alias is not None) for c in self.columns)

get_primary_columns(sort_results=False)

Get the primary columns for a table.

Source code in src/supabase_pydantic/db/models.py 
245
246
247
def get_primary_columns(self, sort_results: bool = False) -> list[ColumnInfo]:
    """Get the primary columns for a table."""
    return self._get_columns(is_primary=True, sort_results=sort_results)

get_secondary_columns(sort_results=False)

Get the secondary columns for a table.

Source code in src/supabase_pydantic/db/models.py 
249
250
251
def get_secondary_columns(self, sort_results: bool = False) -> list[ColumnInfo]:
    """Get the secondary columns for a table."""
    return self._get_columns(is_primary=False, sort_results=sort_results)

has_unique_constraint()

Check if the table has unique constraints.

Source code in src/supabase_pydantic/db/models.py 
297
298
299
def has_unique_constraint(self) -> bool:
    """Check if the table has unique constraints."""
    return any(c.constraint_type() == 'UNIQUE' for c in self.constraints)

primary_is_composite()

Check if the primary key is composite.

Source code in src/supabase_pydantic/db/models.py 
241
242
243
def primary_is_composite(self) -> bool:
    """Check if the primary key is composite."""
    return len(self.primary_key()) > 1

primary_key()

Get the primary key for a table.

Source code in src/supabase_pydantic/db/models.py 
233
234
235
236
237
238
239
def primary_key(self) -> list[str]:
    """Get the primary key for a table."""
    if self.table_type == 'BASE TABLE':
        for constraint in self.constraints:
            if constraint.constraint_type() == 'PRIMARY KEY':
                return constraint.columns
    return []  # Return an empty list if no primary key is found

sort_and_separate_columns(separate_nullable=False, separate_primary_key=False)

Sort and combine columns based on is_nullable attribute.

Parameters:

Name Type Description Default
separate_nullable bool

Whether to separate nullable and non-nullable columns.

 False
separate_primary_key bool

Whether to separate primary key and secondary columns.

 False

Returns:

Type Description
SortedColumns

A dictionary with keys, nullable, non_nullable, and remaining as keys
SortedColumns

and lists of ColumnInfo objects as values.
Source code in src/supabase_pydantic/db/models.py 
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
def sort_and_separate_columns(
    self, separate_nullable: bool = False, separate_primary_key: bool = False
) -> SortedColumns:
    """Sort and combine columns based on is_nullable attribute.

    Args:
        separate_nullable: Whether to separate nullable and non-nullable columns.
        separate_primary_key: Whether to separate primary key and secondary columns.

    Returns:
        A dictionary with keys, nullable, non_nullable, and remaining as keys
        and lists of ColumnInfo objects as values.
    """
    # result: dict[str, list[ColumnInfo]] = {'keys': [], 'nullable': [], 'non_nullable': [], 'remaining': []}
    result: SortedColumns = SortedColumns([], [], [], [])
    if separate_primary_key:
        result.primary_keys = self.get_primary_columns(sort_results=True)
        result.remaining = self.get_secondary_columns(sort_results=True)
    else:
        result.remaining = sorted(self.columns, key=lambda x: x.name)

    if separate_nullable:
        nullable_columns = [column for column in result.remaining if column.is_nullable]  # already sorted
        non_nullable_columns = [column for column in result.remaining if not column.is_nullable]

        # Combine them with non-nullable first
        result.nullable = nullable_columns
        result.non_nullable = non_nullable_columns
        result.remaining = []

    return result

table_dependencies()

Get the table dependencies (foreign tables) for a table.

Source code in src/supabase_pydantic/db/models.py 
229
230
231
def table_dependencies(self) -> set[str]:
    """Get the table dependencies (foreign tables) for a table."""
    return set([fk.foreign_table_name for fk in self.foreign_keys])

URLConnectionParams

Bases: DatabaseConnectionParams

Connection parameters for URL-based database connection.

Source code in src/supabase_pydantic/db/models.py 
321
322
323
324
325
326
class URLConnectionParams(DatabaseConnectionParams):
    """Connection parameters for URL-based database connection."""

    db_url: str = Field(
        ..., description='Database connection URL in format: dialect://username:password@host:port/database'
    )

UserEnumType dataclass

Bases: AsDictParent

Source code in src/supabase_pydantic/db/models.py 
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
@dataclass
class UserEnumType(AsDictParent):
    type_name: str
    namespace: str
    owner: str
    category: str
    is_defined: bool
    type: str
    enum_values: list[str] = field(default_factory=list)

    def matches_type_name(self, type_name: str) -> bool:
        """Check if a given type name matches this enum type, handling PostgreSQL array naming conventions."""
        if not type_name:
            return False

        # Remove all leading underscores (PostgreSQL array types add underscores)
        clean_name = type_name
        while clean_name.startswith('_'):
            clean_name = clean_name[1:]

        # Remove array brackets if present
        if clean_name.endswith('[]'):
            clean_name = clean_name[:-2]

        # Remove quotes if present
        if clean_name.startswith('"') and clean_name.endswith('"'):
            clean_name = clean_name[1:-1]

        # Handle schema qualification (e.g., public.Fifth_Type)
        if '.' in clean_name:
            clean_name = clean_name.split('.')[-1]

        # PostgreSQL sometimes lowercases type names for arrays
        # Compare both lowercased and original
        return self.type_name.lower() == clean_name.lower()

matches_type_name(type_name)

Check if a given type name matches this enum type, handling PostgreSQL array naming conventions.

Source code in src/supabase_pydantic/db/models.py 
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
def matches_type_name(self, type_name: str) -> bool:
    """Check if a given type name matches this enum type, handling PostgreSQL array naming conventions."""
    if not type_name:
        return False

    # Remove all leading underscores (PostgreSQL array types add underscores)
    clean_name = type_name
    while clean_name.startswith('_'):
        clean_name = clean_name[1:]

    # Remove array brackets if present
    if clean_name.endswith('[]'):
        clean_name = clean_name[:-2]

    # Remove quotes if present
    if clean_name.startswith('"') and clean_name.endswith('"'):
        clean_name = clean_name[1:-1]

    # Handle schema qualification (e.g., public.Fifth_Type)
    if '.' in clean_name:
        clean_name = clean_name.split('.')[-1]

    # PostgreSQL sometimes lowercases type names for arrays
    # Compare both lowercased and original
    return self.type_name.lower() == clean_name.lower()

Core Models

EnumInfo dataclass

Source code in src/supabase_pydantic/core/models.py 
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
@dataclass
class EnumInfo:
    name: str  # The name of the enum type in the DB
    values: list[str]  # The possible values for the enum
    schema: str = 'public'  # The schema, defaulting to 'public'

    def python_class_name(self) -> str:
        """Converts DB enum name to PascalCase for Python class, prefixed by schema.

        Handles various input formats:
        - snake_case: 'order_status' -> 'OrderStatusEnum'
        - camelCase: 'thirdType' -> 'ThirdTypeEnum'
        - PascalCase: 'FourthType' -> 'FourthTypeEnum'
        - mixed: 'Fifth_Type' -> 'FifthTypeEnum'
        - with leading underscore: '_first_type' -> 'FirstTypeEnum'

        Final class name is prefixed by schema: 'public.order_status' -> 'PublicOrderStatusEnum'
        """
        # Handle empty name edge case
        if not self.name:
            return f'{self.schema.capitalize()}Enum'

        # Remove leading underscore if present (for PostgreSQL compatibility)
        clean_name = self.name
        if clean_name.startswith('_'):
            clean_name = clean_name[1:]

        # Special case: if the name is already PascalCase or camelCase without underscores
        if '_' not in clean_name and any(c.isupper() for c in clean_name):
            # Ensure first character is uppercase
            class_name = clean_name[0].upper() + clean_name[1:] + 'Enum'
        else:
            # Standard snake_case processing
            class_name = ''.join(word.capitalize() for word in clean_name.split('_')) + 'Enum'

        # Add schema prefix
        return f'{self.schema.capitalize()}{class_name}'

    def python_member_name(self, value: str) -> str:
        """Converts enum value to a valid Python identifier.

        e.g., 'pending_new' -> 'pending_new'
        """
        return value.lower()

python_class_name()

Converts DB enum name to PascalCase for Python class, prefixed by schema.

Handles various input formats: - snake_case: 'order_status' -> 'OrderStatusEnum' - camelCase: 'thirdType' -> 'ThirdTypeEnum' - PascalCase: 'FourthType' -> 'FourthTypeEnum' - mixed: 'Fifth_Type' -> 'FifthTypeEnum' - with leading underscore: '_first_type' -> 'FirstTypeEnum'

Final class name is prefixed by schema: 'public.order_status' -> 'PublicOrderStatusEnum'

Source code in src/supabase_pydantic/core/models.py 
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
def python_class_name(self) -> str:
    """Converts DB enum name to PascalCase for Python class, prefixed by schema.

    Handles various input formats:
    - snake_case: 'order_status' -> 'OrderStatusEnum'
    - camelCase: 'thirdType' -> 'ThirdTypeEnum'
    - PascalCase: 'FourthType' -> 'FourthTypeEnum'
    - mixed: 'Fifth_Type' -> 'FifthTypeEnum'
    - with leading underscore: '_first_type' -> 'FirstTypeEnum'

    Final class name is prefixed by schema: 'public.order_status' -> 'PublicOrderStatusEnum'
    """
    # Handle empty name edge case
    if not self.name:
        return f'{self.schema.capitalize()}Enum'

    # Remove leading underscore if present (for PostgreSQL compatibility)
    clean_name = self.name
    if clean_name.startswith('_'):
        clean_name = clean_name[1:]

    # Special case: if the name is already PascalCase or camelCase without underscores
    if '_' not in clean_name and any(c.isupper() for c in clean_name):
        # Ensure first character is uppercase
        class_name = clean_name[0].upper() + clean_name[1:] + 'Enum'
    else:
        # Standard snake_case processing
        class_name = ''.join(word.capitalize() for word in clean_name.split('_')) + 'Enum'

    # Add schema prefix
    return f'{self.schema.capitalize()}{class_name}'

python_member_name(value)

Converts enum value to a valid Python identifier.

e.g., 'pending_new' -> 'pending_new'

Source code in src/supabase_pydantic/core/models.py 
42
43
44
45
46
47
def python_member_name(self, value: str) -> str:
    """Converts enum value to a valid Python identifier.

    e.g., 'pending_new' -> 'pending_new'
    """
    return value.lower()

Writers

Serialization

AsDictParent dataclass

Source code in src/supabase_pydantic/utils/serialization.py 
 8
 9
10
11
12
13
14
15
@dataclass
class AsDictParent:
    def as_dict(self) -> dict[str, Any]:
        """Convert the dataclass instance to a dictionary."""
        return asdict(self)

    def __str__(self) -> str:
        return json.dumps(asdict(self), indent=4)

as_dict()

Convert the dataclass instance to a dictionary.

Source code in src/supabase_pydantic/utils/serialization.py 
10
11
12
def as_dict(self) -> dict[str, Any]:
    """Convert the dataclass instance to a dictionary."""
    return asdict(self)

CustomJsonEncoder

Bases: JSONEncoder

Custom JSON encoder for encoding decimal and datetime.

Source code in src/supabase_pydantic/utils/serialization.py 
18
19
20
21
22
23
24
25
26
27
class CustomJsonEncoder(json.JSONEncoder):
    """Custom JSON encoder for encoding decimal and datetime."""

    def default(self, o: object) -> Any:
        """Encode decimal and datetime objects."""
        if isinstance(o, decimal.Decimal):
            return str(o)
        elif isinstance(o, datetime | date):
            return o.isoformat()
        return super().default(o)

default(o)

Encode decimal and datetime objects.

Source code in src/supabase_pydantic/utils/serialization.py 
21
22
23
24
25
26
27
def default(self, o: object) -> Any:
    """Encode decimal and datetime objects."""
    if isinstance(o, decimal.Decimal):
        return str(o)
    elif isinstance(o, datetime | date):
        return o.isoformat()
    return super().default(o)