---

Title: Projects. Description: Organize and manage your migration projects.

PROJECTS

Projects help you organize migrations by application, environment, or database.

WHAT IS A PROJECT?

A project represents a single database or application with its own set of migrations.

PROJECT STRUCTURE Each project contains:

☑ Name & description - Identify your project ☑ Safety level - Default consolidation mode ☑ Database connection - Optional for live analysis ☑ Analysis runs - History of all squashing operations ☑ Team access - Who can view/edit

PROJECT EXAMPLES

By Application

Organization: Acme Startup
├── Production API (PostgreSQL on Neon)
├── Staging API (PostgreSQL on Neon)
├── Mobile Backend (PostgreSQL on Supabase)
└── Analytics DB (PostgreSQL on AWS RDS)

By Environment

Organization: SaaS Company
├── Main App - Production
├── Main App - Staging
├── Main App - Development
└── Main App - Testing

By Client (Agencies)

Organization: Web Agency
├── Client A - Production
├── Client A - Staging
├── Client B - Production
├── Client B - Staging
└── Internal Tools

CREATING A PROJECT

CREATE PROJECT IN 4 STEPS

NAVIGATE TO PROJECTS
Dashboard → Projects → New Project
2
FILL DETAILS
► Name (e.g., "Production API")
► Description (optional)
► Color & icon (optional)
3
CONFIGURE SETTINGS
► Safety level (paranoid/conservative/standard/aggressive)
► Database provider (Neon, Supabase, AWS, etc.)
► Database connection (optional)
4
CREATE & START
Click "Create Project" and start analyzing!

PROJECT SETTINGS

Basic Information

Name

Display name for the project
Can be changed anytime
Example: "Production API", "Mobile Backend"

Description

Optional longer description
Visible to all team members
Example: "Main API database for production environment"

Color & Icon

Visual identification
Helps quickly identify projects in dashboard
Choose from preset colors and icons

Safety Configuration

Default Safety Level

Choose the default for all analyses in this project:

Level	Use Case
Paranoid	First-time use, critical production
Conservative	Production databases
Standard	Most use cases (recommended)
Aggressive	Development, fresh starts

Can be overridden per analysis run.

Learn more about safety levels →

Database Connection (Optional)

Connect your live database for advanced features:

Benefits:

Direct migration analysis without file upload
Schema introspection
Automated migration detection
Live validation

What you need:

Database host
Database name
Username & password
SSL configuration (usually required)

Supported providers:

Neon
Supabase
AWS RDS
Azure PostgreSQL
Google Cloud SQL
Railway
Render
Any PostgreSQL 12+

Security:

Credentials encrypted at rest (AES-256)
Never exposed in API responses
Read-only access recommended
Can test connection before saving

💡 Note: Database connection is optional. You can analyze migrations by uploading files without connecting to your database.

GitHub Integration

Link a GitHub repository to enable:

Automatic PR analysis
Comment results on pull requests
Pass/fail checks
Branch detection

Set up GitHub integration →

Auto-Squash Settings

Configure automatic squashing:

Frequency:

Never (manual only)
Daily
Weekly (recommended)
Monthly

Day & Time:

Choose specific day/time for weekly/monthly
Uses your organization's timezone

Safety Level:

Override default for auto-squashing
Usually more conservative

Auto-PR Creation:

Automatically create PR with squashed migrations
Requires GitHub integration
Team reviews before merge

PROJECT LIMITS

Plan	Projects Allowed
Free	3 projects
Creator	10 projects
Professional	Unlimited
Agency	Unlimited
Enterprise	Unlimited

ANALYZING MIGRATIONS

Upload Files

ANALYZE MIGRATIONS

GO TO PROJECT
Open your project from dashboard
2
UPLOAD MIGRATIONS
Drag & drop SQL files or select from folder
3
START ANALYSIS
Click "Analyze" and wait for results
4
REVIEW & DOWNLOAD
See results, download optimized files

