CoginitiScript: Configuring Runtime Environments

This guide explains how to set up and manage CoginitiScript runtime environments, which allow project owners to define multiple named environments with specific connection and schema overrides for flexible project execution across development, staging, and production contexts.

Overview

CoginitiScript Runtime Environments provide a powerful way to manage different execution contexts for your projects through TOML configuration files. This feature enables you to define multiple named environments within a single project, each with its own connection references and platform-specific overrides such as schema settings.

Key Benefits

Environment Flexibility:

• Multiple named environments per project (development, staging, production)
• Connection references - Reference existing connections by name
• Platform-specific overrides - Schema, database, and other connection parameters
• Default environment selection - Automatic environment selection when opening project assets

Editor Integration:

• Environment selection - Choose environments directly in the editor connection dropdown
• Visual indicators - Tab colors match the selected environment's connection
• Override indicators - Visual feedback when custom overrides are applied
• Quick reset - Easily reset to default environment settings

Project Management:

• TOML-based configuration - Version-controlled environment definitions
• Connection validation - Error handling for missing or renamed connections
• Test execution - Run tests against specific environments
• Consistent execution - Same CoginitiScript code across all environments

Understanding Runtime Environments

Environment Concepts

Project Manifest Configuration

Runtime environments are defined in your project's TOML manifest file, which serves as the central configuration for all environment settings.

TOML-Based Definition:

• Version-controlled configuration - Environment settings stored with project code
• Named environment sections - Each environment defined with unique identifier
• Connection references - Environments reference existing connections by name
• Platform-specific overrides - Schema and other connection parameter overrides

Environment Components

Environment Identifier:

• Unique ID - Short identifier used in TOML configuration (e.g., "dev", "prod")
• Display name - Human-readable name shown in the editor interface
• Default designation - One environment marked as project default

Connection Reference:

• Connection name - References existing Coginiti connection by name
• Override parameters - Platform-specific parameter overrides (schema, database, etc.)
• Validation - Error handling when referenced connections don't exist

Editor Integration:

• Connection dropdown - Environments appear as separate group in connection selector
• Tab coloring - Editor tabs use connection color for visual environment identification
• Override indicators - Visual feedback when custom overrides are applied

Environment Inheritance

Default Environment

Automatic Selection:

• Primary environment used when no specific environment specified
• Fallback configuration for undefined environment references
• Base settings inherited by other environments

Configuration Priority:

1. Explicitly specified environment - User-selected environment
2. Project default environment - Project owner-defined default
3. System default - Platform-level default configuration

Environment Hierarchy

Inheritance Model:

• Base configuration from project settings
• Environment-specific overrides for connections and schemas
• User-level preferences for execution options

Setting Up Runtime Environments

TOML Configuration File

Runtime environments are configured through your project's TOML manifest file. This file defines all environments, their connection references, and platform-specific overrides.

Basic TOML Structure

[environment]
default = "dev"

[environment.dev]
name = "Development"
connection = { name="My Development Connection", overrides={ schema="dev_schema" } }

[environment.prod]
name = "Production"
connection = { name="My Production Connection", overrides={ schema="prod_schema" } }

TOML Configuration Elements

Environment Section Header:

[environment]
default = "dev"  # Specifies which environment is the project default

Individual Environment Definition:

[environment.dev]
name = "Display Name"
connection = { name="Connection Name", overrides={ key="value", key2="value2" } }

Configuration Parameters:

• environment_id - Unique identifier for the environment (e.g., "dev", "prod")
• name - Human-readable name displayed in the editor interface
• connection.name - Name of existing Coginiti connection to reference
• connection.overrides - Platform-specific parameter overrides

Environment Configuration Examples

Multi-Environment Project Configuration

[environment]
default = "dev"

[environment.dev]
name = "Development"
connection = { name="PostgreSQL Dev", overrides={ schema="dev_analytics" } }

[environment.staging]
name = "Staging"
connection = { name="PostgreSQL Staging", overrides={ schema="staging_analytics" } }

[environment.prod]
name = "Production"
connection = { name="PostgreSQL Production", overrides={ schema="prod_analytics" } }

Same Connection, Different Schemas

[environment]
default = "dev"

[environment.dev]
name = "Development"
connection = { name="Company Data Warehouse", overrides={ schema="dev" } }

[environment.prod]
name = "Production"
connection = { name="Company Data Warehouse", overrides={ schema="production" } }

Cross-Platform Environment Setup

[environment]
default = "local"

[environment.local]
name = "Local Development"
connection = { name="Local PostgreSQL", overrides={ schema="dev_schema", database="local_dev" } }

[environment.cloud]
name = "Cloud Production"
connection = { name="Snowflake Production", overrides={ schema="ANALYTICS", database="PROD_DW" } }

