https://github.com/spaceshaman/ormagic
Simple and lightweight ORM for Python, built on top of Pydantic.
https://github.com/spaceshaman/ormagic
database db fastapi orm postgres postgresql pydantic python sql sqlite sqlite3
Last synced: about 14 hours ago
JSON representation
Simple and lightweight ORM for Python, built on top of Pydantic.
- Host: GitHub
- URL: https://github.com/spaceshaman/ormagic
- Owner: SpaceShaman
- License: mit
- Created: 2024-07-20T17:17:10.000Z (over 1 year ago)
- Default Branch: master
- Last Pushed: 2025-01-12T09:56:07.000Z (about 1 year ago)
- Last Synced: 2025-09-28T23:02:03.038Z (4 months ago)
- Topics: database, db, fastapi, orm, postgres, postgresql, pydantic, python, sql, sqlite, sqlite3
- Language: Python
- Homepage: https://spaceshaman.github.io/ORMagic/
- Size: 1.02 MB
- Stars: 3
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
[](https://github.com/SpaceShaman/ORMagic?tab=MIT-1-ov-file)
[](https://github.com/SpaceShaman/ORMagic/blob/master/.github/workflows/tests.yml)
[](https://codecov.io/gh/SpaceShaman/ORMagic)
[](https://pypi.org/project/ORMagic)
[](https://pypi.org/project/ORMagic)
[](https://github.com/psf/black)
[](https://github.com/astral-sh/ruff)
[](https://docs.pydantic.dev)
[](https://www.sqlite.org)
[](https://www.postgresql.org)
[](https://docs.pytest.org/)
[](https://spaceshaman.github.io/ORMagic/)
The main goal of ORMagic is to provide a simple and easy-to-use ORM for [Python](https://www.python.org/), that is easy to understand and use, while still providing the necessary features to interact with a database.
Is based on the [Pydantic](https://docs.pydantic.dev) model and extends it with the ability to interact with [SQLite](https://www.sqlite.org) and [PostgreSQL](https://www.postgresql.org) databases.
## Simple example
```python
from ormagic import DBModel
class User(DBModel):
name: str
age: int
User.create_table()
User(name="John", age=30).save()
User.get(name="John")
>>> User(id=1, name='John', age=30)
```
You can find more examples and detailed documentation at [spaceshaman.github.io/ORMagic/](https://spaceshaman.github.io/ORMagic/)
## Installation
You can install ORMagic using pip:
```bash
pip install ORMagic
```
By default, ORMagic uses [SQLite](https://www.sqlite.org) as a database, so you don't need to install any additional dependencies.
But if you want to use another database, you need to install the appropriate database driver, for example,
for [PostgreSQL](https://www.postgresql.org) you need to install [psycopg2](https://github.com/psycopg/psycopg2), you can do it with the following command:
```bash
pip install ORMagic[postgres]
```
Additionally, to use a database other than [SQLite](https://www.sqlite.org), you need to set the `ORMAGIC_DATABASE_URL` environment,
more information about that you can find in the [documentation](https://spaceshaman.github.io/ORMagic/settings/).
## Documentation
The full documentation is available at [spaceshaman.github.io/ORMagic/](https://spaceshaman.github.io/ORMagic/)
## Features and Roadmap
- [x] Define table schema using Pydantic models
- [x] Basic CRUD operations
- [x] Save data to the database
- [x] Read data from the database
- [x] Update data in the database
- [x] Delete data from the database
- [x] Relationships between tables
- [x] One-to-many
- [x] Create a tables with a foreign key
- [x] Save data with a foreign key
- [x] Read data with a foreign key
- [x] Update data with a foreign key
- [x] Delete data with a foreign key
- [X] Cascade
- [x] Set null
- [x] Restrict
- [x] Set default
- [x] No action
- [x] One-to-one
- [x] Many-to-many
- [x] Unique constraints
- [x] Remove table
- [x] Read all data from the database
- [x] Filter data and retrieve multiple records
- [x] Equal
- [x] Not equal
- [x] Greater than
- [x] Greater than or equal
- [x] Less than
- [x] Less than or equal
- [x] Like (Pattern matching with % and _)
- [x] Not like (Pattern matching with % and _)
- [x] In (List of values)
- [x] Not in (List of values)
- [x] Between (Two values)
- [x] Not between (Two values)
- [x] Q objects to combine filters (AND, OR, NOT)
- [x] Protect against SQL injection
- [x] Order by
- [x] Limit and offset
- [x] Update table schema
- [x] Add new column
- [x] Rename column
- [x] Drop column
- [x] Custom primary key
- [x] Transactions
- [x] Integration with databases
- [x] SQLite
- [x] PostgreSQL
- [ ] MySQL
- [ ] Functions
- [ ] Aggregate functions
- [ ] String functions
- [ ] Date and time functions
- [ ] Mathematical functions
- [ ] Control flow functions
- [ ] Migrations
## Changelog
Changes for each release are thoroughly documented in [release notes](https://github.com/SpaceShaman/ORMagic/releases)
## Contributing
Contributions are welcome! Feel free to open an issue or submit a pull request.
I would like to keep the library to be safe as possible, so i would appreciate if you cover any new feature with tests to maintain 100% coverage.
### Install in a development environment
1. First, clone the repository:
```bash
git clone git@github.com:SpaceShaman/ORMagic.git
```
2. Install poetry if you don't have, here you can find the [instructions](https://python-poetry.org/docs/#installing-with-the-official-installer)
3. Create a virtual environment and install the dependencies:
```bash
cd ORMagic
poetry install --no-root
```
4. Activate the virtual environment:
```bash
poetry shell
```
### Run tests
If you in the virtual environment, you can run the tests with the following command:
```bash
pytest
```
You can also run the tests with coverage:
```bash
pytest --cov=ormagic
```
## License
This project is licensed under the terms of the [MIT license](https://github.com/SpaceShaman/ORMagic?tab=MIT-1-ov-file)