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

Environment-Based Connection Selection:

• Same CoginitiScript code runs across all environments
• Connection determined by environment selected in the editor
• Transparent switching when you change environments
• No special syntax required in your CoginitiScript

How Connection Overrides Work

When you configure an environment in your TOML manifest, you specify which connection to use. When you select that environment in the editor and run your CoginitiScript, it automatically executes against that connection.

Example Configuration:

[environment.dev]
name = "Development"
connection = { name="dev-postgres-local" }

[environment.staging]
name = "Staging"
connection = { name="staging-postgres-cluster" }

[environment.prod]
name = "Production"
connection = { name="prod-postgres-cluster" }

Using Connection Overrides

Write Standard CoginitiScript

Your CoginitiScript doesn't need special syntax. Write queries using standard SQL:

-- Standard SQL query works across all environments
-- Connection determined by selected environment
SELECT customer_id, order_total
FROM orders
WHERE order_date >= CURRENT_DATE - INTERVAL '30 days';

-- Analytics query
WITH sales_summary AS (
  SELECT region, SUM(sales) as total_sales
  FROM sales_data
  GROUP BY region
)
SELECT * FROM sales_summary;

Switch Environments

1. Select environment from the connection dropdown in the editor
2. Execute your script - runs against that environment's connection
3. Switch to different environment to run against different connection
4. Compare results across environments

Multi-Environment Projects

Development, Staging, and Production

Configure multiple environments that use different connections:

[environment]
default = "dev"

[environment.dev]
name = "Development"
connection = { name="PostgreSQL Dev Server" }

[environment.staging]
name = "Staging"
connection = { name="PostgreSQL Staging Server" }

[environment.prod]
name = "Production"
connection = { name="PostgreSQL Production Server" }

Workflow:

1. Develop using the development environment
2. Test by switching to staging environment
3. Deploy by switching to production environment
4. Same queries run against appropriate connection for each environment

Schema Overrides

Schema Override Concepts

Schema overrides enable the same CoginitiScript to execute against different schemas while maintaining code consistency. When you configure a schema override in your environment, all queries executed in that environment automatically use the specified schema.

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

Schema overrides are configured in your TOML manifest using the overrides parameter:

Single Schema Override:

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

When this environment is selected, all unqualified table references in your queries will use the dev_analytics schema.

Schema Override Example:

[environment]
default = "dev"

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

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

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

How Schema Overrides Work

Your CoginitiScript uses standard SQL without special syntax. The environment's schema override determines which schema your queries execute against:

-- Standard SQL query
-- Schema determined by selected environment
CREATE OR REPLACE TABLE 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 raw_orders
WHERE order_date >= CURRENT_DATE - INTERVAL '1 day';

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

When running in different environments:

• Development environment: Queries use dev_analytics.raw_orders, dev_analytics.clean_orders, etc.
• Staging environment: Queries use staging_analytics.raw_orders, staging_analytics.clean_orders, etc.
• Production environment: Queries use analytics.raw_orders, analytics.clean_orders, etc.

Environment-Specific Schema Examples

Development Schema Configuration

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

Benefits:

• Isolated development data
• Safe for experimentation
• Fast execution with smaller datasets
• Testing without affecting production

Production Schema Configuration

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

Benefits:

• Live data processing
• Optimized for performance
• Structured for business use
• Production-grade reliability

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

Different environments may require different performance characteristics. You can manage this through your environment configuration and by maintaining separate query versions when needed.

Resource Management Strategies:

• Connection pooling - Configure connection pools appropriate for each environment's usage patterns
• Query timeouts - Set environment-specific timeout values based on expectations (faster for dev, longer for prod)
• Memory allocation - Optimize database configuration for environment data volumes
• Concurrency limits - Prevent resource contention with appropriate limits per environment

Development Environment:

• Smaller datasets for faster feedback
• Shorter query timeouts
• Lower resource allocation

Production Environment:

• Full datasets for accurate analysis
• Longer query timeouts for complex operations
• Optimized resource allocation for performance

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.