Supported File Formats

.sql - Standard SQL files
.up.sql - Goose/Migrate-style up migrations
Multiple files in ZIP archive
Timestamped filenames automatically detected

Analysis Results

After analysis completes, you'll see:

Statistics:

Original: 156 files (2.3 MB)
Optimized: 12 files (298 KB)
Reduction: 92% fewer files, 87% smaller
Time savings: ~35 minutes per CI/CD run

Visualizations:

Operations breakdown (CREATE, ALTER, DROP, etc.)
File comparison chart
Consolidation graph
Timeline view

Warnings:

Potential data loss scenarios
Missing indexes
Redundant operations
Best practice violations

Download Options:

ZIP archive of optimized migrations
Individual files
Analysis report (PDF)
Share link

ANALYSIS HISTORY

View all past analysis runs:

📊 RUN HISTORY Each run shows:

☑ Timestamp ☑ Who ran it ☑ Files analyzed ☑ Reduction achieved ☑ Warnings count ☑ Status (success/failed)

Filter runs by:

Date range
User
Status
Safety level

PROJECT COLLABORATION

Activity Log

See all project activity:

Analysis runs
Settings changes
Files uploaded
Downloads

🚧 Coming Soon: Team discussions and commenting features are planned for a future release.

PROJECT DASHBOARD

Each project has its own dashboard showing:

Health Metrics

📈 CURRENT STATE

► Migration count ► Last analysis date ► Current health score ► Warnings count

⏱️ IMPACT
► Total time saved
► Total files reduced
► Analyses run count
► Average reduction

Recent Activity

Last 10 analysis runs
Recent downloads
Team member activity

ARCHIVING PROJECTS

Archive projects you're not actively using:

Benefits:

Declutter dashboard
Preserve history
Free up project slots (Free/Creator plans)

How to archive:

Go to Project Settings
Click "Archive Project"
Confirm

What happens:

Project hidden from main dashboard
History preserved
Can be unarchived anytime
Still counts toward storage (Enterprise)

DELETING PROJECTS

⚠️ PERMANENT DELETION Deleting a project permanently removes:

► All analysis runs ► All uploaded files ► All comments ► All activity history ► Database connection

This cannot be undone!

Requirements:

Admin or Member role
Confirm by typing project name

BEST PRACTICES

Naming Conventions

Good names:

"Production API"
"Mobile Backend - Production"
"Client XYZ - Staging"

Avoid:

"Project 1"
"test"
"asdf"

Organization Strategies

By Environment:

MyApp - Production
MyApp - Staging
MyApp - Development

By Service:

Auth Service
API Gateway
User Service
Notification Service

For Agencies:

[Client Name] - [Environment]
Acme Corp - Production
Acme Corp - Staging
Beta Inc - Production

Safety Level Selection

Production projects: Conservative or Paranoid Staging projects: Standard Development projects: Standard or Aggressive First-time analysis: Start with Conservative

Regular Analysis

Recommended frequency:

High activity: Weekly
Medium activity: Bi-weekly
Low activity: Monthly

Set up auto-squashing to automate this.

MULTI-PROJECT DASHBOARD

View all projects at once:

Available views:

Grid view (cards)
List view (table)
Health view (sorted by warnings)
Activity view (sorted by recent)

Filters:

By safety level
By database provider
By health status
By team member

Bulk actions:

Archive multiple projects
Change safety level
Export data

COMMON QUESTIONS

Q: Can I have the same project in multiple organizations? A: No, each project belongs to one organization.

Q: What counts as one project? A: One database or application. Different environments (prod/staging) are typically separate projects.

Q: Can I transfer a project to another organization? A: Not yet. Contact support@CAPYSQUASH.dev for assistance.

Q: How much storage does each project use? A: Analysis results and uploaded files. Usually <100 MB per project. Only Enterprise plans have storage limits.

Q: Can I export project data? A: Yes. Click "Export Data" in project settings to download all runs as JSON.

---

---