136 lines
4.1 KiB
Markdown
136 lines
4.1 KiB
Markdown
|
|
|
|
---
|
|
|
|
## 🗄️ Shared Supabase Database - Table Naming Convention
|
|
|
|
**Date Documented:** February 22, 2026
|
|
**Applies To:** All web apps using shared Supabase project (`qnatchrjlpehiijwtreh`)
|
|
|
|
### The Rule
|
|
|
|
**ALWAYS use `<project_name>_<table_name>` format with underscores (NO hyphens)**
|
|
|
|
### Why This Matters
|
|
|
|
- All Vercel-deployed web apps share ONE Supabase project
|
|
- Prevents table name collisions between apps
|
|
- Maintains clean separation of data per app
|
|
- Enables cross-app queries when needed (via user_id or shared keys)
|
|
|
|
### Current Apps & Table Prefixes
|
|
|
|
| App | URL | Table Prefix | Example Tables | Notes |
|
|
|-----|-----|--------------|----------------|-------|
|
|
| **Gantt Board** | https://gantt-board.twisteddevices.com | *(none - legacy)* | `tasks`, `projects`, `sprints`, `users` | **First app** - created before naming convention. Tables have no prefixes. |
|
|
| **Blog Backup** | https://blog.twisteddevices.com | `blog_` | `blog_messages`, `blog_tags` | Uses prefix convention ✅ |
|
|
| **Mission Control** | https://mission-control.twisteddevices.com | `mission_control_` | `mission_control_documents`, `mission_control_folders` | Uses prefix convention ✅ |
|
|
| **Heartbeat Monitor** | http://localhost:3005 | `heartbeat_` | `heartbeat_status`, `heartbeat_logs` | Uses prefix convention ✅ |
|
|
|
|
### Legacy Tables (No Prefix)
|
|
|
|
**Gantt Board** was the first app and predates the naming convention. Its tables remain without prefixes:
|
|
- `tasks`
|
|
- `projects`
|
|
- `sprints`
|
|
- `users` (shared)
|
|
|
|
**Future Consideration:** If we need to avoid confusion, we could migrate these to `gantt_tasks`, `gantt_projects`, etc. But for now, they remain as-is since Gantt Board is the primary app.
|
|
|
|
**All NEW apps MUST use prefixes.**
|
|
|
|
### Naming Convention Details
|
|
|
|
**✅ CORRECT:**
|
|
```sql
|
|
mission_control_documents
|
|
blog_messages
|
|
gantt_tasks
|
|
heartbeat_status
|
|
```
|
|
|
|
**❌ INCORRECT:**
|
|
```sql
|
|
mission-control_documents -- No hyphens!
|
|
documents -- No prefix, will collide
|
|
mc_docs -- Abbreviation unclear
|
|
```
|
|
|
|
### Creating New Tables
|
|
|
|
**Always follow this pattern:**
|
|
|
|
```sql
|
|
CREATE TABLE <project_name>_<table_name> (
|
|
id uuid DEFAULT gen_random_uuid() PRIMARY KEY,
|
|
-- your columns
|
|
created_at timestamptz DEFAULT now(),
|
|
updated_at timestamptz DEFAULT now(),
|
|
user_id uuid REFERENCES auth.users(id)
|
|
);
|
|
|
|
-- Enable RLS
|
|
ALTER TABLE <project_name>_<table_name> ENABLE ROW LEVEL SECURITY;
|
|
|
|
-- Add policies
|
|
CREATE POLICY "Allow all" ON <project_name>_<table_name>
|
|
FOR ALL USING (true) WITH CHECK (true);
|
|
```
|
|
|
|
### Shared Tables (No Prefix)
|
|
|
|
These tables are shared across ALL apps:
|
|
- `users` — Auth users (managed by Supabase Auth)
|
|
- `profiles` — User profiles (shared)
|
|
- `auth` tables — Managed by Supabase
|
|
|
|
### When Adding a New App
|
|
|
|
1. **Choose a prefix:** Short, clear, unique
|
|
- Example: `finance_`, `habit_`, `inventory_`
|
|
|
|
2. **Document it:** Add to the table above
|
|
|
|
3. **Use consistently:** Every table gets the prefix
|
|
|
|
4. **Update .env.local:** Copy from existing project:
|
|
```
|
|
NEXT_PUBLIC_SUPABASE_URL=https://qnatchrjlpehiijwtreh.supabase.co
|
|
NEXT_PUBLIC_SUPABASE_ANON_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
|
|
```
|
|
|
|
### Querying Across Apps
|
|
|
|
Since tables are prefixed, you can join across apps if needed:
|
|
|
|
```sql
|
|
-- Example: Get user's tasks from Gantt + documents from Mission Control
|
|
SELECT
|
|
gantt_tasks.title as task,
|
|
mission_control_documents.title as doc
|
|
FROM gantt_tasks
|
|
JOIN mission_control_documents
|
|
ON gantt_tasks.user_id = mission_control_documents.user_id
|
|
WHERE gantt_tasks.user_id = '<user-id>';
|
|
```
|
|
|
|
### Migration Checklist
|
|
|
|
When moving an app from LocalStorage to Supabase:
|
|
|
|
- [ ] Choose table prefix (if not already set)
|
|
- [ ] Create tables with prefix in Supabase SQL Editor
|
|
- [ ] Update frontend to use Supabase client
|
|
- [ ] Migrate existing data (if any)
|
|
- [ ] Test CRUD operations
|
|
- [ ] Document the prefix in this file
|
|
|
|
### Related Files
|
|
|
|
- **Supabase Project:** https://supabase.com/dashboard/project/qnatchrjlpehiijwtreh
|
|
- **Connection String:** In each app's `.env.local`
|
|
- **Shared Config:** `SPECIALIZED_AGENTS.md` (web-dev section)
|
|
|
|
---
|
|
|
|
**Remember:** When in doubt, use the full project name with underscores. No hyphens, no abbreviations, no exceptions! |