Skip to content

Quick Start

This guide will get you up and running with Oxyde from scratch.

1. Install Oxyde

pip install oxyde

2. Project Structure

myproject/
├── models.py          # Your OxydeModel classes
├── oxyde_config.py    # Generated by oxyde init
├── migrations/        # Generated migration files
└── main.py            # Your application

3. Initialize Configuration

Run the interactive setup:

oxyde init

You'll be prompted for:

  • Models module(s) — Python modules with your models (e.g., models)
  • Dialect — Database type: postgres, sqlite, or mysql
  • Database URL — Connection string (e.g., sqlite:///app.db)
  • Migrations directory — Where to store migrations (default: migrations)

This creates oxyde_config.py:

"""Oxyde ORM configuration."""

MODELS = ["models"]
DIALECT = "sqlite"
MIGRATIONS_DIR = "migrations"
DATABASES = {
    "default": "sqlite:///app.db",
}

SQLite paths

SQLite relative paths are resolved from the current working directory. For portable projects, see SQLite File Paths.

4. Define Models

Create models.py:

from oxyde import OxydeModel, Field

class User(OxydeModel):
    id: int | None = Field(default=None, db_pk=True)
    name: str
    email: str = Field(db_unique=True)
    age: int | None = Field(default=None)

    class Meta:
        is_table = True
        table_name = "users"

Key points:

  • Inherit from OxydeModel
  • Set is_table = True in Meta class
  • Use Field() for database constraints
  • db_pk=True marks the primary key
  • db_unique=True creates a UNIQUE constraint

5. Create and Apply Migrations

Generate migration from your models:

oxyde makemigrations

Output: 

📦 Loading models from: ['models']
✅ Created migration: migrations/0001_initial.py

Apply the migration to create tables:

oxyde migrate

Output: 

📦 Loading models from: ['models']
🔄 Applying 0001_initial... ✅

6. Write Your Application

Create main.py:

import asyncio
from oxyde import db
from models import User

async def main():
    # Connect using config from oxyde_config.py
    await db.init(default="sqlite:///app.db")

    # Create
    alice = await User.objects.create(
        name="Alice",
        email="alice@example.com",
        age=30
    )
    print(f"Created user: {alice.name} (id={alice.id})")

    # Read
    users = await User.objects.filter(age__gte=25).all()
    print(f"Found {len(users)} users aged 25+")

    # Update
    alice.age = 31
    await alice.save()

    # Delete
    await alice.delete()

    # Close connection
    await db.close()

if __name__ == "__main__":
    asyncio.run(main())

Run it:

python main.py

CRUD Operations Reference

Create

# Via manager
user = await User.objects.create(name="Alice", email="alice@example.com")

# Via instance
user = User(name="Bob", email="bob@example.com")
await user.save()

Read

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

# Get by ID (raises NotFoundError if not found)
user = await User.objects.get(id=1)

# Get or None
user = await User.objects.get_or_none(id=999)

# Filter
adults = await User.objects.filter(age__gte=18).all()

# First/Last
first = await User.objects.first()
last = await User.objects.last()

Update

# Via instance
user = await User.objects.get(id=1)
user.name = "Alice Smith"
await user.save()

# Bulk update (returns updated rows)
rows = await User.objects.filter(age__lt=18).update(status="minor")

Delete

# Via instance
user = await User.objects.get(id=1)
await user.delete()

# Bulk delete
count = await User.objects.filter(status="inactive").delete()

Next Steps