Skip to main content

Database

Regius includes a unified database layer that works out of the box with PostgreSQL, MySQL/MariaDB, and SQLite.

Driver Alias Normalization​

postgres/postgresql, mysql/mariadb, and sqlite/sqlite3 are all accepted as DATABASE_TYPE.

Multi-Database DSN Builder​

BuildDSN() produces the correct DSN for each driver without manual string concatenation.

Connection Pool Tuning​

Configure max open, max idle, and connection lifetime via environment variables:

DATABASE_MAX_OPEN_CONNS=25
DATABASE_MAX_IDLE_CONNS=25
DATABASE_CONN_MAX_LIFETIME=15m

Health Checks​

Database.HealthCheck(ctx) verifies the database is reachable and responds to a ping.

if err := app.DB.HealthCheck(r.Context()); err != nil {
    http.Error(w, "database unavailable", http.StatusServiceUnavailable)
    return
}

Transaction Helper​

Regius.Transaction(ctx, func(*sql.Tx) error) runs a block inside a transaction and handles commit/rollback automatically.

err := app.Transaction(r.Context(), func(tx *sql.Tx) error {
    _, err := tx.Exec("INSERT INTO users (email) VALUES (?)", email)
    return err
})

Read/Write Splitting​

Configure a read replica via DATABASE_READ_* environment variables (or DATABASE_READ_DSN) and use app.DB.Reader() and app.DB.Writer() to route queries. Disabled by default.

// Route reads to the read replica (or main pool when not configured)
rows, err := app.DB.Reader().QueryContext(r.Context(), "SELECT id, email FROM users")

// Route writes to the write pool
_, err = app.DB.Writer().ExecContext(r.Context(), "UPDATE users SET last_login = ? WHERE id = ?", now, id)

GORM Integration​

Access a configured *gorm.DB via app.GORM() or run app.AutoMigrate(&models...) for schema management. GORM reuses the framework's existing database pool.

// Use GORM for ORM-style queries
gormDB, err := app.GORM()
if err != nil {
    http.Error(w, err.Error(), http.StatusInternalServerError)
    return
}
var users []User
gormDB.Find(&users)

// Run GORM AutoMigrate
_ = app.AutoMigrate(&User{}, &Post{})

Query Logging​

Enable DATABASE_QUERY_LOGGING=true to log every SQL statement with timing and error details through a transparent database/sql driver wrapper.

DATABASE_QUERY_LOGGING=true

Configuration​

DATABASE_TYPE=postgres
DATABASE_HOST=127.0.0.1
DATABASE_PORT=5432
DATABASE_USER=postgres
DATABASE_PASS=postgres
DATABASE_NAME=myapp
DATABASE_SSL_MODE=disable

# Optional pool tuning
DATABASE_MAX_OPEN_CONNS=25
DATABASE_MAX_IDLE_CONNS=25
DATABASE_CONN_MAX_LIFETIME=15m

# Optional query logging (for development)
DATABASE_QUERY_LOGGING=true

Fill in these values with your database connection details. Migrations, seeds, and health checks use these environment variables directly — no additional configuration file required.