Vinyl, a django-based async orm

Warm greetings to all the django community! I want to present to you the vinyl orm, that is natively async and is very close to django in terms of API.

Why not a DEP

Yesterday I’ve posted a gist on how django can be made natively async, while preserving the compatibility of the synchronous version.

However, developing that idea as an enhancement to django doesn’t seem to me as the best practical solution. That’s because the main value of the project is it’s async version, the one that doesn’t have a counterpart in django, so is not bound by any compatibility requirements.

Speaking of compatibility, the proposed approach fundamentally builds sync and async version upon the same codebase, so the compatibility can’t be lost unless you want otherwise. To add more, I’m going to use the sync version to test the async one, so the sync version will be allways in pretty working state anyway.

Nevertheless, the async version will be the first to release. For the sync services, users can always use the traditional django, so there is no rush in releasing the sync version of vinyl.


Django’s lazy attributes for relations are fundamentally incompatible with async-await, so that part of django API should be adapted. My proposition is to keep the old syntax/API for the case when the related objects has been already prefetched. Otherwise you’ll have to use different syntax, like that:

await obj.R('related_object)

The async version will always be compatible with the sync version (and django) in terms of the models/fields and the corresponding entities in the database (tables, indexes, SQL)

Not django-specific

Vinyl will be a general-purpose orm, not bound to django. It will be able to be used with any web framework. Therefore it won’t require and the directory-based layout of files used in django.

The name of django application will be by default the last part of the package which model belongs to (and can be customized if, for example, that package has some special attribute). So, for the service.auth.accounts.models.User model the application will be called accounts.


Every sync driver in django database backends will have it’s async counterpart with the API close to the dbapi specification. In the case of postgresql I like psycopg3 more than asyncpg for that reason, but that still is to be decided.

Replacing django

If the project will be successful it will inevitably finally replace django (at least the django.db part of it) because it will provide both versions, sync and async, at the same time.


Vinyl will probably be the first natively async orm for python, compatible with existing django projects. I think big projects using django should be interested