Add: Dashboard db migrations & tooling

.env.example

@@ -19,3 +19,6 @@ NEXT_PUBLIC_DEFAULT_API_DOMAIN=e2b.dev
 NEXT_PUBLIC_EXPOSE_STORYBOOK=0
 NEXT_PUBLIC_SCAN=0
 NEXT_PUBLIC_MOCK_DATA=0
+
+# For applying migrations
+# POSTGRES_CONNECTION_STRING=

README.md

@@ -75,21 +75,28 @@ vercel storage add
 3. Copy the `anon key` and `service_role key`
 4. Copy the project URL
 
-#### c. Supabase Storage Setup
+#### c. Database Setup
+1. Retrieve the `POSTGRES_CONNECTION_STRING` from the Supabase project settings
+2. Run the migrations by running the following command:
+```bash
+bun run db:migrations:apply
+```
+
+#### d. Supabase Storage Setup
 1. Go to Storage > Buckets
 2. Create a new **public** bucket named `profile-pictures`
-3. Apply storage access policies by running the SQL from [supabase/policies/buckets.sql](supabase/policies/buckets.sql) in the Supabase SQL Editor:
+3. Apply storage access policies by running the SQL from [migrations/supabase/profile-picture-bucket.sql](migrations/supabase/profile-picture-bucket.sql) in the Supabase SQL Editor:
    - These policies ensure only Supabase admin (service role) can write to and list files in the bucket
    - Public URLs are accessible for downloading files if the exact path is known
    - Regular users cannot browse, upload, update, or delete files in the bucket
 
-#### d. Environment Variables
+#### e. Environment Variables
 ```bash
 # Copy the example env file
 cp .env.example .env.local
 ```
 
