QuickSight Quickstart

A comprehensive Python CLI toolkit for AWS QuickSight asset management and deployment, featuring export/import capabilities and automated infrastructure setup.

Features

• 📊 Export/Import: Export QuickSight resources as CloudFormation templates
• 🏗️ Infrastructure as Code: Automated database and networking setup
• 🔄 Deployment Automation: One-command deployment of complete environments
• 🧪 Sample Data: Pre-configured sales dataset for testing and demonstration
• 🧪 Well Tested: Comprehensive test suite with pytest

Quick Start

Basic Usage

1. Export QuickSight Resources:

   uv run quicksight-export -r us-east-1 -o ./export

2. Deploy Complete Environment:

   uv run quicksight-deploy -e quickstart

3. Cleanup Resources:

   uv run quicksight-deploy --cleanup

CLI Commands

Export Command (quicksight-export)

Export QuickSight dashboards and analyses as CloudFormation templates.

# Export all resources
quicksight-export -r us-east-1

# Export specific resources
quicksight-export -d "dashboard-1,dashboard-2" -A "analysis-1"

# List available resources
quicksight-export --list-resources

# Export to custom directory
quicksight-export -o ./exports --format cloudformation

Options:

• -a, --account-id: AWS Account ID (auto-detected if not provided)
• -r, --region: AWS Region (default: us-east-1)
• --profile: AWS Profile to use
• -j, --job-id: Export job ID (auto-generated if not provided)
• -o, --output-dir: Output directory (default: ./export)
• -d, --dashboard-ids: Comma-separated dashboard IDs
• -A, --analysis-ids: Comma-separated analysis IDs
• --format: Export format (cloudformation|quicksight)
• --list-resources: List available resources without exporting
• --no-dependencies: Don't include dependencies in export
• --timeout: Maximum wait time in seconds (default: 300)

Deploy Command (quicksight-deploy)

Deploy QuickSight resources with database infrastructure.

# Deploy complete environment
quicksight-deploy -e production

# Deploy with custom template and password
quicksight-deploy -t ./my-template.yaml --db-password mypass123

# Skip infrastructure (use existing database)
quicksight-deploy --skip-infrastructure

# Cleanup all resources
quicksight-deploy --cleanup

Options:

• -r, --region: AWS Region (default: from AWS CLI config)
• --profile: AWS Profile to use
• -e, --environment: Environment name (default: quickstart)
• --db-stack-name: Database stack name (auto-generated if not provided)
• --quicksight-stack-name: QuickSight stack name (auto-generated if not provided)
• --db-password: Database password (default: quicksight123)
• -t, --template-file: CloudFormation template file (default: export/bundle2.yaml)
• --skip-infrastructure: Skip database infrastructure deployment
• --skip-database-setup: Skip database table and data setup
• --skip-quicksight: Skip QuickSight resources deployment
• --skip-permissions: Skip QuickSight permissions setup
• --cleanup: Remove all deployed resources

Architecture

The deployment creates:

Database Infrastructure

• RDS PostgreSQL: Managed database instance
• VPC: Isolated network with public/private subnets
• Security Groups: Proper network access controls
• S3 Bucket: Storage for CloudFormation templates

QuickSight Resources

• Data Sources: Connection to PostgreSQL database
• Datasets: Structured data for analysis
• Analyses: Interactive visualizations
• Dashboards: Published business insights

Sample Data Schema

• customers: Customer master data
• products: Product catalog with categories
• sales: Transaction records with metrics
• regions: Geographic hierarchy

Development

Project Structure

quicksight_quickstart/
├── quicksight_quickstart/          # Main package
│   ├── core/                       # Core functionality
│   │   ├── models.py              # Pydantic models
│   │   ├── aws_client.py          # AWS client wrapper
│   │   └── __init__.py
│   ├── cli/                       # CLI commands
│   │   ├── export.py              # Export command
│   │   ├── deploy.py              # Deploy command
│   │   └── __init__.py
│   └── __init__.py
├── tests/                         # Test suite
│   ├── test_models.py            # Model tests
│   ├── test_aws_client.py        # Client tests
│   └── __init__.py
├── pyproject.toml                # Project configuration
└── README.md                     # This file

Running Tests

# Run all tests
uv run pytest

# Run tests with coverage
uv run pytest --cov=quicksight_quickstart --cov-report=html

# Run specific test file
uv run pytest tests/test_models.py

# Run with verbose output
uv run pytest -v

Code Quality

# Format code
uv run ruff format

# Lint code
uv run ruff check

# Type checking
uv run mypy quicksight_quickstart

Key Design Patterns

• Type Safety: Full type hints with mypy validation
• Functional Programming: Immutable data classes and pure functions
• Error Handling: Comprehensive exception handling with user-friendly messages
• Performance: Uses functools.lru_cache and __slots__ for optimization
• Modern Python: Uses latest language features and best practices

Prerequisites

Required Tools

• Python 3.9+: Modern Python runtime
• UV: Fast Python package manager (install guide)
• AWS CLI: Configured with appropriate permissions
• PostgreSQL Client (psql): For database operations

AWS Permissions

Your AWS credentials need permissions for:

• CloudFormation: Stack management (create/update/delete)
• QuickSight: Resource management (dashboards, analyses, datasets)
• RDS: Database instance management
• VPC: Network resource management
• S3: Bucket and object operations
• IAM: Role creation for QuickSight

Configuration

Environment Variables

export AWS_REGION="us-west-2"
export AWS_PROFILE="my-profile"
export ENVIRONMENT="production"
export DB_PASSWORD="secure-password-123"

AWS Profile Setup

# Configure AWS CLI
aws configure --profile quicksight-dev

# Use specific profile
quicksight-export --profile quicksight-dev
quicksight-deploy --profile quicksight-dev

Advanced Usage

Custom Data Sources

1. Modify Database Schema:

   # Edit setup-database.sh to add your tables
   vim setup-database.sh

2. Update CloudFormation Template:

   # Export existing resources first
   quicksight-export -o ./custom-exports
   
   # Modify the generated template
   vim ./custom-exports/quicksight-export-*.yaml
   
   # Deploy with custom template
   quicksight-deploy -t ./custom-exports/quicksight-export-*.yaml

Multi-Environment Deployments

# Development environment
quicksight-deploy -e dev --db-password dev-pass-123

# Staging environment
quicksight-deploy -e staging --db-password staging-pass-123

# Production environment
quicksight-deploy -e prod --db-password prod-pass-123

Selective Deployment

# Deploy only infrastructure
quicksight-deploy --skip-quicksight --skip-permissions

# Deploy only QuickSight resources
quicksight-deploy --skip-infrastructure --skip-database-setup

# Update permissions only
quicksight-deploy --skip-infrastructure --skip-database-setup --skip-quicksight

Troubleshooting

Common Issues

1. QuickSight Not Signed Up:

   Error: Access denied to QuickSight
   

   Solution: Sign up for QuickSight Enterprise in AWS Console

2. Missing Dependencies:

   Error: psql command not found
   

   Solution: Install PostgreSQL client tools

3. Permission Errors:

   Error: User is not authorized to perform quicksight:ListDashboards
   

   Solution: Add QuickSight permissions to your IAM user/role

4. Region Mismatch:

   Error: Stack does not exist
   

   Solution: Ensure consistent AWS region across all commands

Debug Mode

# Enable verbose logging
export AWS_CLI_DEBUG=1

# Run with detailed output
quicksight-export --list-resources -v
quicksight-deploy -e test --debug