Connection Overrides

Understanding Connection Overrides

Connection overrides allow you to specify different database connections for different environments while maintaining the same CoginitiScript code.

Override Mechanisms

Connection Mapping:

• Logical connection names in CoginitiScript remain constant
• Physical connections vary by environment
• Transparent switching without code changes

Example Override Configuration:

CoginitiScript Reference: @connection.primary
  - Development: maps to dev-postgres-local
  - Staging: maps to staging-postgres-cluster  
  - Production: maps to prod-postgres-cluster

CoginitiScript Reference: @connection.warehouse
  - Development: maps to dev-snowflake-trial
  - Staging: maps to staging-snowflake-cluster
  - Production: maps to prod-snowflake-cluster

Configuring Connection Overrides

Step 1: Define Logical Connections

In your CoginitiScript, use logical connection references:

-- CoginitiScript with logical connection references
{{% connection = @connection.primary %}}
{{% warehouse = @connection.warehouse %}}

-- Query using logical connections
SELECT customer_id, order_total
FROM {{% connection %}}.orders
WHERE order_date >= CURRENT_DATE - INTERVAL '30 days';

-- Cross-connection analysis
WITH warehouse_summary AS (
  SELECT region, SUM(sales) as total_sales
  FROM {{% warehouse %}}.sales_summary
  GROUP BY region
)
SELECT * FROM warehouse_summary;

Step 2: Map Connections by Environment

Configure environment-specific connection mappings:

Development Environment:

Connection Mappings:
  @connection.primary → dev-local-postgres
  @connection.warehouse → dev-snowflake-trial
  @connection.archive → dev-s3-bucket

Production Environment:

Connection Mappings:
  @connection.primary → prod-postgres-cluster
  @connection.warehouse → prod-snowflake-enterprise
  @connection.archive → prod-s3-warehouse

Step 3: Test Environment Switching

1. Execute script in development environment
2. Switch to production environment
3. Execute same script against production connections
4. Compare results and validate environment isolation

Advanced Connection Patterns

Multi-Database Environments

Cross-Platform Integration:

Environment: production
Connection Mappings:
  @connection.operational → postgres-prod-cluster
  @connection.analytics → snowflake-prod-warehouse  
  @connection.archive → s3-production-bucket
  @connection.cache → redis-prod-cluster

Usage in CoginitiScript:

-- Operational data extraction
{{% operational_data = @connection.operational %}}
SELECT * FROM {{% operational_data %}}.customer_orders;

-- Analytics processing
{{% analytics_db = @connection.analytics %}}
CREATE OR REPLACE TABLE {{% analytics_db %}}.customer_summary AS
SELECT customer_id, SUM(order_total) as lifetime_value
FROM {{% operational_data %}}.customer_orders
GROUP BY customer_id;

-- Archive results
{{% archive_location = @connection.archive %}}
COPY INTO {{% archive_location %}}/customer_summaries/
FROM {{% analytics_db %}}.customer_summary;

Schema Overrides

Schema Override Concepts

Schema overrides enable the same CoginitiScript to execute against different schemas while maintaining code consistency.

Schema Mapping Strategies

Environment-Based Schemas:

• Development schemas with test data and experimental structures
• Staging schemas with production-like data for validation
• Production schemas with live data and finalized structures

Use Case-Based Schemas:

• Raw data schemas for initial data ingestion
• Processed data schemas for cleaned and transformed data
• Analytics schemas for aggregated and business-ready data

Configuring Schema Overrides

Basic Schema Configuration

Single Schema Override:

Environment: development
Schema Configuration:
  default: dev_analytics
  
CoginitiScript Usage:
  - All unqualified table references use dev_analytics
  - Explicit schema references remain unchanged

Multiple Schema Overrides:

Environment: production  
Schema Configuration:
  default: prod_analytics
  raw: prod_raw_data
  processed: prod_processed_data
  archive: prod_archive

Schema Reference Patterns

Logical Schema References:

-- CoginitiScript with logical schema references
{{% schema.raw = @schema.raw %}}
{{% schema.processed = @schema.processed %}}
{{% schema.analytics = @schema.default %}}

-- ETL pipeline using schema references
CREATE OR REPLACE TABLE {{% schema.processed %}}.clean_orders AS
SELECT 
    order_id,
    customer_id,
    CASE 
        WHEN order_status = 'COMPLETE' THEN 'completed'
        WHEN order_status = 'CANCEL' THEN 'cancelled'
        ELSE 'pending'
    END as status,
    order_total
FROM {{% schema.raw %}}.raw_orders
WHERE order_date >= CURRENT_DATE - INTERVAL '1 day';

