hstore holds a flexible key-value map in a column

Wed, 16 Jun 2027 00:00:00 +0000

When a model keeps sprouting loose attributes, hstore holds them in one row instead of a growing join chain. Every product grows settings nobody predicted — per-tenant flags, integration tokens, display preferences. Modeling each as a column means endless migrations; as a table, joins for trivia. hstore offers the middle path — one column carrying a flat string map — for attributes that are numerous, optional, and individually unimportant.

The bargain is explicit: you trade type safety and constraint power for agility. Keys and values are text, there are no nested structures, and the database cannot enforce much about the contents. For genuinely loose metadata that tradeoff wins; for data the business reasons about, it loses. Knowing which side each attribute falls on is the whole skill.

One type, one column

Once the extension is enabled, an hstore column stores many key-value pairs in a single cell, simpler than mirroring the shape with extra tables. Add it with CREATE EXTENSION hstore and declare the type. Writes use a natural literal — 'color=>blue, size=>large' — and updates touch single keys with concatenation and deletion operators rather than rewriting the map by hand. The application reads the column as a dictionary in most drivers, so round-tripping needs no special parsing layer.

Migration-wise this is the cheapest flexibility available: one extension, one column, zero new tables, no backfill — absent keys simply do not exist rather than living as NULLs. When a new attribute appears, no DDL runs; the writer just starts including the key.

Query with operators

Use the hstore operators for existence and containment, and back the column with a GIN index so those checks stay fast as the map grows. The ? operator tests key existence, -> extracts a value as text, and @> matches whole key-value slices — together they cover existence, projection, and containment without unpacking the map client-side. A GIN index directly supports the existence and containment forms; if a hot query extracts one known key and compares its value, add a separate expression index for that key rather than assuming the generic GIN index can answer it.

Design queries around whole-key access, not pattern surgery on serialized text. data -> 'color' uses the structure; data::text LIKE '%color%' defeats it, ignoring the index and matching substrings that are not keys. Operators respect the map, casts destroy it — check for the cast first in review.

Prefer JSONB for rich rows

hstore stores only strings, so when keys need real types or stricter references, JSONB often serves richer rows better. Choose hstore for plain key-value maps and JSONB when the values need to be structured. The decision line runs through three questions: do values need numbers, booleans, or nesting (JSONB wins); do you need constraints or foreign keys into the values (neither serves well — normalize instead); is every value genuinely free-form text with uniform access patterns (hstore wins on simplicity and smaller storage).

Migration between the two is a single cast in either direction, so the choice is reversible. Start with hstore while the shape is flat; promote to JSONB when the first nested value appears, or to real columns when some key becomes load-bearing logic. The ladder is flat map, structured document, normalized schema — climb it as certainty grows.

When it breaks

The classic failure is the load-bearing string: a key that started as decoration becomes critical — pricing tier, access flag, routing rule — while still living as untyped text with no constraints. Typos create parallel realities (gold vs Gold), comparisons sort lexicographically instead of numerically, and no constraint can stop either. Promote such keys to typed columns with checks the moment business logic branches on them; the migration is cheap, the ambiguity it removes is not.

The second failure is unindexed growth: the map accumulates thousands of distinct keys, queries filter by key without a GIN index, and reads degrade into full scans plus per-row unpacking. Add the GIN index before the key space explodes, and evict keys nobody filters on back to logs or blob storage.

Check it quickly

Prove operators and index behavior:

SELECT 'a=>1, b=>2'::hstore -> 'a', 'a=>1, b=>2'::hstore ? 'c';
CREATE INDEX ON prefs USING GIN (attrs);
EXPLAIN SELECT * FROM prefs WHERE attrs @> 'theme=>dark';

The first exercises extraction and existence. The containment query should use the GIN index when its selectivity justifies it; a small table may correctly choose a sequential scan, so compare the plan after loading representative data.

Sources

PostgreSQL hstore, Official extension reference for the hstore type, checked 2026-06-01.
PostgreSQL JSON types, documents json and jsonb types and operators, checked 2026-09-05.