-#### e. Cookie Encryption
+#### f. Cookie Encryption
 The dashboard uses encrypted cookies for secure data storage. You'll need to set up a `COOKIE_ENCRYPTION_KEY`:
 
 ```bash
@@ -179,3 +186,92 @@ If you need help or have questions:
 This project is licensed under the Apache License, Version 2.0 - see the [LICENSE](LICENSE) file for details.
 
 Copyright 2025 FoundryLabs, Inc.
+
+## Database Migrations
+
+The dashboard uses a custom migration system to manage database schema changes in a controlled, versioned manner.
+
+### Migration System Overview
+
+- **Timestamp-based**: Migrations are ordered by timestamp prefixes (YYYYMMDDHHMMSS)
+- **Idempotent**: Each migration is applied only once
+- **Transactional**: Migrations run in transactions for atomic changes
+- **Integrity checks**: Checksums verify migrations haven't been modified after application
+- **SQL-native**: Write pure SQL migrations with full PostgreSQL feature support
+
+### Creating Migrations
+
+To create a new migration:
+
+```bash
+# Create a migration with a description
+bun run db:migrations:create "add user profiles"
+# Creates: migrations/20250315123045.sql with description comment
+
+# Or create without description
+bun run db:migrations:create
+# Creates: migrations/20250315123045.sql
+```
+
+### Writing Migrations
+
+Migrations are SQL files that can contain multiple statements, including complex PostgreSQL features:
+
+```sql
+-- Migration: add user profiles
+-- Timestamp: 20250315123045
+
+-- Create profiles table
+CREATE TABLE profiles (
+  id UUID PRIMARY KEY REFERENCES auth.users(id),
+  display_name TEXT,
+  bio TEXT,
+  created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP
+);
+
+-- Create function to handle profile creation
+CREATE OR REPLACE FUNCTION create_profile_for_new_user()
+RETURNS TRIGGER AS $$
+BEGIN
+  INSERT INTO profiles (id)
+  VALUES (NEW.id);
+  RETURN NEW;
+END;
+$$ LANGUAGE plpgsql;
+
+-- Set up trigger
+CREATE TRIGGER on_user_created
+AFTER INSERT ON auth.users
+FOR EACH ROW
+EXECUTE FUNCTION create_profile_for_new_user();
+```
+
+### Applying Migrations
+
+To apply pending migrations:
+
+```bash
+bun run db:migrations:apply
+```
+
+This will:
+1. Create the migrations tracking table if it doesn't exist
+2. Apply any migrations that haven't been run yet
+3. Skip already-applied migrations
+4. Provide a summary of applied/skipped migrations
+
+### Migration Safety
+
+The system includes several safety features:
+- Migrations are applied in a transaction (all-or-nothing)
+- Each migration is recorded with a checksum to detect modifications
+- Warnings are shown if a previously applied migration file has changed
+- Execution stops on the first error to prevent partial migrations
+
+### Best Practices
+
+- **One change per migration**: Keep migrations focused on a single logical change
+- **Backward compatibility**: When possible, design migrations to be backward compatible
+- **Comments**: Document the purpose of complex migrations
+- **Testing**: Test migrations in development before applying to production
+- **Avoid modifying applied migrations**: Create a new migration instead of changing an existing one

bun.lock

@@ -32,7 +32,7 @@
         "@tanstack/match-sorter-utils": "^8.19.4",
         "@tanstack/react-query": "^5.65.0",
         "@tanstack/react-table": "^8.20.6",
-        "@tanstack/react-virtual": "^3.13.2",
+        "@tanstack/react-virtual": "^3.11.3",
         "@theguild/remark-mermaid": "^0.2.0",
         "@types/mdx": "^2.0.13",
         "@vercel/kv": "^3.0.0",
@@ -93,7 +93,7 @@
         "@tailwindcss/postcss": "^4.0.6",
         "@testing-library/jest-dom": "^6.6.3",
         "@testing-library/react": "^16.2.0",
-        "@types/bun": "latest",
+        "@types/bun": "^1.2.5",
         "@types/node": "22.10.10",
         "@types/pg": "^8.11.11",
         "@types/react": "^19.0.8",

migrations/20250205180205.sql

@@ -0,0 +1,109 @@
+/*
+This migration adds team slugs and profile pictures to support user-friendly URLs and team branding.
+
+It performs the following steps:
+
+1. Adds two new columns to the teams table:
+   - slug: A URL-friendly version of the team name (e.g. "acme-inc")
+   - profile_picture_url: URL to the team's profile picture
+
+2. Creates a slug generation function that:
+   - Takes a team name and converts it to a URL-friendly format
+   - Removes special characters, accents, and spaces
+   - Handles email addresses by only using the part before @
+   - Converts to lowercase and replaces spaces with hyphens
+
+3. Installs the unaccent PostgreSQL extension for proper accent handling
+
+4. Generates initial slugs for all existing teams:
+   - Uses the team name as base for the slug
+   - If multiple teams would have the same slug, appends part of the team ID
+     to ensure uniqueness
+
+5. Sets up automatic slug generation for new teams:
+   - Creates a trigger that runs before team insertion
+   - Generates a unique slug using random suffixes if needed
+   - Only generates a slug if one isn't explicitly provided
+
+6. Enforces slug uniqueness with a database constraint
+*/
+
+ALTER TABLE teams
+ADD COLUMN slug TEXT,
+ADD COLUMN profile_picture_url TEXT;
+
+CREATE OR REPLACE FUNCTION generate_team_slug(name TEXT)
+RETURNS TEXT AS $$
+DECLARE
+  base_name TEXT;
+BEGIN
+  base_name := SPLIT_PART(name, '@', 1);
+
+  RETURN LOWER(
+    REGEXP_REPLACE(
+      REGEXP_REPLACE(
+        UNACCENT(TRIM(base_name)),
+        '[^a-zA-Z0-9\s-]',
+        '',
+        'g'
+      ),
+      '\s+',
+      '-',
+      'g'
+    )
+  );
+END;
+$$ LANGUAGE plpgsql;
+
+CREATE EXTENSION IF NOT EXISTS unaccent;
+
+WITH numbered_teams AS (
+  SELECT
+    id,
+    name,
+    generate_team_slug(name) as base_slug,
+    ROW_NUMBER() OVER (PARTITION BY generate_team_slug(name) ORDER BY created_at) as slug_count
+  FROM teams
+  WHERE slug IS NULL
+)
+UPDATE teams
+SET slug =
+  CASE
+    WHEN t.slug_count = 1 THEN t.base_slug
+    ELSE t.base_slug || '-' || SUBSTRING(teams.id::text, 1, 4)
+  END
+FROM numbered_teams t
+WHERE teams.id = t.id;
+
+CREATE OR REPLACE FUNCTION generate_team_slug_trigger()
+RETURNS TRIGGER AS $$
+DECLARE
+  base_slug TEXT;
+  test_slug TEXT;
+  suffix TEXT;
+BEGIN
+  IF NEW.slug IS NULL THEN
+    base_slug := generate_team_slug(NEW.name);
+    test_slug := base_slug;
+
+    WHILE EXISTS (SELECT 1 FROM teams WHERE slug = test_slug) LOOP
+      suffix := SUBSTRING(gen_random_uuid()::text, 33, 4);
+      test_slug := base_slug || '-' || suffix;
+    END LOOP;
+
+    NEW.slug := test_slug;
+  END IF;
+  RETURN NEW;
+END;
+$$ LANGUAGE plpgsql;
+
+CREATE TRIGGER team_slug_trigger
+BEFORE INSERT ON teams
+FOR EACH ROW
+EXECUTE FUNCTION generate_team_slug_trigger();
+
+ALTER TABLE teams
+ADD CONSTRAINT teams_slug_unique UNIQUE (slug);
+
+ALTER TABLE teams
+ALTER COLUMN slug SET NOT NULL;

migrations/20250311144556.sql

@@ -0,0 +1,12 @@
+/*
+This migration creates a public view 'auth_users' that exposes selected columns
+from the auth.users table, making it easier to query user data from the public schema.
+*/
+
+CREATE OR REPLACE VIEW public.auth_users AS
+SELECT
+    *
+FROM auth.users;
+
+-- Grant SELECT permissions to supabase_admin role
+GRANT SELECT ON public.auth_users TO supabase_admin;

package.json

@@ -10,27 +10,25 @@
     "preview": "bun run build && bun start",
     "lint": "next lint",
     "lint:fix": "next lint --fix",
-
     "<<<<<< Development Tools": "",
     "dev:scan": "bun dev & bun scan",
     "start:scan": "bun start & bun scan",
-
     "<<<<<< Database": "",
     "db:types": "bunx supabase@latest gen types typescript --schema public > src/types/database.types.ts --project-id $SUPABASE_PROJECT_ID",
-    "db:migration": "bun scripts/create-migration.ts",
-
+    "db:migrations:create": "bun run scripts:create-migration",
+    "db:migrations:apply": "bun run scripts:apply-migrations",
     "<<<<<< Scripts": "",
     "scripts:check-app-env": "bun scripts/check-app-env.ts",
     "scripts:build-storybook": "bun scripts/build-storybook.ts",
     "scripts:check-e2e-env": "bun scripts/check-e2e-env.ts",
     "scripts:check-all-env": "bun scripts:check-app-env && bun scripts:check-e2e-env",
-
+    "scripts:create-migration": "bun scripts/create-migration.ts",
+    "scripts:apply-migrations": "bun scripts/apply-migrations.ts",
     "<<<<<< Development": "",
     "storybook": "storybook dev -p 6006",
     "shad": "bunx shadcn@canary",
     "prebuild": "bun scripts:build-storybook",
     "postinstall": "fumadocs-mdx",
-
     "<<<<<< Testing": "",
     "test:run": "bun scripts:check-all-env && vitest run",
     "test:integration": "bun scripts:check-app-env && vitest run src/__test__/integration/",
@@ -128,7 +126,7 @@
     "@tailwindcss/postcss": "^4.0.6",
     "@testing-library/jest-dom": "^6.6.3",
     "@testing-library/react": "^16.2.0",
-    "@types/bun": "latest",
+    "@types/bun": "^1.2.5",
     "@types/node": "22.10.10",
     "@types/pg": "^8.11.11",
     "@types/react": "^19.0.8",