Want Database Sharding Without Leaving PostgreSQL? Try Citus 🚀

If you’re building a Django application and starting to worry about scaling your database, you’ve probably heard words like sharding, distributed databases, or horizontal scaling — and then immediately thought:

“Sounds powerful… but also sounds painful 😅”

Good news: you don’t need to abandon PostgreSQL or Django ORM to get sharding. There’s a clean, production-proven way to do it using Citus Data.

In this post, I’ll explain:

• What Citus is (in simple terms)
• Why it fits Django surprisingly well
• How sharding actually works with Django + Citus
• When you should (and should not) use it

Join the discussion on Discord : https://discord.com/invite/XqqcAhg63f

First things first: What is Citus?

Citus Data is an extension on top of PostgreSQL that turns Postgres into a distributed database.

That means:

• Your data is split into shards
• Shards are stored across multiple machines (nodes)
• Queries run in parallel
• You can scale horizontally, not just vertically

The best part?

👉 To your application, it still looks like PostgreSQL.

Why Django + Citus is a great combo

Django talks to databases using SQL. Citus is PostgreSQL, so Django doesn’t need special drivers, SDKs, or ORM changes.

From Django’s point of view:

“I’m just talking to Postgres.”

From Citus’s point of view:

“I’ll decide which shard this query should go to.”

That separation is what makes Citus powerful and safe to use with Django.

The key concept: Distribution Key 🔑

Citus doesn’t magically guess how to shard your data. You must tell it how.

That’s done using a distribution key — a column that decides where each row lives.

Typical examples:

• tenant_id
• org_id
• account_id

Example Django model

class User(models.Model):
    tenant_id = models.UUIDField()
    email = models.EmailField()
    created_at = models.DateTimeField(auto_now_add=True)

After running normal Django migrations, you run one SQL command:

SELECT create_distributed_table('users', 'tenant_id');

That’s it.

From now on:

• Every INSERT is routed automatically
• Every SELECT with tenant_id hits only one shard
• Django ORM keeps working as usual

What happens when data is inserted?

When Django runs:

User.objects.create(
    tenant_id=tenant_id,
    email="user@example.com"
)

Behind the scenes:

Django ORM
   ↓
Citus Coordinator
   ↓
hash(tenant_id)
   ↓
Correct shard on a worker node

✅ No sharding logic in Django ✅ No custom routers ✅ No ORM hacks

Citus handles it automatically.

UUIDs and sharding: a quick clarification

A common question is:

“If I use UUIDs, won’t every row go to a different shard?”

It depends what the UUID represents.

✔ Good: UUID per tenant

tenant_id = UUID (same for all users in that tenant)

❌ Bad: UUID per user as shard key

Rule of thumb:

Shard by a group, not an individual row.

UUIDs are actually a great choice for tenant IDs in distributed systems.

When Citus is a perfect fit

Citus shines when your Django app has:

• Multi-tenant SaaS architecture
• Large datasets (millions+ rows)
• Event logs, audit logs, telemetry
• Analytics-heavy queries
• Write-heavy workloads

When you should NOT use Citus

Citus is not for everything.

Avoid it if your app is:

• A simple CRUD app
• An early MVP
• Heavy on random joins across tables
• Small enough to scale vertically

For many apps, plain PostgreSQL is still the best choice.

Final thoughts 🧠

If you’re a Django developer and hear “sharding” and think complex, risky, scary — Citus changes that story.

Citus lets you scale PostgreSQL horizontally without leaving the Django ecosystem.

Design your schema carefully, choose the right distribution key, and Citus will do the heavy lifting for you.

Join the discussion on Discord : https://discord.com/invite/XqqcAhg63f