---

Title: Database Connections. Description: Securely manage database credentials for live analysis.

DATABASE CONNECTIONS

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

Optional Feature: You can use CAPYSQUASH by uploading migration files without connecting to your database.

WHY CONNECT YOUR DATABASE?

Benefits

🚀 AUTOMATION

► No manual file uploads ► Direct schema introspection ► Automatic migration detection ► Real-time analysis

• 🔍 ADVANCED ANALYSIS

• ► Live schema validation

• ► Performance insights

• ► Missing index detection

• ► Schema drift monitoring

CREATING A CONNECTION

CONNECT DATABASE IN 4 STEPS

1

• NAVIGATE TO CONNECTIONS

• Dashboard → Organization Settings → Database Connections

• 2

• ADD CONNECTION DETAILS

• ► Name (e.g., "Production DB")

• ► Connection URL or individual fields

• ► Provider (Neon, Supabase, etc.)

• ► Environment (production/staging/dev)

• 3

• TEST CONNECTION

• Click "Test Connection" to verify credentials

• 4

• SAVE

• Connection is encrypted and stored securely

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:

☁️ CLOUD PLATFORMS

► Neon ► Supabase ► Railway ► Render ► Fly.io

🏢 MAJOR CLOUDS

► AWS RDS ► Google Cloud SQL ► Azure PostgreSQL ► DigitalOcean ► Heroku

• 🔧 SELF-HOSTED

• ► On-premise

• ► Docker

• ► Kubernetes

• ► Any PostgreSQL 12+

SSL CONFIGURATION

SSL Modes

Recommendation: Always use require or higher for production databases. Most cloud providers require SSL.

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

SECURITY GUARANTEES

AT REST

☑ AES-256 encryption for all credentials

☑ Passwords never stored in plain text

☑ Encryption keys rotated regularly

☑ Separate encryption per organization

• IN TRANSIT

• ☑ TLS 1.3 for all connections

• ☑ SSL required for database connections

• ☑ Certificate validation

• ☑ No credential logging

• ACCESS

• ☑ Role-based access control

• ☑ Connection credentials never exposed via API

• ☑ Audit logs for all connection usage

• ☑ Automatic connection cleanup on org deletion

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:

All credentials valid, database accessible.

Common causes: - Wrong password - Firewall blocking connection - SSL not configured - Database not accepting connections

Connection works but took >3 seconds. May indicate network issues.

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

Connection Timeout

Symptoms: "Connection timed out" error

Causes:

Firewall blocking CAPYSQUASH Database not accepting external connections Wrong host/port

Solutions:

Whitelist CAPYSQUASH IP addresses (contact support)

Enable external connections in database settings

Verify host and port are correct

Authentication Failed

Symptoms: "Authentication failed" error

Causes:

Wrong username or password User doesn't have permissions Password special characters not escaped

Solutions:

Double-check credentials

Grant necessary permissions (see SQL above)

URL-encode password if it contains special characters

SSL Required

Symptoms: "SSL required" error

Causes:

Database requires SSL but connection URL has sslmode=disable Missing SSL certificate

Solutions:

Change sslmode=disable to sslmode=require

Upload SSL certificates if needed

Contact database provider for SSL settings

Database Not Found

Symptoms: "Database does not exist" error

Causes:

Wrong database name Database deleted No permissions to access database

Solutions:

Verify database name (case-sensitive)

Check database still exists

Ensure user has CONNECT permission

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 BEST PRACTICES

☑ DO

► Use read-only credentials

► Enable SSL/TLS

► Tag environments (prod/staging/dev)

► Test connections before saving

► Rotate credentials quarterly

► Use connection pooling for high-traffic databases

► Monitor connection health regularly

• ☒ DON'T

• ► Use admin/superuser credentials

• ► Disable SSL for production databases

• ► Share connections across organizations

• ► Ignore failed connection health checks

• ► Connect directly to production (use read replica)

Connection Naming

Good names:

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

Bad names:

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

LIMITATIONS

Need more connections? Upgrade to Professional for 5 connections, or Agency/Enterprise for unlimited.

NEXT STEPS

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