ormar-postgres-extensions

Overview

ormar-postgres-extensions is a an extension to theOrmar ORM. It enables developers to write models that map to native PostgreSQL types.

Motivation

Ormar is an amazing async ORM that works with FastAPI. However, it is agnostic to the underlying database used meaning that we cannot use native PostgreSQL types such as UUID or JSONB columns. The aim of this library is to provide Ormar fields that can be used to generate database columns with native PG types.

Installation

python -m pip install ormar-postgres-extensions

Usage

Fields

Three native PG fields are provided. The JSONB and UUID types map to native JSONB and UUID data types respectively. The Array type can be used to create an array column. Using these in an Ormar model is as simple as importing the fields and using them in the model.

UUID

from uuid import UUID

import ormar
import ormar_postgres_extensions as ormar_pg_ext


class MyModel(ormar.Model):
    uuid: UUID = ormar_pg_ext.UUID(unique=True, nullable=False)

JSONB

import ormar
import ormar_postgres_extensions as ormar_pg_ext

class JSONBTestModel(ormar.Model):
    id: int = ormar.Integer(primary_key=True)
    data: dict = ormar_pg_ext.JSONB()

jsonb_contained_by

The maps to the contains operator in Postgres.

await JSONBTestModel.objects.filter(data__jsonb_contained_by=dict(key="value")).all()

jsonb_contains

The maps to the contains operator in Postgres.

await JSONBTestModel.objects.filter(data__jsonb_contains=dict(key="value")).all()

jsonb_has_all

The maps to the has_all operator in Postgres.

from sqlalchemy.dialects.postgresql import array

await JSONBTestModel.objects.filter(data__jsonb_has_all=array(["key1", "key2"])).all()

jsonb_has_any

The maps to the has_any operator in Postgres.

from sqlalchemy.dialects.postgresql import array

await JSONBTestModel.objects.filter(data__jsonb_has_any=array(["key1", "key2"])).all()

jsonb_has_key

The maps to the has_key operator in Postgres.

await JSONBTestModel.objects.filter(data__jsonb_has_key="key1").all()

Array

Array field requires a bit more setup to pass the type of the array into the field

import ormar
import sqlalchemy
import ormar_postgres_extensions as ormar_pg_ext

class ModelWithArray(ormar.Model):
    class Meta:
        database = database
        metadata = metadata

    id: int = ormar.Integer(primary_key=True)
    data: list = ormar_pg_ext.ARRAY(item_type=sqlalchemy.String())

Arrays have access to three special methods that map to specific PostgreSQL array functions

array_contained_by

The maps to the contained_by operator in Postgres.

await ModelWithArray.objects.filter(data__array_contained_by=["a"]).all()

array_contains

The maps to the contains operator in Postgres.

await ModelWithArray.objects.filter(data__array_contains=["a"]).all()

array_overlap

The maps to the overlap operator in Postgres.

await ModelWithArray.objects.filter(data__array_overlap=["a"]).all()

INET / CIDR

from ipaddress import IPv4Address, IPv6Address, IPv4Interface, IPv6Interface
from typing import Union

import ormar
import ormar_postgres_extensions as ormar_pg_ext

IPAddress = Union[
    IPv4Address,
    IPv4Interface,
    IPv6Address,
    IPv6Interface,
]

class INETTestModel(ormar.Model):
    id: int = ormar.Integer(primary_key=True)
    inet: IPAddress = ormar_pg_ext.INET()
    cidr: IPAddress = ormar_pg_ext.CIDR()

contained_by

This maps to the << operator

from ipaddress import ip_interface
await INETTestModel.objects.filter(inet__contained_by=ip_interface("192.168.1.0/24")).all()

contained_by_eq

This maps to the <<= operator

from ipaddress import ip_interface
await INETTestModel.objects.filter(inet__contained_by_eq=ip_interface("192.168.1.0/24")).all()

contains_subnet

This maps to the >> operator

from ipaddress import ip_interface
await INETTestModel.objects.filter(inet__contains_subnet=ip_interface("192.168.1.0/24")).all()

contains_subnet_eq

This maps to the >>= operator

from ipaddress import ip_interface
await INETTestModel.objects.filter(inet__contains_subnet_eq=ip_interface("192.168.1.0/24")).all()

contains_or_eq

This maps to the && operator

from ipaddress import ip_interface
await INETTestModel.objects.filter(inet__contains_or_eq=ip_interface("192.168.1.0/24")).all()

MACADDR

from ipaddress import IPv4Address, IPv6Address, IPv4Interface, IPv6Interface
from typing import Union

import ormar
import ormar_postgres_extensions as ormar_pg_ext

class MacAddrTestModel(ormar.Model):
    id: int = ormar.Integer(primary_key=True)
    addr: str = ormar_pg_ext.MACADDR()

Uninstalling

pip uninstall ormar-postgres-extensions

Contributing

Feel free to open a PR or GitHub issue. Contributions welcome!

To develop locally, clone this repository and run . script/bootstrap to install test dependencies. You can then use invoke --list to see available commands. To run the tests locally, PostgreSQL needs to be running. This can be easily started via inv database.

See contributing guide

Contributors

You don't really have to add this section yourself! Simply use all-contributors by adding comments in your PRs like so:

Evert Timberg 🤔 🚇 🚧 📖 ⚠️

@all-contributors please add <username> for <contribution type>

Find out more about All-Contributors on their website!

License

ormar-postgres-extensions is licensed under Apache License Version 2.0.