# Configuration Reference

Complete guide to the `prax.toml` configuration file.

## Overview

The `prax.toml` file is the central configuration for your Prax ORM project. It controls database connections, code generation, migrations, seeding, and debugging behavior.

📍 Location: Place `prax.toml` in your project's root directory.

## Minimal Configuration

At minimum, you only need to specify your database provider and connection URL:

## Complete Example

Here's a fully-documented configuration file showing all available options:

## Database Configuration

### [database]

Configure your database connection and connection pool settings.

Option | Type | Default | Description
--- | --- | --- | ---
`provider` | string | `"postgresql"` | Database provider (see supported providers below)
`url` | string | — | Connection URL (supports `${{ '{' }}VAR{{ '}' }}` interpolation)

### Supported Database Providers

Provider | Aliases | URL Format
--- | --- | ---
`"postgresql"` | `"postgres"` | `postgresql://user:pass@host:5432/db`
`"mysql"` | — | `mysql://user:pass@host:3306/db`
`"sqlite"` | `"sqlite3"` | `sqlite:./path/to/db.sqlite`
`"mongodb"` | `"mongo"` | `mongodb://user:pass@host:27017/db`

### Connection URL Examples

## Connection Pool

### [database.pool]

Fine-tune connection pool behavior for optimal performance.

Option | Type | Default | Description
--- | --- | --- | ---
`min_connections` | integer | `2` | Minimum idle connections to maintain
`max_connections` | integer | `10` | Maximum connections in the pool
`connect_timeout` | duration | `"30s"` | Timeout for establishing new connections
`idle_timeout` | duration | `"10m"` | Close connections idle longer than this
`max_lifetime` | duration | `"30m"` | Maximum lifetime of any connection

⚠️ Duration Format: Use strings with units: `"30s"` (seconds), `"10m"` (minutes), `"1h"` (hours). Numbers without units will cause errors.

## Environment Variables

Prax supports environment variable interpolation using the `${{ '{' }}VAR_NAME{{ '}' }}` syntax. This is the recommended way to manage sensitive values like database credentials.

### .env File Example

🔒 Security: Never commit your `.env` file to version control. Add it to `.gitignore`.

## Schema Configuration

### [schema]

Configure where your schema file is located.

Option | Type | Default | Description
--- | --- | --- | ---
`path` | string | `"schema.prax"` | Path to your schema file (relative to project root)

## Generator Configuration

### [generator.client]

Control how Prax generates your Rust client code.

Option | Type | Default | Description
--- | --- | --- | ---
`output` | string | `"./src/generated"` | Output directory for generated code
`async_client` | boolean | `true` | Generate async client (using tokio)
`tracing` | boolean | `false` | Add tracing instrumentation to generated code
`preview_features` | array | `[]` | Enable experimental features

### Available Preview Features

Feature | Description
--- | ---
`"full_text_search"` | PostgreSQL full-text search support
`"multi_schema"` | Support for multiple database schemas
`"json_filtering"` | Filter on JSON/JSONB field contents
`"views"` | Database view support

## Migration Configuration

### [migrations]

Configure database migration behavior.

Option | Type | Default | Description
--- | --- | --- | ---
`directory` | string | `"./migrations"` | Directory for migration files
`auto_migrate` | boolean | `false` | Auto-apply migrations on startup
`table_name` | string | `"_prax_migrations"` | Name of migration history table

🚫 Warning: Never enable `auto_migrate = true` in production. Always run migrations manually after review.

## Seeding Configuration

### [seed]

Configure database seeding for development and testing.

Option | Type | Default | Description
--- | --- | --- | ---
`script` | string | — | Path to seed script
`auto_seed` | boolean | `false` | Automatically seed after migrations
`environments` | table | `{{ '{' }}{{ '}' }}` | Enable/disable seeding per environment

### Seed Script Example

## Debug Configuration

### [debug]

Configure query logging and debugging features.

Option | Type | Default | Description
--- | --- | --- | ---
`log_queries` | boolean | `false` | Log all executed SQL queries
`pretty_sql` | boolean | `true` | Pretty-print SQL in logs
`slow_query_threshold` | integer | `1000` | Warn about queries slower than this (ms)

### Debug Output Example

## Environment-Specific Overrides

### [environments.<name>]

Override any configuration value for specific environments (development, test, staging, production). Use `config.with_environment("name")` to apply overrides.

### Loading Environment Config

## Common Configuration Patterns

### Web Application

Typical configuration for a web server with connection pooling and tracing:

### CLI Application

Configuration for a command-line tool with SQLite:

### Microservice

Configuration for a microservice with custom migration table:

## Troubleshooting

Common configuration errors and how to fix them:

← Quick Start Schema Overview →