-- Analytics aggregation
CREATE OR REPLACE TABLE {{% schema.analytics %}}.daily_sales AS
SELECT 
    DATE(order_date) as sales_date,
    COUNT(*) as order_count,
    SUM(order_total) as total_revenue
FROM {{% schema.processed %}}.clean_orders  
WHERE status = 'completed'
GROUP BY DATE(order_date);

Environment-Specific Schema Examples

Development Schema Strategy

Environment: development
Schema Overrides:
  default: dev_analytics
  raw: dev_raw (contains sample data)
  processed: dev_processed  
  testing: dev_testing (for unit tests)
  
Benefits:
  - Isolated development data
  - Safe for experimentation
  - Fast execution with smaller datasets

Production Schema Strategy

Environment: production
Schema Overrides:
  default: analytics
  raw: raw_data
  processed: processed_data
  archive: historical_archive
  reporting: business_reporting
  
Benefits:
  - Live data processing
  - Optimized for performance
  - Structured for business use

Using Runtime Environments

Environment Selection in Editor

Runtime environments are selected through the editor's connection dropdown, which displays environments as a separate grouped section.

Connection Dropdown Interface

When you open a project asset, the connection dropdown shows:

=== Project Environments ===
[Platform Icon] Development
[Platform Icon] Staging  
[Platform Icon] Production
=== Connections ===
[Platform Icon] My PostgreSQL Connection
[Platform Icon] My Snowflake Connection

Visual Environment Indicators

Tab Coloring:

• Editor tabs display in the color of the selected environment's connection
• Color consistency with direct connection selection behavior
• Visual environment identification at a glance

Override Indicators:

• Modification indicator icon appears when overrides differ from defaults
• Reset control allows quick return to default environment settings
• Clear visual feedback for custom configuration states

Automatic Environment Selection

Default Environment Loading:

1. Project default environment loads automatically when opening assets
2. Connection and overrides applied transparently
3. Tab coloring matches environment's connection
4. Ready for immediate execution with environment settings

Running Tests with Environments

Project tests can be executed against specific environments, allowing you to validate your CoginitiScript across different data sources and configurations.

Test Execution Context Menu

Environment Options in Context Menu:

• Individual environments listed as separate menu options
• Quick test execution against chosen environment
• Environment grouping - More than 3 environments collapsed into submenu

Test Execution Process:

1. Right-click project in catalog tree
2. Select "Run Tests" or specific environment option
3. Choose target environment if multiple options available
4. Tests execute with selected environment's connection and overrides
5. Results show environment-specific validation

Test Environment Strategies

Environment-Specific Test Data:

[environment.testing]
name = "Test Environment"
connection = { name="Test Database", overrides={ schema="test_data" } }

Benefits of Environment Testing:

• Validate schema compatibility across different environments
• Test data transformation logic with environment-specific data
• Verify connection overrides work correctly
• Environment-specific validation of business logic

Connection Validation and Error Handling

Missing Connection Detection

When an environment references a connection that doesn't exist, Coginiti provides clear error feedback.

Error Scenarios:

• Connection name typo in TOML configuration
• Connection renamed after environment configuration
• Connection deleted from Coginiti platform
• Permission changes affecting connection access

Error Display:

• Editor tab error indicator when environment cannot be resolved
• Clear error message identifying missing connection
• Suggestion to check TOML configuration
• Prevents query execution until resolved

Managing Multiple Environments

Environment Lifecycle Management

Environment Creation Workflow

1. Planning Phase - Define environment purpose and requirements
2. Configuration Phase - Set up connections, schemas, and parameters
3. Testing Phase - Validate environment configuration
4. Documentation Phase - Document environment usage and restrictions
5. Deployment Phase - Make environment available to project users

Environment Maintenance

Regular Maintenance Tasks:

• Connection validation - Ensure environment connections remain valid
• Schema updates - Keep schema overrides current with data changes
• Permission reviews - Verify environment access remains appropriate
• Performance monitoring - Track environment usage and performance

Environment Decommissioning

Safe Removal Process:

1. Usage analysis - Identify scripts and users dependent on environment
2. Migration planning - Plan transition to alternative environments
3. Notification - Inform users of environment removal timeline
4. Gradual removal - Phase out environment usage
5. Final cleanup - Remove environment configuration and documentation

Environment Access Control

Project-Level Permissions

Environment Visibility:

• Project owners can create, modify, and delete environments
• Project editors can use existing environments
• Project viewers can see environment configurations but not execute

Environment-Specific Access:

• Development environments - Broad access for team development
• Staging environments - Limited access for testing and validation
• Production environments - Restricted access with approval workflows

User Environment Preferences

Personal Environment Settings:

• Default environment preference per user
• Environment shortcuts for frequently used environments
• Environment switching interface in user workspace

Best Practices for Environment Management

Environment Naming Conventions

Descriptive Names:

