# Django HStore Project

A monorepo for the Django HStore ecosystem providing a human-friendly,
Lit-based key-value editor for PostgreSQL hstore fields in Django admin.

- **Python**: 3.10+
- **Django**: 5.0+
- **PostgreSQL**: 14+

# django-hstore-field API

## django_hstore_field.HStoreField

Drop-in replacement for Django's ``HStoreField`` with the custom widget.

Overrides ``formfield()`` so that the admin and ModelForms automatically
use ``HStoreFormField`` and ``HStoreFormWidget``.

```python
from django.db import models
from django_hstore_field import HStoreField

class Product(models.Model):
    name = models.CharField(max_length=100)
    metadata = HStoreField()
    class Meta:
        app_label = "example"
```

### formfield(**kwargs)

Return a form field class pre-configured with the custom widget.
Pass ``form_class`` or ``widget`` to override the defaults.

# Installation

Installation
============

Get up and running with django-hstore-project in minutes.

Requirements
------------

- :iconify:`mdi:python` **Python 3.10+**
- :iconify:`logos:django` **Django 5.0+**
- :iconify:`logos:postgresql` **PostgreSQL 14+**
- Modern browsers (Chrome 112+, Firefox 117+, Safari 16.5+)

Install django-hstore-field
---------------------------

.. tabs::

   .. tab:: :iconify:`logos:pypi` pip

      .. termynal::
         $ pip install django-hstore-field
         -->
         Collecting django-hstore-field
         Collecting django-hstore-widget
         Installing collected packages...
         Successfully installed django-hstore-field django-hstore-widget

   .. tab:: :iconify:`simple-icons:astral` uv

      .. termynal::
         $ uv pip install django-hstore-field
         -->
         Collecting django-hstore-field
         Collecting django-hstore-widget
         Installing collected packages...
         Successfully installed django-hstore-field django-hstore-widget

   .. tab:: :iconify:`simple-icons:poetry` Poetry

      .. termynal::
         $ poetry add django-hstore-field
         -->
         Creating virtualenv: django-hstore-project
         Package django-hstore-field added.
         Package django-hstore-widget added (dependency).

   .. tab:: :iconify:`simple-icons:pdm` PDM

      .. termynal::
         $ pdm add django-hstore-field
         -->
         Adding packages to workspace: django-hstore-field
         Package django-hstore-widget added (dependency).
         All packages are installed.

   .. tab:: :iconify:`mdi:package-variant` pip-tools

      .. termynal::
         $ echo "django-hstore-field" >> requirements.in
         $ pip-compile requirements.in
         -->
         #
         # This file is autogenerated by pip-compile
         #
         django-hstore-field==1.0.0
         django-hstore-widget==1.0.0
         $ pip-sync requirements.txt

Configure
---------

Add both packages to your ``INSTALLED_APPS``:

.. code-block:: python

   # settings.py
   INSTALLED_APPS = [
       ...,
       'django_hstore_widget',
       'django_hstore_field',
       ...,
   ]

Run Migrations
--------------

.. termynal::
   $ python manage.py migrate
   -->
   Operations to perform:
     Apply all migrations: admin, auth, contenttypes, sessions
   Running migrations:
     Applying contenttypes.0001_initial... OK
     Applying auth.0001_initial... OK
   All migrations completed.

This enables the PostgreSQL hstore extension automatically.

Next
----

Head over to the :doc:`quickstart` to use HStore fields in your models.

# Quick Start

Quick Start
===========

Get up and running with django-hstore-project in under a minute.

Create a Model
--------------

Add an HStore field to any model:

.. code-block:: python

   # models.py
   from django.db import models
   from django_hstore_field import HStoreField

   class Product(models.Model):
       name = models.CharField(max_length=100)
       metadata = HStoreField()

That's it. The widget is auto-wired, no form configuration needed.

Run Migrations
--------------

.. code-block:: bash

   python manage.py makemigrations
   python manage.py migrate

This enables the PostgreSQL hstore extension automatically.

Register in Admin
-----------------

.. code-block:: python

   # admin.py
   from django.contrib import admin
   from .models import Product

   @admin.register(Product)
   class ProductAdmin(admin.ModelAdmin):
       pass

Visit your admin page and you'll see the HStore widget with a clean key-value
interface. Each key-value pair is editable inline. Add, remove, and modify pairs
as needed.

With Custom Keys
----------------

Define explicit keys to get labeled form fields instead of the free-form editor:

.. code-block:: python

   from django import forms
   from django_hstore_field import HStoreField

   class Product(models.Model):
       name = models.CharField(max_length=100)
       metadata = HStoreField(
           keys=[
               ('color', {'widget': forms.TextInput}),
               ('size', {'widget': forms.Select, 'choices': SIZE_CHOICES}),
               ('material', {'widget': forms.TextInput}),
           ],
       )

Each key becomes a proper form field with validation, widgets, and labels.

What's Next
-----------

- :doc:`../user-guide/installation` - Detailed installation options
- :doc:`../technical/hstore-vs-jsonb` - When to use HStore vs JSONB
- :doc:`../user-guide/best-practices` - Tips for production use