66 lines
2.8 KiB
Markdown
66 lines
2.8 KiB
Markdown
# Sojorn Database Architecture & Context
|
|
|
|
**Last Updated:** January 27, 2026
|
|
|
|
## Overview
|
|
The Sojorn backend uses a PostgreSQL database hosted on a VPS. It is critical to note that there are multiple databases present in the Postgres instance, and the application serves from a specific one.
|
|
|
|
## Connection Details
|
|
- **Host:** `localhost` (Internal to VPS)
|
|
- **Port:** `5432`
|
|
- **Primary Database Name:** `sojorn`
|
|
- **User:** `postgres`
|
|
- **SSL Mode:** `disable`
|
|
- **Application Config Source:** `/opt/sojorn/.env` (on VPS)
|
|
|
|
**Warning:** Do not assume the database is named `postgres`. Always target the `sojorn` database for application schema changes.
|
|
|
|
## Critical Key Tables & Schema Notes
|
|
|
|
### 1. Profiles (`public.profiles`)
|
|
Stores user identity and global configuration.
|
|
|
|
| Column | Type | Notes |
|
|
| :--- | :--- | :--- |
|
|
| `id` | UUID | Primary Key |
|
|
| `handle` | Text | Unique user handle (username) |
|
|
| `is_private` | Boolean | **Crucial:** Controls visibility in global feeds. Defaults to `FALSE`. |
|
|
| `is_official` | Boolean | **Crucial:** Verification badge / official account status. |
|
|
| `identity_key` | Text | For E2EE (Signal Protocol) |
|
|
|
|
### 2. Follows (`public.follows`)
|
|
Manages the social graph.
|
|
|
|
| Column | Type | Notes |
|
|
| :--- | :--- | :--- |
|
|
| `follower_id` | UUID | User DOING the following |
|
|
| `following_id` | UUID | User BEING followed |
|
|
| `status` | Text | **Crucial:** Must be `'accepted'` or `'pending'`. Logic joins on `status='accepted'`. |
|
|
|
|
### 3. Posts (`public.posts`)
|
|
|
|
| Column | Type | Notes |
|
|
| :--- | :--- | :--- |
|
|
| `duration_ms` | Int | **Nullable**. Can be NULL for non-video posts. Queries MUST use `COALESCE(duration_ms, 0)`. |
|
|
| `is_beacon` | Boolean | Determines if post is location-aware. |
|
|
| `location` | Geography | Post coordinates (PostGIS). |
|
|
|
|
## Troubleshooting & Maintenance
|
|
|
|
### Accessing the Database (CLI)
|
|
To manually inspect or patch the database, use the following command pattern on the VPS:
|
|
```bash
|
|
# Connect specifically to the 'sojorn' database
|
|
export PGPASSWORD='YOUR_PASSWORD'
|
|
psql -U postgres -h localhost -d sojorn
|
|
```
|
|
|
|
### Common Pitfalls
|
|
1. **Patching `postgres` instead of `sojorn`:** Running `psql` without `-d sojorn` defaults to the `postgres` system DB. Schema changes here WON'T affect the app.
|
|
2. **Null Scanning:** Go's `database/sql` driver will panic or error if you try to `Scan` a SQL `NULL` into a non-pointer primitive (e.g., `int` vs `*int` or `NullInt`). Always use `COALESCE` in SQL queries for nullable optional fields like `duration_ms`, `image_url`.
|
|
3. **Scan Mismatches:** If you add a column to a `SELECT` query, you MUST add a corresponding destination variable in `rows.Scan()`.
|
|
|
|
### Migration Strategy
|
|
- The project currently relies on imperative SQL patches or `golang-migrate` scripts.
|
|
- Ensure any migration scripts target the `DATABASE_URL` defined in `.env`.
|