IO Config Setup Guide
The io_config
file is a crucial configuration file in Mage that stores credentials and connection information for accessing various data sources. This guide will help you understand where to store it and how to create it from scratch.
File Location
The io_config
file should be stored in your Mage project’s root directory. The default path is:
your_mage_project/
└── default_repo/
└── io_config.yaml
Creating a New io_config File
1. Basic Structure
Create a new file named io_config.yaml
in your project’s default_repo
directory with the following basic structure:
version: 0.1.1 # Optional but recommended
default:
# Your default profile configuration here
Mage supports two formats for the io_config
file:
version: 0.1.1
default:
# PostgreSQL configuration
POSTGRES_DBNAME: your_database
POSTGRES_USER: your_username
POSTGRES_PASSWORD: your_password
POSTGRES_HOST: your_host
POSTGRES_PORT: 5432
# Snowflake configuration
SNOWFLAKE_USER: your_username
SNOWFLAKE_PASSWORD: your_password
SNOWFLAKE_ACCOUNT: your_account
SNOWFLAKE_DEFAULT_WH: your_warehouse
SNOWFLAKE_DEFAULT_DB: your_database
SNOWFLAKE_DEFAULT_SCHEMA: your_schema
# AWS configuration
AWS_ACCESS_KEY_ID: "{{ env_var('AWS_ACCESS_KEY_ID') }}"
AWS_SECRET_ACCESS_KEY: "{{ env_var('AWS_SECRET_ACCESS_KEY') }}"
AWS_REGION: your_region
default:
PostgreSQL:
database: your_database
user: your_username
password: your_password
host: your_host
port: 5432
AWS:
region: your_region
Redshift:
database: your_redshift_database
port: 5439
3. Using Environment Variables
For security, it’s recommended to use environment variables for sensitive information:
version: 0.1.1
default:
POSTGRES_PASSWORD: "{{ env_var('POSTGRES_PASSWORD') }}"
SNOWFLAKE_PASSWORD: "{{ env_var('SNOWFLAKE_PASSWORD') }}"
4. Multiple Profiles
You can create multiple profiles for different environments or use cases:
version: 0.1.1
default:
# Default profile configuration
POSTGRES_DBNAME: production_db
development:
# Development environment configuration
POSTGRES_DBNAME: development_db
staging:
# Staging environment configuration
POSTGRES_DBNAME: staging_db
Using io_config in Your Code
Python Block Example
from mage_ai.settings.repo import get_repo_path
from mage_ai.io.config import ConfigFileLoader
from mage_ai.io.postgres import Postgres
from os import path
@data_loader
def load_data_from_postgres(**kwargs):
query = 'SELECT * FROM your_table'
config_path = path.join(get_repo_path(), 'io_config.yaml')
config_profile = 'default' # or any other profile name
with Postgres.with_config(ConfigFileLoader(config_path, config_profile)) as loader:
return loader.load(query)
SQL Block Example
In SQL blocks, you can select the desired IO Config profile from the UI using the “Profile” dropdown menu.
Best Practices
-
Security:
- Never commit sensitive credentials directly in the
io_config
file
- Use environment variables for sensitive information
- Consider using a secrets management service for production environments
-
Organization:
- Use meaningful profile names
- Group related configurations together
- Document any non-standard configurations
- Use the standard format for new configurations
-
Version Control:
- Add
io_config.yaml
to your .gitignore
file
- Provide a template file (
io_config.yaml.template
) with dummy values
- Document the required environment variables
Troubleshooting
If you encounter issues with your io_config
:
- Verify the file is in the correct location (
default_repo/io_config.yaml
)
- Check that all required fields are present
- Ensure environment variables are properly set
- Validate the YAML syntax
- Check the connection credentials
- Verify you’re using the correct configuration format (standard or verbose)
Additional Resources
Responses are generated using AI and may contain mistakes.