nexorm 0.1.0

A minimal Django-style ORM for SQLite applications.

NexORM

A minimal Python ORM for SQLite apps with models, query helpers, transactions, migrations, and named database connections.

Installation

pip install nexorm

For local development:

python -m pip install -e ".[dev]"

Quick Start

Initialize NexORM in your project:

nexorm init

This creates a local manage.py file and a migrations/ directory:

manage.py
migrations/

After that, you can use NexORM through python manage.py, similar to Django.

Define models in your app, for example app/models.py:

from nexorm import ForeignKey, IntegerField, Model, StringField


class User(Model):
    id = IntegerField(primary_key=True, auto_increment=True)
    username = StringField(max_length=100, unique=True, index=True)

    class Meta:
        table_name = "users"


class Post(Model):
    id = IntegerField(primary_key=True, auto_increment=True)
    title = StringField(max_length=200)
    user_id = ForeignKey("User", on_delete="CASCADE", related_name="posts")

    class Meta:
        table_name = "posts"

Generate and apply migrations:

python manage.py makemigrations
python manage.py migrate
python manage.py showmigrations
python manage.py rollback
python manage.py sqlmigrate 0001_create_table_users.py

By default, manage.py uses db.sqlite3 and imports models from app.models. You can override both:

python manage.py --database local.sqlite3 --models myproject.models makemigrations
python manage.py --database local.sqlite3 --models myproject.models migrate

Use the ORM:

from nexorm import configure, transaction
from app.models import Post, User

configure("db.sqlite3")

user = User.objects.create(username="admin")
post = Post.objects.create(title="Hello", user_id=user.id)

same_user = User.objects.filter(username__contains="adm").first()
recent_posts = user.posts.order_by("-id").limit(10).all()

with transaction.atomic():
    User.objects.create(username="vicky")

Use raw SQL only with parameters:

user = User.objects.raw("SELECT * FROM users WHERE id = ?", [1]).first()

Use with Flask:

from flask import Flask
from nexorm import configure


def create_app():
    configure("db.sqlite3")
    app = Flask(__name__)
    return app

Models

Define models by subclassing Model and assigning field instances. If a model does not define a primary key, NexORM adds an auto-incrementing id field.

from nexorm import BooleanField, DateTimeField, IntegerField, Model, StringField


class Article(Model):
    title = StringField(max_length=180)
    views = IntegerField(default=0)
    published = BooleanField(default=False)
    created_at = DateTimeField(nullable=True)

Queries

Post.objects.create(title="First post", user_id=1)

posts = Post.objects.filter(title__contains="First").order_by("-id").limit(10).all()
count = Post.objects.filter(user_id=1).count()
exists = Post.objects.filter(title="First post").exists()

Supported lookup suffixes include exact matching and common comparisons such as gt, gte, lt, lte, contains, startswith, endswith, and in.

Multiple Databases

Configure the default connection:

from nexorm import configure

configure("db.sqlite3")

Configure named connections:

from nexorm import configure, transaction
from app.models import User

configure("db.sqlite3")
configure("analytics.sqlite3", alias="analytics")

admin = User.objects.create(username="admin")
report_user = User.objects.using("analytics").create(username="report")

analytics_users = User.objects.using("analytics").filter(username__contains="rep").all()

with transaction.atomic("analytics"):
    User.objects.using("analytics").create(username="worker")

You can also pass a Database instance directly to using(...) or transaction.atomic(...).

Transactions

from nexorm import transaction


with transaction.atomic():
    Post.objects.create(title="Inside a transaction", user_id=1)

Nested transactions use SQLite savepoints.

Migrations CLI

Initialize a project:

nexorm init

That command creates this local manage.py file:

from nexorm.cli import main


if __name__ == "__main__":
    main()

Generate and apply migrations:

python manage.py makemigrations
python manage.py migrate
python manage.py showmigrations

Other commands:

python manage.py rollback
python manage.py sqlmigrate 0001_initial.py
python manage.py dbshell

You can still use the installed nexorm command directly:

nexorm --database app.sqlite3 --models app.models makemigrations
nexorm --database app.sqlite3 --models app.models migrate

Build

python -m pip install --upgrade build twine
python -m build
python -m twine check dist/*

Publish to PyPI

Create an API token in PyPI, then upload manually:

python -m twine upload dist/*

When prompted:

username: __token__
password: pypi-...

Use TestPyPI first if you want a dry run:

python -m twine upload --repository testpypi dist/*

Status

NexORM is an early package. The current implementation focuses on SQLite and keeps the public API small: model fields, managers/querysets, raw queries, transactions, named connections, and file-based migrations.