Database Configuration

Kit provides flexible database configuration through environment variables and a programmatic API.

Environment Variables

The simplest way to configure your database is through the .env file:

# .env
DATABASE_URL=sqlite:./database.db

Connection String Formats

Database	Format	Example
SQLite	`sqlite:<path>`	`sqlite:./database.db`
PostgreSQL	`postgres://user:pass@host:port/db`	`postgres://admin:secret@localhost:5432/myapp`
MySQL	`mysql://user:pass@host:port/db`	`mysql://root:password@localhost:3306/myapp`

DatabaseConfig

For programmatic configuration, use DatabaseConfig:

use kit::database::DatabaseConfig;

let config = DatabaseConfig::from_env();

Builder Pattern

You can also build configuration manually:

use kit::database::DatabaseConfig;

let config = DatabaseConfig::builder()
    .url("postgres://localhost/myapp")
    .max_connections(10)
    .min_connections(2)
    .connect_timeout_seconds(30)
    .idle_timeout_seconds(600)
    .build();

Connection Pooling

Kit automatically manages a connection pool for optimal performance. Configure pooling settings through DatabaseConfig:

Setting	Default	Description
`max_connections`	`10`	Maximum number of connections in the pool
`min_connections`	`1`	Minimum idle connections to maintain
`connect_timeout_seconds`	`30`	Timeout for acquiring a connection
`idle_timeout_seconds`	`600`	Time before idle connections are closed

use kit::database::DatabaseConfig;

let config = DatabaseConfig::builder()
    .url("postgres://localhost/myapp")
    .max_connections(20)      // For high-traffic applications
    .min_connections(5)       // Keep 5 connections warm
    .connect_timeout_seconds(10)
    .idle_timeout_seconds(300)
    .build();

Database Initialization

The database is automatically initialized when your Kit application starts. The DB::init() method is called during bootstrap:

// src/main.rs (handled automatically by Kit)
use kit::database::{DB, DatabaseConfig};

#[tokio::main]
async fn main() {
    // Database initialization happens automatically
    // when you use Kit::new()

    Kit::new()
        .serve()
        .await;
}

Manual Initialization

If you need to initialize the database manually:

use kit::database::{DB, DatabaseConfig};

async fn setup_database() {
    let config = DatabaseConfig::from_env();
    DB::init(config).await;
}

Accessing the Connection

Use the DB facade to access the database connection anywhere in your application:

use kit::database::DB;
use sea_orm::EntityTrait;

async fn example() {
    // Get the database connection
    let db = DB::connection();

    // Use with SeaORM queries
    let users = users::Entity::find()
        .all(db)
        .await
        .unwrap();
}

Multiple Databases

For applications requiring multiple database connections, you can manage connections manually:

use sea_orm::{Database, DatabaseConnection};

struct AppState {
    primary_db: DatabaseConnection,
    analytics_db: DatabaseConnection,
}

async fn setup_databases() -> AppState {
    let primary = Database::connect("postgres://localhost/primary")
        .await
        .unwrap();

    let analytics = Database::connect("postgres://localhost/analytics")
        .await
        .unwrap();

    AppState {
        primary_db: primary,
        analytics_db: analytics,
    }
}

Environment-Specific Configuration

Use different configurations for development, testing, and production:

# .env.development
DATABASE_URL=sqlite:./dev.db

# .env.test
DATABASE_URL=sqlite::memory:

# .env.production
DATABASE_URL=postgres://user:pass@prod-server:5432/myapp

Troubleshooting

Connection Refused

If you see connection refused errors:

Verify the database server is running
Check the connection string format
Ensure network access (firewall, security groups)

# Test PostgreSQL connection
psql -h localhost -U user -d myapp

# Test MySQL connection
mysql -h localhost -u user -p myapp

Pool Exhausted

If connections are being exhausted:

Increase max_connections
Ensure connections are being released (avoid long-running transactions)
Check for connection leaks in your code

// Increase pool size
let config = DatabaseConfig::builder()
    .url("postgres://localhost/myapp")
    .max_connections(50)  // Increase from default 10
    .build();

SQLite File Not Created

For SQLite, ensure the directory exists:

// The file will be created automatically, but the directory must exist
DATABASE_URL=sqlite:./data/database.db  // Ensure ./data/ exists

Getting Started

Tutorials

Core Concepts

Frontend

Database

CLI Reference

Deployment

Environment Variables

Connection String Formats

DatabaseConfig

Builder Pattern

Connection Pooling

Database Initialization

Manual Initialization

Accessing the Connection

Multiple Databases

Environment-Specific Configuration

Troubleshooting

Connection Refused

Pool Exhausted

SQLite File Not Created

​Environment Variables

​Connection String Formats

​DatabaseConfig

​Builder Pattern

​Connection Pooling

​Database Initialization

​Manual Initialization

​Accessing the Connection

​Multiple Databases

​Environment-Specific Configuration

​Troubleshooting

​Connection Refused

​Pool Exhausted

​SQLite File Not Created

Environment Variables

Connection String Formats

DatabaseConfig

Builder Pattern

Connection Pooling

Database Initialization

Manual Initialization

Accessing the Connection

Multiple Databases

Environment-Specific Configuration

Troubleshooting

Connection Refused

Pool Exhausted

SQLite File Not Created