# PostgreSQL

PostgreSQL is our primary relational database - the source of truth for all core application data.

## What is PostgreSQL?

Traditional relational database with ACID guarantees, complex query support, and strong data integrity.

## Our Databases

- **`suno_studio`** - Main application database. The original database
- **`suno2`** - Second databased created since the first was getting too big. Currently used for video/imagee generation.

## Access Pattern

Via Django ORM:

```python
from studio_api.bots.models import GeneratedClip

# Query with relationships
clip = GeneratedClip.objects.select_related('user').get(id=clip_id)

# Complex filters
trending_clips = GeneratedClip.objects.filter(
    created_at__gte=last_week,
    user_reaction_count__gte=100
).order_by('-user_reaction_count')[:50]
```

## Pros

✅ **ACID Transactions** - Data consistency guarantees

✅ **Complex Queries** - JOINs, aggregations, window functions

✅ **Django ORM** - Well-integrated with our framework

✅ **Data Integrity** - Foreign keys, constraints, validations

✅ **Mature Tooling** - pg_stat_statements, EXPLAIN, indexing

## Cons

❌ **Vertical Scaling** - Eventually hit single-server limits

❌ **Schema Migrations** - Can be slow on large tables

❌ **Not for Rapid Evolution** - Schema changes require careful planning

## When to Use

### ✅ Use PostgreSQL for:
- User accounts and profiles
- Core application entities (clips, playlists)
- Data requiring relationships (foreign keys)
- Data needing ACID guarantees (billing, credits)

### ❌ Don't use PostgreSQL for:
- Frequently changing schemas
- High-throughput counters (use [Redis](/backend/data-storage/redis))
- Full-text search (use [Elasticsearch](/backend/data-storage/elasticsearch))
- Large binary data (use S3)

## Related Documentation

- [How to Add a Database](/infra/postgres/add-new-db)
- [Backend Guide](/backend/backend-guide)