https://github.com/piccolo-orm/piccolo
A fast, user friendly ORM and query builder which supports asyncio.
https://github.com/piccolo-orm/piccolo
asgi asyncio database fastapi hacktoberfest orm piccolo postgresql python python3 query-builder sqlite starlette
Last synced: 2 days ago
JSON representation
A fast, user friendly ORM and query builder which supports asyncio.
- Host: GitHub
- URL: https://github.com/piccolo-orm/piccolo
- Owner: piccolo-orm
- License: mit
- Created: 2018-10-27T20:53:26.000Z (over 7 years ago)
- Default Branch: master
- Last Pushed: 2026-01-12T18:19:24.000Z (about 1 month ago)
- Last Synced: 2026-01-29T17:36:06.062Z (14 days ago)
- Topics: asgi, asyncio, database, fastapi, hacktoberfest, orm, piccolo, postgresql, python, python3, query-builder, sqlite, starlette
- Language: Python
- Homepage: https://piccolo-orm.com/
- Size: 4.31 MB
- Stars: 1,853
- Watchers: 16
- Forks: 97
- Open Issues: 81
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGES.rst
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Security: SECURITY.md
Awesome Lists containing this project
- awesome-fastapi - Piccolo - An async ORM and query builder, supporting Postgres and SQLite, with batteries (migrations, security, etc). (Third-Party Extensions / Databases)
- awesome-fastapi - Piccolo - An async ORM and query builder, supporting Postgres and SQLite, with batteries (migrations, security, etc). (Third-Party Extensions / Databases)
- best-of-python - GitHub - 19% open · ⏱️ 29.10.2025): (Database Clients)
- awesome-litestar - Piccolo - An async ORM and query builder, supporting Postgres and SQLite, (Third-Party Extensions / Databases)
- awesome-pydantic - Piccolo - An async query builder and ORM, which can auto generate Pydantic models from database tables. (Object Mapping)
- awesome-asyncio - Piccolo - An ORM / query builder which can work in async and sync modes, with a nice admin GUI, and ASGI middleware. (Database Drivers)
README
[](https://piccolo-orm.readthedocs.io/en/latest/?badge=latest)
[](https://pypi.org/project/piccolo/)
[](https://codecov.io/gh/piccolo-orm/piccolo)
Piccolo is a fast, user friendly ORM and query builder which supports asyncio. [Read the docs](https://piccolo-orm.readthedocs.io/en/latest/).
## Features
Some of it’s stand out features are:
- Support for sync and async.
- A builtin playground, which makes learning a breeze.
- Tab completion support - works great with iPython and VSCode.
- Batteries included - a User model, authentication, migrations, an [admin GUI](https://github.com/piccolo-orm/piccolo_admin), and more.
- Modern Python - fully type annotated.
- Make your codebase modular and scalable with Piccolo apps (similar to Django apps).
## Syntax
The syntax is clean and expressive.
You can use it as a query builder:
```python
# Select:
await Band.select(
Band.name
).where(
Band.popularity > 100
)
# Join:
await Band.select(
Band.name,
Band.manager.name
)
# Delete:
await Band.delete().where(
Band.popularity < 1000
)
# Update:
await Band.update({Band.popularity: 10000}).where(
Band.name == 'Pythonistas'
)
```
Or like a typical ORM:
```python
# To create a new object:
b = Band(name='C-Sharps', popularity=100)
await b.save()
# To fetch an object from the database, and update it:
b = await Band.objects().get(Band.name == 'Pythonistas')
b.popularity = 10000
await b.save()
# To delete:
await b.remove()
```
## Installation
Installing with PostgreSQL driver:
```bash
pip install 'piccolo[postgres]'
```
Installing with SQLite driver:
```bash
pip install 'piccolo[sqlite]'
```
Installing with all optional dependencies (easiest):
```bash
pip install 'piccolo[all]'
```
## Building a web app?
Let Piccolo scaffold you an ASGI web app, using Piccolo as the ORM:
```bash
piccolo asgi new
```
[Starlette](https://www.starlette.io/), [FastAPI](https://fastapi.tiangolo.com/), [BlackSheep](https://www.neoteroi.dev/blacksheep/), [Litestar](https://litestar.dev/), [Ravyn](https://www.ravyn.dev/), [Lilya](https://lilya.dev/), [Quart](https://quart.palletsprojects.com/en/latest/), [Falcon](https://falconframework.org/) and [Sanic](https://sanic.dev/en/) are currently supported.
## Piccolo ecosystem
### Piccolo Admin
Piccolo Admin is a powerful admin interface / content management system for Python, built on top of Piccolo.
It was created at a design agency to serve the needs of customers who demand a high quality, beautiful admin interface for their websites. It's a modern alternative to tools like Wordpress and Django Admin.
It's built using the latest technologies, with Vue.js on the front end, and a powerful REST backend.
Some of it's standout features:
* Powerful data filtering
* Builtin security
* Multi-factor Authentication
* Media support, both locally and in S3 compatible services
* Dark mode support
* CSV exports
* Easily create custom forms
* Works on mobile and desktop
* Use standalone, or integrate with several supported ASGI frameworks
* Multilingual out of box
* Bulk actions, like updating and deleting data
* Flexible UI - only show the columns you want your users to see
You can read the docs [here](https://piccolo-admin.readthedocs.io/en/latest/).
### Piccolo API
Utilities for easily exposing [Piccolo](https://piccolo-orm.readthedocs.io/en/latest/) tables as REST endpoints in ASGI apps, such as [Starlette](https://www.starlette.io) and [FastAPI](https://fastapi.tiangolo.com/).
Includes a bunch of useful ASGI middleware:
- Session Auth
- Token Auth
- Rate Limiting
- CSRF
- Content Security Policy (CSP)
- And more
You can read the docs [here](https://piccolo-api.readthedocs.io/en/latest/).
## Are you a Django user?
We have a handy page which shows the equivalent of [common Django queries in Piccolo](https://piccolo-orm.readthedocs.io/en/latest/piccolo/query_types/django_comparison.html).
## Documentation
Our documentation is on [Read the docs](https://piccolo-orm.readthedocs.io/en/latest/piccolo/getting_started/index.html).
We also have some great [tutorial videos on YouTube](https://www.youtube.com/channel/UCE7x5nm1Iy9KDfXPNrNQ5lA).