Configuration File Reference

This page provides a complete reference for all configuration options available in the pg_ai_query extension configuration file.

Configuration File Location

The configuration file must be placed at:

~/.pg_ai.config

File Format

The configuration uses INI format with sections and key-value pairs:

# Comments start with # and are ignored
[section_name]
key = value
key_with_quotes = "value with spaces"

Complete Configuration Template

# PG AI Query Configuration File
# Place this file at ~/.pg_ai.config

[general]
# Logging configuration
log_level = "INFO"
enable_logging = false
enable_postgresql_elog = true

# Request configuration
request_timeout_ms = 30000
max_retries = 3

[query]
# Query generation behavior
enforce_limit = true
default_limit = 1000

[openai]
# OpenAI provider configuration
api_key = ""
default_model = "gpt-4o"

[anthropic]
# Anthropic provider configuration
api_key = ""
default_model = "claude-3-5-sonnet-20241022"

Configuration Sections

[general] Section

Controls general extension behavior and logging.

log_level

Controls the verbosity of log messages.

Values:

• "DEBUG": Most verbose, includes all internal operations
• "INFO": General information about operations
• "WARNING": Warnings about potential issues
• "ERROR": Only error messages

Example:

[general]
log_level = "DEBUG"  # Show all log messages

enable_logging

Master switch for all logging output.

Values:

• true: Enable logging (respects log_level)
• false: Disable all logging output

Example:

[general]
enable_logging = true  # Turn on logging
log_level = "INFO"     # Show INFO level and above

enable_postgresql_elog

Controls whether to use PostgreSQL’s internal logging system.

Values:

• true: Use PostgreSQL’s elog system (recommended)
• false: Use alternative logging method

Example:

[general]
enable_postgresql_elog = true  # Use PostgreSQL logging

request_timeout_ms

Timeout for AI API requests in milliseconds.

Range: 1000-300000 (1 second to 5 minutes) Recommended: 30000-60000 for most use cases

Example:

[general]
request_timeout_ms = 45000  # 45 second timeout

max_retries

Maximum number of retry attempts for failed API requests.

Range: 0-10 Recommended: 3-5 for production use

Example:

[general]
max_retries = 5  # Retry up to 5 times

[query] Section

Controls query generation behavior and safety features.

enforce_limit

Controls whether SELECT queries automatically include LIMIT clauses.

Values:

• true: Always add LIMIT to SELECT queries (recommended for safety)
• false: Allow unlimited SELECT queries

Example:

[query]
enforce_limit = true    # Always limit query results
default_limit = 500     # Default to 500 rows

default_limit

Default number of rows to limit when no explicit limit is requested.

Range: 1-1000000 Recommended: 100-5000 depending on use case

Example:

[query]
default_limit = 2000  # Default to 2000 rows

[openai] Section

Configuration for OpenAI provider.

api_key

Your OpenAI API key from platform.openai.com.

Format: Must start with sk- or sk-proj- Security: Keep this key secure and never commit to version control

Example:

[openai]
api_key = "sk-proj-abc123..."  # Your actual API key

default_model

Default OpenAI model to use for query generation.

Available Models:

• "gpt-4o": Latest GPT-4 Omni model (recommended)
• "gpt-4": Standard GPT-4 model
• "gpt-3.5-turbo": Fast and economical model

Example:

[openai]
default_model = "gpt-4o"  # Use latest model

[anthropic] Section

Configuration for Anthropic (Claude) provider.

api_key

Your Anthropic API key from console.anthropic.com.

Format: Must start with sk-ant- Security: Keep this key secure and never commit to version control

Example:

[anthropic]
api_key = "sk-ant-abc123..."  # Your actual API key

default_model

Default Anthropic model to use for query generation.

Available Models:

• "claude-3-5-sonnet-20241022": Latest Claude 3.5 Sonnet model

Example:

