plain.models 0.40.0

Model your data and store it in a database.

plain.models

Model your data and store it in a database.

• Overview
• Database connection
• Querying
• Migrations
• Fields
• Validation
• Indexes and constraints
• Managers
• Forms
• Sharing fields across models
• Installation

Overview

# app/users/models.py
from plain import models
from plain.passwords.models import PasswordField


@models.register_model
class User(models.Model):
    email = models.EmailField()
    password = PasswordField()
    is_admin = models.BooleanField(default=False)
    created_at = models.DateTimeField(auto_now_add=True)

    def __str__(self):
        return self.email

Every model automatically includes an id field which serves as the primary key. The name id is reserved and can't be used for other fields.

Create, update, and delete instances of your models:

from .models import User


# Create a new user
user = User.objects.create(
    email="[e-mail]",
    password="password",
)

# Update a user
user.email = "[e-mail]"
user.save()

# Delete a user
user.delete()

# Query for users
admin_users = User.objects.filter(is_admin=True)

Database connection

To connect to a database, you can provide a DATABASE_URL environment variable:

DATABASE_URL=postgresql://user:password@localhost:5432/dbname

Or you can manually define the DATABASE setting:

# app/settings.py
DATABASE = {
    "ENGINE": "plain.models.backends.postgresql",
    "NAME": "dbname",
    "USER": "user",
    "PASSWORD": "password",
    "HOST": "localhost",
    "PORT": "5432",
}

Multiple backends are supported, including Postgres, MySQL, and SQLite.

Querying

Models come with a powerful query API through their Manager interface:

# Get all users
all_users = User.objects.all()

# Filter users
admin_users = User.objects.filter(is_admin=True)
recent_users = User.objects.filter(created_at__gte=datetime.now() - timedelta(days=7))

# Get a single user
user = User.objects.get(email="[e-mail]")

# Complex queries with Q objects
from plain.models import Q
users = User.objects.filter(
    Q(is_admin=True) | Q(email__endswith="@example.com")
)

# Ordering
users = User.objects.order_by("-created_at")

# Limiting results
first_10_users = User.objects.all()[:10]

For more advanced querying options, see the QuerySet class.

Migrations

Migrations track changes to your models and update the database schema accordingly:

# Create migrations for model changes
plain makemigrations

# Apply migrations to the database
plain migrate

# See migration status
plain models show-migrations

Migrations are Python files that describe database schema changes. They're stored in your app's migrations/ directory.

Fields

Plain provides many field types for different data:

from plain import models

class Product(models.Model):
    # Text fields
    name = models.CharField(max_length=200)
    description = models.TextField()

    # Numeric fields
    price = models.DecimalField(max_digits=10, decimal_places=2)
    quantity = models.IntegerField(default=0)

    # Boolean fields
    is_active = models.BooleanField(default=True)

    # Date and time fields
    created_at = models.DateTimeField(auto_now_add=True)
    updated_at = models.DateTimeField(auto_now=True)

    # Relationships
    category = models.ForeignKey("Category", on_delete=models.CASCADE)
    tags = models.ManyToManyField("Tag")

Common field types include:

• CharField
• TextField
• IntegerField
• DecimalField
• BooleanField
• DateTimeField
• EmailField
• URLField
• UUIDField

Validation

Models can be validated before saving:

class User(models.Model):
    email = models.EmailField(unique=True)
    age = models.IntegerField()

    def clean(self):
        if self.age < 18:
            raise ValidationError("User must be 18 or older")

    def save(self, *args, **kwargs):
        self.full_clean()  # Runs validation
        super().save(*args, **kwargs)

Field-level validation happens automatically based on field types and constraints.

Indexes and constraints

Optimize queries and ensure data integrity with indexes and constraints:

class User(models.Model):
    email = models.EmailField()
    username = models.CharField(max_length=150)
    age = models.IntegerField()

    class Meta:
        indexes = [
            models.Index(fields=["email"]),
            models.Index(fields=["-created_at"], name="user_created_idx"),
        ]
        constraints = [
            models.UniqueConstraint(fields=["email", "username"], name="unique_user"),
            models.CheckConstraint(check=models.Q(age__gte=0), name="age_positive"),
        ]

Managers

Manager objects provide the interface for querying models:

class PublishedManager(models.Manager):
    def get_queryset(self):
        return super().get_queryset().filter(status="published")

class Article(models.Model):
    title = models.CharField(max_length=200)
    status = models.CharField(max_length=20)

    # Default manager
    objects = models.Manager()

    # Custom manager
    published = PublishedManager()

# Usage
all_articles = Article.objects.all()
published_articles = Article.published.all()

Forms

Models integrate with Plain's form system:

from plain import forms
from .models import User

class UserForm(forms.ModelForm):
    class Meta:
        model = User
        fields = ["email", "is_admin"]

# Usage
form = UserForm(data=request.data)
if form.is_valid():
    user = form.save()

Sharing fields across models

To share common fields across multiple models, use Python classes as mixins. The final, registered model must inherit directly from models.Model and the mixins should not.

from plain import models


# Regular Python class for shared fields
class TimestampedMixin:
    created_at = models.DateTimeField(auto_now_add=True)
    updated_at = models.DateTimeField(auto_now=True)


# Models inherit from the mixin AND models.Model
@models.register_model
class User(TimestampedMixin, models.Model):
    email = models.EmailField()
    password = PasswordField()
    is_admin = models.BooleanField(default=False)


@models.register_model
class Note(TimestampedMixin, models.Model):
    content = models.TextField(max_length=1024)
    liked = models.BooleanField(default=False)

Installation

Install the plain.models package from PyPI:

uv add plain.models

Then add to your INSTALLED_PACKAGES:

# app/settings.py
INSTALLED_PACKAGES = [
    ...
    "plain.models",
]