DATABASE CONNECTIONS

Database Connections allow CAPYSQUASH to securely connect to your PostgreSQL databases for advanced analysis features.

WHY CONNECT YOUR DATABASE?

Benefits

CREATING A CONNECTION

CONNECTION METHODS

Method 1: Connection URL

Easiest: Single connection string

postgresql://user:password@host:5432/database?sslmode=require

Components:

• Protocol: postgresql:// or postgres://
• Username: user
• Password: password
• Host: Database server address
• Port: 5432 (default PostgreSQL port)
• Database: Database name
• SSL Mode: require, prefer, disable

Method 2: Individual Fields

Alternative: Enter each field separately

• Host: db.example.com or 192.168.1.100
• Port: 5432 (default)
• Database: myapp_production
• Username: dbuser
• Password: **** (encrypted)
• SSL Mode: Choose from dropdown

SUPPORTED PROVIDERS

CAPYSQUASH auto-detects providers from connection URLs:

SSL CONFIGURATION

SSL Modes

Certificate Files

For verify-ca or verify-full modes, you may need to upload certificate files:

• Root CA Certificate - Verifies server identity
• Client Certificate - For mutual TLS (optional)
• Client Key - For mutual TLS (optional)

Format: PEM-encoded files

PROVIDER-SPECIFIC GUIDES

Neon

postgresql://user:password@ep-cool-sun-123456.us-east-2.aws.neon.tech/neondb?sslmode=require

Steps:

1. Go to Neon Console → Your Project
2. Copy connection string
3. Paste into CAPYSQUASH
4. Test connection

Notes:

• SSL is required (sslmode=require)
• Connection pooling available via :5432/neondb → :6543/neondb

Supabase

postgresql://postgres:[YOUR-PASSWORD]@db.projectref.supabase.co:5432/postgres?sslmode=require

Steps:

1. Go to Supabase Dashboard → Project Settings → Database
2. Copy "Connection string" under "Connection pooling"
3. Replace [YOUR-PASSWORD] with actual password
4. Paste into CAPYSQUASH

Notes:

• Use connection pooling URL (port 6543) for better performance
• SSL is required
• Default database is postgres

Railway

postgresql://postgres:password@containers-us-west-123.railway.app:5432/railway?sslmode=require

Steps:

1. Railway Dashboard → Your Service → Variables
2. Copy DATABASE_URL
3. Paste into CAPYSQUASH

Notes:

• Railway auto-generates secure credentials
• SSL recommended but not required

AWS RDS

postgresql://admin:password@mydb.abc123.us-east-1.rds.amazonaws.com:5432/production?sslmode=require

Steps:

1. AWS Console → RDS → Databases
2. Click your database → Connectivity & Security
3. Note endpoint, port, username
4. Construct connection URL
5. Add to CAPYSQUASH

Notes:

• Enable "Publicly Accessible" or use VPN
• Configure security group to allow CAPYSQUASH IPs (contact support for IPs)
• SSL recommended

CONNECTION PROPERTIES

Basic Information

Name (required)

• Display name for the connection
• Example: "Production API", "Staging Dashboard"

Description (optional)

• Additional context about this connection
• Example: "Main production database on Neon"

Provider (auto-detected)

• Database hosting provider
• Helps optimize connection settings

Environment Tagging

Environment (optional)

• production - Production database
• staging - Staging/QA environment
• development - Local/dev environment
• testing - Test databases

Benefits:

• Visual indicators (production tagged with warning colors)
• Prevent accidental production operations
• Filter connections by environment

Project Association

Link to Project (optional)

• Associate connection with a specific project
• Project can auto-use this connection for analysis

Access Control

Organization-level (default)

• All organization members can use
• Based on their role permissions

Project-specific

• Only members of linked project can use
• Additional access restriction

SECURITY

Encryption

Recommended Permissions

Create a read-only database user for CAPYSQUASH:

-- Create read-only user
CREATE USER capysquash_readonly WITH PASSWORD 'secure_password_here';

-- Grant connect permission
GRANT CONNECT ON DATABASE your_database TO capysquash_readonly;

-- Grant schema usage
GRANT USAGE ON SCHEMA public TO capysquash_readonly;

-- Grant read-only access to all tables
GRANT SELECT ON ALL TABLES IN SCHEMA public TO capysquash_readonly;

-- Grant access to information schema (for introspection)
GRANT SELECT ON ALL TABLES IN SCHEMA information_schema TO capysquash_readonly;
GRANT SELECT ON ALL TABLES IN SCHEMA pg_catalog TO capysquash_readonly;

-- Make it apply to future tables
ALTER DEFAULT PRIVILEGES IN SCHEMA public
GRANT SELECT ON TABLES TO capysquash_readonly;

Why read-only?

• CAPYSQUASH only needs to read schema structure
• No data modification
• Enhanced security
• Compliance-friendly

TESTING CONNECTIONS

Test Before Saving

Always test connections before saving:

1. Enter connection details
2. Click "Test Connection"
3. Wait for result

Possible results:

Connection Health

After saving, CAPYSQUASH periodically checks connection health:

Healthy: ☑ Last checked < 24 hours ago, working Warning: ⚠️ Last check failed, trying again Offline: ☒ Multiple failures, connection disabled

USING CONNECTIONS

In Projects

Auto-use:

1. Go to Project Settings
2. Select "Default database connection"
3. Project automatically uses this connection for analysis

Manual selection:

1. Start new analysis
2. Choose "Use database connection" instead of file upload
3. Select connection from dropdown

Direct Schema Analysis

Analyze your database schema without uploading files:

1. Create database connection
2. Go to project or create new one
3. Click "Analyze from Database"
4. Select connection
5. CAPYSQUASH introspects schema and generates report

What's analyzed:

• Table structures
• Indexes (missing, unused, duplicate)
• Constraints
• Foreign keys
• Views and materialized views
• Sequences
• Functions and triggers

MANAGING CONNECTIONS

Update Connection

When to update:

• Password rotated
• Database migrated to new host
• SSL settings changed
• Provider changed (e.g., local → Neon)

How:

1. Go to Database Connections
2. Click connection to edit
3. Update fields
4. Test connection
5. Save

Delete Connection

Warning: Deletion is permanent

What happens:

• Connection removed immediately
• Projects using this connection will need new selection
• All encrypted credentials deleted
• Action logged in audit trail

Requirements:

• Admin or Owner role
• Confirmation required

Connection Activity

View usage history:

Information shown:

• Last used timestamp
• Total times used
• Which projects used it
• Recent connection attempts (success/failure)
• Any error messages

TROUBLESHOOTING

Common Issues

URL Encoding Passwords

If your password contains special characters, URL-encode them:

Example:

# Original password: myP@ss:word!
# Encoded URL:
postgresql://user:myP%40ss%3Aword!@host:5432/db

BEST PRACTICES

Connection Naming

Good names:

• "Production API - Neon"
• "Staging Dashboard - Supabase"
• "Dev Local - PostgreSQL 16"

Bad names:

• "Database 1"
• "test"
• "connection"

LIMITATIONS

NEXT STEPS

• API Keys
• Notification Rules
• Projects
• Security Best Practices