[anthropic]
default_model = "claude-3-5-sonnet-20241022"  # Use Claude 3.5 Sonnet

Configuration Examples

Development Configuration

# Development setup with detailed logging
[general]
log_level = "DEBUG"
enable_logging = true
enable_postgresql_elog = true
request_timeout_ms = 60000  # Longer timeout for debugging
max_retries = 2             # Fewer retries for faster feedback

[query]
enforce_limit = true
default_limit = 100         # Small limit for testing

[openai]
api_key = "sk-proj-dev-key-here"
default_model = "gpt-3.5-turbo"  # Cheaper for development

Production Configuration

# Production setup optimized for performance and reliability
[general]
log_level = "WARNING"
enable_logging = false      # Disable for performance
enable_postgresql_elog = true
request_timeout_ms = 30000
max_retries = 5             # More retries for reliability

[query]
enforce_limit = true
default_limit = 1000

[openai]
api_key = "sk-proj-prod-key-here"
default_model = "gpt-4"     # Good balance of quality and cost

Multi-Provider Configuration

# Setup with both providers for redundancy
[general]
log_level = "INFO"
enable_logging = true
request_timeout_ms = 45000
max_retries = 3

[query]
enforce_limit = true
default_limit = 500

[openai]
api_key = "sk-proj-openai-key-here"
default_model = "gpt-4o"

[anthropic]
api_key = "sk-ant-anthropic-key-here"
default_model = "claude-3-5-sonnet-20241022"

# Extension will use OpenAI first (first configured)
# Falls back to Anthropic if OpenAI fails

High-Performance Configuration

# Optimized for speed and low cost
[general]
log_level = "ERROR"         # Minimal logging
enable_logging = false
request_timeout_ms = 15000  # Shorter timeout
max_retries = 2             # Fewer retries

[query]
enforce_limit = true
default_limit = 200         # Smaller default limit

[openai]
api_key = "sk-proj-key-here"
default_model = "gpt-3.5-turbo"  # Fastest model

Configuration Validation

File Format Validation

The extension validates:

• INI Format: Proper section headers and key-value pairs
• Required Quotes: String values with spaces must be quoted
• Section Names: Only valid section names are accepted
• Key Names: Only valid configuration keys are recognized

Value Validation

Each configuration value is validated:

• Type Checking: Strings, integers, and booleans are validated
• Range Checking: Numeric values must be within acceptable ranges
• Format Checking: API keys must match expected formats
• Model Validation: Model names must be supported

Error Handling

Configuration errors are reported with specific messages:

Configuration Error: Invalid log_level 'VERBOSE' in section [general]. Valid values are: DEBUG, INFO, WARNING, ERROR
Configuration Error: request_timeout_ms must be between 1000 and 300000, got 500000
Configuration Error: OpenAI API key must start with 'sk-' or 'sk-proj-'

Configuration File Only

Currently, only configuration files are supported. All settings must be specified in ~/.pg_ai.config.

Security Considerations

File Permissions

Set secure permissions on the configuration file:

# Make file readable only by owner
chmod 600 ~/.pg_ai.config

# Verify permissions
ls -la ~/.pg_ai.config
# Should show: -rw------- 1 user user ...

API Key Security

• Never commit configuration files with API keys to version control
• Use secure configuration files in containerized or CI/CD environments
• Rotate keys regularly as per your organization’s security policy
• Monitor usage through your AI provider’s dashboard

Configuration Templates

Use template files for version control:

# .pg_ai.config.template
[general]
log_level = "INFO"
enable_logging = false

[openai]
api_key = "${OPENAI_API_KEY}"  # Replace with actual key
default_model = "gpt-4o"

[anthropic]
api_key = "${ANTHROPIC_API_KEY}"  # Replace with actual key

Configuration Loading Order

The extension loads configuration in this order:

1. Default values (hardcoded)
2. Configuration file (~/.pg_ai.config)

This provides a simple and secure configuration approach.