Metadata-Version: 2.1
Name: django-libsql
Version: 0.1.2
Summary: A Django integration for libSQL / turso database
Home-page: https://github.com/aaronkazah/django-libsql
Author: Aaron Kazah
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Framework :: Django
Requires-Python: >=3
Description-Content-Type: text/markdown
Requires-Dist: Django >=2.2
Requires-Dist: libsql-client ==0.3.1

# Django + LibSQL / Turso

This project integrates Turso/Libsql with Django, allowing you to use Libsql as a database backend for your Django
applications.

## Installation

To install the package, use pip:

```
pip install django-libsql
```

## Configuration

To use Libsql as your database backend, update your Django settings as follows:

```python
DATABASES = {
    "default": {
        "ENGINE": "libsql.db.backends.libsql",
        "NAME": "libsql://${your-db-name}.turso.io?authToken=${your-auth-token}",
    }
}
```

Replace `${your-db-name}` and `${your-auth-token}` with your actual database name and authentication token.

## Usage

After configuration, you can use Django's ORM as usual. The Libsql backend will handle the database operations.

### Running Tests

To run tests, use the provided scripts:

1. Start the Libsql server:
   ```
   ./scripts/docker.sh
   ```

2. Run the tests:
   ```
   ./scripts/test.sh
   ```

The `test.sh` script handles the server lifecycle automatically.

## Self-Hosting

If you want to host your own Libsql server, refer to the provided Docker script. A working server setup along with key
generation is available in the repository.

## Known Issues

The current implementation has some limitations due to the lack of support for custom functions in the `libsql_client`:

1. Custom Django functions registered via `create_function` are not supported.
2. Certain Django ORM features that rely on these custom functions will not work. For example:
    - Date/time operations using `F()` objects
    - `dates()` queryset method

For a complete list of unsupported functions, query the `pragma_function_list` table in your database.

### Examples of Unsupported Operations

1. Date difference annotation:
   ```python
   Product.objects.annotate(date_diff=F("valid_until") - F("made_at"))
   ```

2. Date truncation in queryset:
   ```python
   SchoolClass.objects.dates("last_updated", "year")
   ```

These operations will raise `django.db.utils.OperationalError` due to missing functions.

## License

This project is distributed under the MIT license.

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## Support

If you encounter any issues or have questions, please open an issue on the GitHub repository.