• Use clear, descriptive names that indicate environment purpose
• Follow consistent patterns across projects and teams
• Include context indicators (dev, test, prod, staging)
• Avoid technical abbreviations that may confuse users

Example Naming Patterns:

Pattern: {purpose}-{data-type}-{region}
Examples:
  - development-analytics-us
  - production-reporting-eu
  - testing-etl-global
  - staging-ml-experiments

Configuration Documentation

Environment Documentation:

• Purpose and scope of each environment
• Data sources and connections used
• Schema configurations and mappings
• Usage guidelines and restrictions
• Access requirements and approval processes

Change Management:

• Document all environment changes with rationale
• Version control environment configurations
• Communication plan for environment updates
• Rollback procedures for configuration issues

Security Considerations

Environment Isolation:

• Separate credentials for each environment
• Network isolation where appropriate
• Data classification alignment with environment access
• Audit logging for environment usage and changes

Access Controls:

• Principle of least privilege for environment access
• Regular access reviews and permission audits
• Multi-factor authentication for production environments
• Session management and timeout policies

Troubleshooting Runtime Environments

Common Configuration Issues

TOML Syntax Errors

Symptoms: Environment configuration not loading or parsing errors

Solutions:

1. Validate TOML syntax using online TOML validators
2. Check quotation marks around strings with spaces
3. Verify bracket notation for nested sections
4. Ensure proper indentation and structure

Missing Connection References

Symptoms: Editor tab shows error when selecting environment

Solutions:

1. Check connection name spelling in TOML configuration
2. Verify connection exists in Coginiti connections list
3. Update connection reference if connection was renamed
4. Test connection accessibility from current user account

Override Parameter Issues

Symptoms: Environment loads but overrides don't take effect

Solutions:

1. Verify override syntax in TOML configuration
2. Check platform-specific parameters (schema, database names)
3. Validate parameter names match connection platform requirements
4. Test overrides with simple queries to verify schema/database access

Practical Configuration Example

Complete Project Setup

Here's a real-world example of setting up environments for a typical analytics project:

Project Structure:

analytics-project/
├── manifest.toml
├── queries/
│   ├── daily-reports.sql
│   └── monthly-summary.sql
└── tests/
    └── data-quality-tests.sql

manifest.toml Configuration:

[environment]
default = "dev"

[environment.dev]
name = "Development"
connection = { name="Dev PostgreSQL", overrides={ schema="dev_analytics" } }

[environment.staging]  
name = "Staging"
connection = { name="Staging PostgreSQL", overrides={ schema="staging_analytics" } }

[environment.prod]
name = "Production"  
connection = { name="Production PostgreSQL", overrides={ schema="analytics" } }

Workflow Example

Development Workflow:

1. Open project asset - Development environment loads automatically
2. Tab shows dev connection color - Visual confirmation of environment
3. Execute queries - Runs against dev_analytics schema
4. Switch to staging - Select from connection dropdown
5. Run tests - Right-click project → Run Tests → Staging
6. Deploy to production - Switch environment and validate

Query Execution:

-- Same query works across all environments
-- Schema determined by environment configuration
SELECT 
    date_column,
    SUM(revenue) as total_revenue
FROM sales_data  -- Resolves to dev_analytics.sales_data in dev environment
WHERE date_column >= CURRENT_DATE - INTERVAL '30 days'
GROUP BY date_column
ORDER BY date_column;

Performance Optimization

Environment-Specific Optimization

Query Performance Tuning:

-- Environment-specific performance settings
{{% env = @environment.name %}}

{% if env == "production" %}
    -- Production optimizations
    SET statement_timeout = '10min';
    SET work_mem = '256MB';
    SET effective_cache_size = '4GB';
{% elif env == "development" %}
    -- Development settings for faster feedback
    SET statement_timeout = '2min';
    SET work_mem = '64MB';
{% endif %}

Resource Management

Environment Resource Allocation:

• Connection pooling appropriate for environment usage
• Query timeouts based on environment expectations
• Memory allocation optimized for environment data volumes
• Concurrency limits to prevent resource contention

Summary

You have successfully mastered CoginitiScript Runtime Environments! Key achievements:

✅ TOML Configuration: Version-controlled environment definitions in project manifest files ✅ Connection References: Environment-specific connection mapping with platform overrides ✅ Editor Integration: Environment selection through connection dropdown with visual indicators ✅ Test Execution: Environment-specific test running with context menu options ✅ Error Handling: Clear validation and error messages for missing connections ✅ Best Practices: Practical configuration examples and troubleshooting guidance

Your CoginitiScript projects now support flexible, environment-aware execution through TOML configuration that enables seamless code promotion across development, staging, and production environments while maintaining consistent code and clear visual feedback in the editor interface.