[](https://pypi.python.org/pypi/django-sqlfun/)
[](https://pypi.python.org/pypi/django-sqlfun/)
[](https://pypi.python.org/pypi/django-sqlfun/)
[](https://github.com/radusuciu/django-sqlfun/releases/)
# Django SQL Fun
Django SQLFun allows you to define and manage custom SQL functions in code. When you change the function definitions and call `makemigrations`, it will generate migrations for any functions that have been added, removed, or changed. These function classes can also be used in Django querysets since the `SqlFun` class inherits from [`django.db.models.expressions.Func`](https://docs.djangoproject.com/en/5.0/ref/models/expressions/#func-expressions).
**Note**: I'm still developing this so there may be some rough edges. Breaking changes may happen.
## Installation
1. Install using your favorite python package manager, eg. `pip install django-sqlfun`.
2. Add `sqlfun` to `INSTALLED_APPS` in your django settings
3. Run `manage.py migrate`. This will set up any tables required by `sqlfun` to keep track of your custom funcitons
## Use
1. Define a custom function in a module that gets imported on project load (eg. `models.py`). See below for example, or the [`test_project`](tests/test_project).
2. Run `manage.py makemigrations`
3. Run `manage.py migrate`
### Example
Define a custom function in your `models.py`:
```python
# models.py
from sqlfun import SqlFun
from django.db.models import IntegerField
class BadSum(SqlFun):
"""Almost returns the sum of two numbers."""
app_label = 'test_project' # [optional] if omitted, sqlfun will atempt to auto-resolve it
sql = """
CREATE OR REPLACE FUNCTION bad_sum(
first integer,
second integer
) RETURNS integer as $$
SELECT first + second + 1;
$$
LANGUAGE sql
stable;
"""
output_field = IntegerField()
```
Then run `manage.py makemigrations` and `manage.py migrate` and you should be good to go. You can use it in SQL: `SELECT bad_sum(2, 2)`, or in a Python queryset like so: `MyModel.objects.annotate(foo=BadSum(Value(2), Value(2)))`.
### Notes
- SQL functions are normalized, so changes in white-space should not result in changes being detected
- the `--dry-run` and `--name` options of `makemigrations` are respected
## Development
These instructions assume a recent Ubuntu/Debian environment.
1. Clone the repository
2. If needed, install `python3-venv` and `python3-pip` packages
3. Create a virtual environment `python3 -m venv .venv`
4. Install `libpq-dev` package since `psycopg2` depends on it.
5. Install `pdm`: `pip3 install --user pdm`
6. Install dev dependencies with `pdm install --dev`
Testing also requires a recent install of docker which is used to spin up a test postgres instance.
## Credits
This project is inspired by two great projects: [`django-pgtrigger`](https://github.com/Opus10/django-pgtrigger) and [`django-pgviews`](https://github.com/mypebble/django-pgviews).
Raw data
{
"_id": null,
"home_page": "",
"name": "django-sqlfun",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": "",
"keywords": "django,database,sql-functions,custom-sql",
"author": "Radu Suciu",
"author_email": "",
"download_url": "https://files.pythonhosted.org/packages/33/47/147301cff849775919562a38f18b3392a450e863e9dcaf923451452982a0/django-sqlfun-0.0.7.tar.gz",
"platform": null,
"description": "[](https://pypi.python.org/pypi/django-sqlfun/)\n[](https://pypi.python.org/pypi/django-sqlfun/)\n[](https://pypi.python.org/pypi/django-sqlfun/)\n[](https://github.com/radusuciu/django-sqlfun/releases/)\n\n# Django SQL Fun\n\nDjango SQLFun allows you to define and manage custom SQL functions in code. When you change the function definitions and call `makemigrations`, it will generate migrations for any functions that have been added, removed, or changed. These function classes can also be used in Django querysets since the `SqlFun` class inherits from [`django.db.models.expressions.Func`](https://docs.djangoproject.com/en/5.0/ref/models/expressions/#func-expressions).\n\n**Note**: I'm still developing this so there may be some rough edges. Breaking changes may happen.\n\n## Installation\n\n1. Install using your favorite python package manager, eg. `pip install django-sqlfun`.\n2. Add `sqlfun` to `INSTALLED_APPS` in your django settings\n3. Run `manage.py migrate`. This will set up any tables required by `sqlfun` to keep track of your custom funcitons\n\n## Use\n\n1. Define a custom function in a module that gets imported on project load (eg. `models.py`). See below for example, or the [`test_project`](tests/test_project).\n2. Run `manage.py makemigrations`\n3. Run `manage.py migrate`\n\n### Example\n\nDefine a custom function in your `models.py`:\n\n```python\n# models.py\nfrom sqlfun import SqlFun\nfrom django.db.models import IntegerField\n\nclass BadSum(SqlFun):\n \"\"\"Almost returns the sum of two numbers.\"\"\"\n \n app_label = 'test_project' # [optional] if omitted, sqlfun will atempt to auto-resolve it\n sql = \"\"\"\n CREATE OR REPLACE FUNCTION bad_sum(\n first integer,\n second integer\n ) RETURNS integer as $$\n SELECT first + second + 1;\n $$\n LANGUAGE sql\n stable;\n \"\"\"\n output_field = IntegerField()\n```\n\nThen run `manage.py makemigrations` and `manage.py migrate` and you should be good to go. You can use it in SQL: `SELECT bad_sum(2, 2)`, or in a Python queryset like so: `MyModel.objects.annotate(foo=BadSum(Value(2), Value(2)))`.\n\n### Notes\n\n- SQL functions are normalized, so changes in white-space should not result in changes being detected\n- the `--dry-run` and `--name` options of `makemigrations` are respected\n\n## Development\n\nThese instructions assume a recent Ubuntu/Debian environment.\n\n1. Clone the repository\n2. If needed, install `python3-venv` and `python3-pip` packages\n3. Create a virtual environment `python3 -m venv .venv`\n4. Install `libpq-dev` package since `psycopg2` depends on it.\n5. Install `pdm`: `pip3 install --user pdm`\n6. Install dev dependencies with `pdm install --dev`\n\nTesting also requires a recent install of docker which is used to spin up a test postgres instance.\n\n## Credits\n\nThis project is inspired by two great projects: [`django-pgtrigger`](https://github.com/Opus10/django-pgtrigger) and [`django-pgviews`](https://github.com/mypebble/django-pgviews).\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Django app that lets you define custom SQL functions",
"version": "0.0.7",
"project_urls": null,
"split_keywords": [
"django",
"database",
"sql-functions",
"custom-sql"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "18138641b39eb3e4e45c97887aec25085d7e65803f8dfc43c2439ec7360befc5",
"md5": "a0d4662f8a06e95b3a93ab6876fafdc6",
"sha256": "c774703d1e50a11e5a960becf7b90f0b49d79358c928069d46672a7afe84b120"
},
"downloads": -1,
"filename": "django_sqlfun-0.0.7-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a0d4662f8a06e95b3a93ab6876fafdc6",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 8548,
"upload_time": "2024-02-28T23:31:25",
"upload_time_iso_8601": "2024-02-28T23:31:25.010972Z",
"url": "https://files.pythonhosted.org/packages/18/13/8641b39eb3e4e45c97887aec25085d7e65803f8dfc43c2439ec7360befc5/django_sqlfun-0.0.7-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "3347147301cff849775919562a38f18b3392a450e863e9dcaf923451452982a0",
"md5": "e6c5cb6941ef1a135270f54015460ce5",
"sha256": "3aca4262c1def71a49403560ea9ae4585c8c49e1cde1b184eda8e5afda62695b"
},
"downloads": -1,
"filename": "django-sqlfun-0.0.7.tar.gz",
"has_sig": false,
"md5_digest": "e6c5cb6941ef1a135270f54015460ce5",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 11588,
"upload_time": "2024-02-28T23:31:26",
"upload_time_iso_8601": "2024-02-28T23:31:26.621315Z",
"url": "https://files.pythonhosted.org/packages/33/47/147301cff849775919562a38f18b3392a450e863e9dcaf923451452982a0/django-sqlfun-0.0.7.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-02-28 23:31:26",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "django-sqlfun"
}
JSON