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 →