Struct DMSCDatabaseConfig 

pub struct DMSCDatabaseConfig {

    pub database_type: DatabaseType,
    pub host: String,
    pub port: u16,
    pub database: String,
    pub username: String,
    pub password: String,
    pub max_connections: u32,
    pub min_idle_connections: u32,
    pub connection_timeout_secs: u64,
    pub idle_timeout_secs: u64,
    pub max_lifetime_secs: u64,
    pub ssl_mode: SslMode,
    pub statement_cache_size: u32,
}

Configuration for database connections in DMSC.

This struct encapsulates all configuration options needed to establish and manage database connections. It supports multiple database backends through the DatabaseType enum and provides a fluent builder API for configuration.

Connection Pooling

DMSC uses connection pooling to efficiently manage database connections. The pool maintains a set of connections that are reused across requests, reducing the overhead of establishing new connections.

Configuration Methods

The struct provides several factory methods for creating configurations:

• postgres() - PostgreSQL with default settings
• mysql() - MySQL with default settings
• sqlite(path) - SQLite at specified path

Builder Pattern

Configuration can be customized using the builder pattern:

use dmsc::database::{DMSCDatabaseConfig, SslMode};

let config = DMSCDatabaseConfig::postgres()
    .host("db.example.com")
    .port(5432)
    .database("myapp")
    .user("admin")
    .password("secret")
    .max_connections(20)
    .ssl_mode(SslMode::Require)
    .build();

Environment Variables

Default values can be overridden using environment variables:

• DMSC_DB_HOST - Database server hostname
• DMSC_DB_PORT - Database server port
• DMSC_DB_NAME - Database name
• DMSC_DB_USER - Database username
• DMSC_DB_PASSWORD - Database password

Thread Safety

This struct is clonable and can be shared across threads. However, modifications should be done before the configuration is passed to the database manager.

Fields

database_type: DatabaseType

The type of database backend to connect to.

This determines which driver and connection logic will be used. Common values are DatabaseType::Postgres, DatabaseType::MySQL, and DatabaseType::SQLite.

host: String

Hostname or IP address of the database server.

For local development, this is typically "localhost" or "127.0.0.1". For production, this should be the database server’s hostname.

Examples

• localhost - Local database server
• db.example.com - Remote database server
• 192.168.1.100 - IP address of database server

port: u16

Port number for database connections.

Each database type has a default port:

• PostgreSQL: 5432
• MySQL: 3306
• MongoDB: 27017
• Redis: 6379

SQLite ignores this field as it uses file-based connections.

database: String

Name of the database to connect to.

For PostgreSQL and MySQL, this is the name of a specific database within the database server.

For SQLite, this is the file path (:memory: for in-memory database).

username: String

Username for database authentication.

This user must have sufficient privileges to perform the required database operations. For security, consider using environment variables or secrets management to provide this value.

password: String

Password for database authentication.

This password is used together with the username to authenticate with the database server. For security, consider using environment variables or secrets management to provide this value.

max_connections: u32

Maximum number of concurrent database connections.

This setting controls the upper bound of the connection pool. Higher values allow more concurrent database operations but increase resource usage on both the application and database server.

Recommendations

• Development: 5-10 connections
• Production: 10-50 connections (depends on workload)
• Consider database server’s max_connections setting

min_idle_connections: u32

Minimum number of idle connections to maintain.

The connection pool will maintain at least this many idle connections to reduce the latency of new database operations. These connections are still subject to the idle timeout.

Default Value

Typically 1-2 connections, depending on expected concurrency.

connection_timeout_secs: u64

Timeout for establishing new connections in seconds.

If a connection cannot be established within this time, the operation will fail with a timeout error. This prevents the application from hanging indefinitely when the database is unreachable.

Common Values

• 30 seconds for most scenarios
• 5-10 seconds for latency-sensitive applications
• 60+ seconds for distant database servers

idle_timeout_secs: u64

Maximum time a connection can be idle before being closed.

Idle connections that have not been used for this duration will be closed and removed from the pool. This helps free resources on both the application and database server.

Recommendations

• 600 seconds (10 minutes) for web applications
• 300 seconds (5 minutes) for batch processing
• Consider database server’s connection timeout settings

max_lifetime_secs: u64

Maximum lifetime of a connection in seconds.

Connections older than this will be closed and replaced with new ones. This prevents connections from becoming stale due to:

• Network interruptions
• Database server restarts
• Connection timeout on the database side

Recommendations

• 1800-3600 seconds (30-60 minutes) for most applications
• Shorter values for long-running applications
• Disable (use None) for very short-lived applications

ssl_mode: SslMode

SSL/TLS mode for encrypted connections.

This setting controls whether and how SSL/TLS encryption is used for database connections. It is ignored by SQLite.

Security

Always use SslMode::Require in production environments to ensure all database traffic is encrypted.

statement_cache_size: u32

Maximum number of prepared statements to cache.

Prepared statements are cached to reduce the overhead of repeated query compilation. Higher values improve performance for complex queries but increase memory usage.

Recommendations

• 100-500 for typical applications
• 1000+ for applications with many repeated complex queries
• 0 to disable statement caching

Implementations

impl DMSCDatabaseConfig

pub fn postgres() -> Self

Creates a configuration for PostgreSQL with default settings.

This factory method initializes a configuration with sensible defaults for PostgreSQL connections. Default values can be overridden using environment variables or the builder methods.

Defaults

• Host: localhost (or DMSC_DB_HOST env var)
• Port: 5432 (or DMSC_DB_PORT env var)
• Database: dmsc (or DMSC_DB_NAME env var)
• Username: dmsc (or DMSC_DB_USER env var)
• Password: empty (or DMSC_DB_PASSWORD env var)
• Max connections: 10
• Min idle: 2
• Connection timeout: 30 seconds
• Idle timeout: 600 seconds
• Max lifetime: 3600 seconds
• SSL mode: Prefer
• Statement cache: 100

Environment Variable Override

Default values are read from environment variables if available:

export DMSC_DB_HOST=db.example.com
export DMSC_DB_PORT=5432
export DMSC_DB_NAME=myapp
export DMSC_DB_USER=admin
export DMSC_DB_PASSWORD=secret

Returns

A new DMSCDatabaseConfig instance configured for PostgreSQL

Examples

use dmsc::database::DMSCDatabaseConfig;

// Basic PostgreSQL configuration
let config = DMSCDatabaseConfig::postgres();

// With environment variable overrides
// (assumes DMSC_DB_* variables are set)
let config = DMSCDatabaseConfig::postgres();

pub fn mysql() -> Self

Creates a configuration for MySQL with default settings.

This factory method initializes a configuration with sensible defaults for MySQL connections. Default values can be overridden using environment variables or the builder methods.

Defaults

• Host: localhost (or DMSC_DB_HOST env var)
• Port: 3306 (or DMSC_DB_PORT env var)
• Database: dmsc (or DMSC_DB_NAME env var)
• Username: dmsc (or DMSC_DB_USER env var)
• Password: empty (or DMSC_DB_PASSWORD env var)
• Max connections: 10
• Min idle: 2
• Connection timeout: 30 seconds
• Idle timeout: 600 seconds
• Max lifetime: 3600 seconds
• SSL mode: Prefer
• Statement cache: 100

MySQL-Specific Notes

• MySQL uses mysql:// URI scheme in connection strings
• MySQL 8.0+ uses caching_sha2_password by default
• Consider using SslMode::Require for production

Returns

A new DMSCDatabaseConfig instance configured for MySQL

Examples

use dmsc::database::DMSCDatabaseConfig;

// Basic MySQL configuration
let config = DMSCDatabaseConfig::mysql();

// Customized configuration
let config = DMSCDatabaseConfig::mysql()
    .host("db.example.com")
    .database("myapp")
    .user("app_user")
    .password("secure_password");

pub fn sqlite(path: &str) -> Self

Creates a configuration for SQLite at the specified path.

This factory method initializes a configuration for SQLite database at the given file path. SQLite is a serverless database that stores data in a single file.

Special Considerations

• The host and port fields are ignored
• The username and password fields are ignored
• The ssl_mode field is ignored
• File path can be :memory: for in-memory database

Path Handling

• Relative paths are resolved relative to the current working directory
• Parent directories are created automatically if they don’t exist
• Use absolute paths for reliability in production

File Permissions

The SQLite file and its directory must be writable by the application. Consider the following:

• The application user needs write permission to the database file
• The directory containing the database must be writable (for journal files)
• Consider file permissions (0600 recommended for the database file)

Arguments

• path - File path for the SQLite database (or :memory: for in-memory)

Returns

A new DMSCDatabaseConfig instance configured for SQLite

Examples

use dmsc::database::DMSCDatabaseConfig;

// File-based database
let config = DMSCDatabaseConfig::sqlite("./data/myapp.db");

// In-memory database (for testing)
let config = DMSCDatabaseConfig::sqlite(":memory:");

// Absolute path
let config = DMSCDatabaseConfig::sqlite("/var/lib/dmsc/database.db");

pub fn host(self, host: &str) -> Self

Sets the database server hostname.

This method configures the host address for database connections. It accepts hostnames, domain names, and IP addresses.

Arguments

• host - The hostname or IP address of the database server

Returns

The updated configuration (for method chaining)

Examples

use dmsc::database::DMSCDatabaseConfig;

let config = DMSCDatabaseConfig::postgres()
    .host("db.example.com");

let config = DMSCDatabaseConfig::mysql()
    .host("192.168.1.100");

pub fn port(self, port: u16) -> Self

Sets the database server port.

This method configures the port number for database connections. Each database type has a default port, but this can be overridden for non-standard configurations or when using database proxies.

Arguments

• port - The port number for database connections (1-65535)

Returns

The updated configuration (for method chaining)

Common Ports

• PostgreSQL: 5432
• MySQL: 3306
• MongoDB: 27017
• Redis: 6379

Examples

use dmsc::database::DMSCDatabaseConfig;

// Non-standard PostgreSQL port
let config = DMSCDatabaseConfig::postgres()
    .port(15432);

pub fn database(self, database: &str) -> Self

Sets the database name.

This method configures the name of the database to connect to. For PostgreSQL and MySQL, this is the logical database name. For SQLite, use the sqlite() constructor instead.

Arguments

• database - The name of the database to connect to

Returns

The updated configuration (for method chaining)

Examples

use dmsc::database::DMSCDatabaseConfig;

let config = DMSCDatabaseConfig::postgres()
    .database("production_db");

pub fn user(self, user: &str) -> Self

Sets the database username.

This method configures the username for database authentication. The specified user must have sufficient privileges to perform the required database operations.

Arguments

• user - The username for database authentication

Returns

The updated configuration (for method chaining)

Security Note

For security, consider using environment variables instead of hardcoding credentials in your code:

use std::env;

let config = DMSCDatabaseConfig::postgres()
    .user(&env::var("DB_USER").unwrap());

pub fn password(self, password: &str) -> Self

Sets the database password.

This method configures the password for database authentication. The password is used together with the username to authenticate with the database server.

Arguments

• password - The password for database authentication

Returns

The updated configuration (for method chaining)

Security Warning

Never hardcode passwords in your source code. Use:

• Environment variables
• Secret management services (AWS Secrets Manager, HashiCorp Vault)
• Configuration files with restricted permissions

Examples

use std::env;
use dmsc::database::DMSCDatabaseConfig;

let config = DMSCDatabaseConfig::postgres()
    .password(&env::var("DB_PASSWORD").unwrap());

pub fn max_connections(self, max: u32) -> Self

Sets the maximum number of concurrent connections.

This method configures the upper bound of the connection pool. The pool will not create more than this number of connections, even under heavy load.

Arguments

• max - Maximum number of concurrent connections (minimum 1)

Returns

The updated configuration (for method chaining)

Performance Considerations

• Higher values allow more concurrent database operations
• Each connection consumes memory on both client and server
• Database server has its own connection limits (e.g., PostgreSQL’s max_connections)
• Consider using connection pooling middleware for very high concurrency

Recommendations

• Development: 5-10 connections
• Production: 10-50 connections (depends on workload)
• Monitor database server connection counts

pub fn min_idle_connections(self, min: u32) -> Self

Sets the minimum number of idle connections.

This method configures the minimum number of idle connections that the pool will maintain. Having idle connections ready reduces the latency of new database operations.

Arguments

• min - Minimum number of idle connections (must be <= max_connections)

Returns

The updated configuration (for method chaining)

Trade-offs

• Benefits: Reduced latency for new operations
• Cost: Increased memory usage and database server load

Recommendations

• Set to expected concurrency level for best latency
• Or use a small value (1-2) if memory is constrained

pub fn connection_timeout_secs(self, secs: u64) -> Self

Sets the connection timeout in seconds.

This method configures the maximum time to wait when establishing a new database connection. If a connection cannot be established within this time, the operation will fail with a timeout error.

Arguments

• secs - Timeout in seconds for connection establishment

Returns

The updated configuration (for method chaining)

Considerations

• Too short: May cause false failures under normal load
• Too long: May hide database server problems
• Consider network latency to database server

Examples

use dmsc::database::DMSCDatabaseConfig;

// 60 second timeout for distant databases
let config = DMSCDatabaseConfig::postgres()
    .connection_timeout_secs(60);

pub fn idle_timeout_secs(self, secs: u64) -> Self

Sets the idle connection timeout in seconds.

This method configures how long an idle connection can exist before being closed. Idle connections are those that have been checked back into the pool but not reused.

Arguments

• secs - Maximum idle time in seconds before connection is closed

Returns

The updated configuration (for method chaining)

Purpose

• Frees resources on both client and database server
• Handles database server connection timeouts
• Reconnects after network interruptions

Recommendations

• 600 seconds (10 minutes) for typical web applications
• 300 seconds (5 minutes) for batch processing
• Consider database server’s wait_timeout setting (MySQL)

pub fn max_lifetime_secs(self, secs: u64) -> Self

Sets the maximum connection lifetime in seconds.

This method configures the maximum age of a connection. Connections older than this will be closed and replaced with new ones when they are returned to the pool.

Arguments

• secs - Maximum connection lifetime in seconds

Returns

The updated configuration (for method chaining)

Purpose

• Prevents stale connections from database server timeouts
• Handles database server restarts gracefully
• Rotates connections to handle network interruptions

Recommendations

• 1800-3600 seconds (30-60 minutes) for most applications
• Shorter values for very long-running applications
• Disable by using a very large value if needed

pub fn ssl_mode(self, mode: SslMode) -> Self

Sets the SSL/TLS mode for connections.

This method configures whether and how SSL/TLS encryption is used for database connections. For production environments, SslMode::Require is recommended to ensure all data is encrypted.

Arguments

• mode - The SSL/TLS mode to use

Returns

The updated configuration (for method chaining)

Examples

use dmsc::database::{DMSCDatabaseConfig, SslMode};

// Require SSL for production
let config = DMSCDatabaseConfig::postgres()
    .ssl_mode(SslMode::Require);

pub fn statement_cache_size(self, size: u32) -> Self

Sets the prepared statement cache size.

This method configures the maximum number of prepared statements to cache. Prepared statements are cached to reduce the overhead of repeated query compilation.

Arguments

• size - Maximum number of prepared statements to cache (0 to disable)

Returns

The updated configuration (for method chaining)

Performance Impact

• Benefit: Reduces query compilation overhead for repeated queries
• Cost: Increased memory usage for statement metadata
• Trade-off: Balance between memory and CPU usage

Recommendations

• 100-500 for typical applications
• 1000+ for applications with many repeated complex queries
• 0 to disable statement caching (for debugging)

pub fn build(self) -> DMSCDatabaseConfig

Builds the final configuration.

This method finalizes the configuration and returns the complete DMSCDatabaseConfig instance. It is the terminal method in the builder chain.

Returns

The complete configuration ready for use with DMSCDatabaseManager

Examples

use dmsc::database::DMSCDatabaseConfig;

let config = DMSCDatabaseConfig::postgres()
    .host("localhost")
    .database("myapp")
    .user("app")
    .password("secret")
    .max_connections(10)
    .build();

pub fn connection_string(&self) -> String

Generates a connection string for the configured database.

This method creates a database-specific connection string URI that can be used with various database client libraries.

Returns

A String containing the connection string

Examples

use dmsc::database::DMSCDatabaseConfig;

let config = DMSCDatabaseConfig::postgres()
    .host("localhost")
    .port(5432)
    .database("myapp")
    .user("app")
    .password("secret");

let connection_string = config.connection_string();
// postgresql://app:secret@localhost:5432/myapp

Trait Implementations

impl Clone for DMSCDatabaseConfig

fn clone(&self) -> DMSCDatabaseConfig

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for DMSCDatabaseConfig

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for DMSCDatabaseConfig

fn default() -> Self

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for DMSCDatabaseConfig

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl<'py> IntoPyObject<'py> for DMSCDatabaseConfig

type Target = DMSCDatabaseConfig

The Python output type

type Output = Bound<'py, <DMSCDatabaseConfig as IntoPyObject<'py>>::Target>

The smart pointer type to use.

type Error = PyErr

The type returned in the event of a conversion error.

fn into_pyobject( self, py: Python<'py>, ) -> Result<<Self as IntoPyObject<'_>>::Output, <Self as IntoPyObject<'_>>::Error>

Performs the conversion.

impl PyClass for DMSCDatabaseConfig

type Frozen = False

Whether the pyclass is frozen.

impl PyClassImpl for DMSCDatabaseConfig

const IS_BASETYPE: bool = false

#[pyclass(subclass)]

const IS_SUBCLASS: bool = false

#[pyclass(extends=…)]

const IS_MAPPING: bool = false

#[pyclass(mapping)]

const IS_SEQUENCE: bool = false

#[pyclass(sequence)]

const IS_IMMUTABLE_TYPE: bool = false

#[pyclass(immutable_type)]

const RAW_DOC: &'static CStr = /// to the database manager.

Docstring for the class provided on the struct or enum.

const DOC: &'static CStr

Fully rendered class doc, including the text_signature if a constructor is defined.

type BaseType = PyAny

Base class

type ThreadChecker = SendablePyClass<DMSCDatabaseConfig>

This handles following two situations:

type PyClassMutability = <<PyAny as PyClassBaseType>::PyClassMutability as PyClassMutability>::MutableChild

Immutable or mutable

type Dict = PyClassDummySlot

Specify this class has #[pyclass(dict)] or not.

type WeakRef = PyClassDummySlot

Specify this class has #[pyclass(weakref)] or not.

type BaseNativeType = PyAny

The closest native ancestor. This is PyAny by default, and when you declare #[pyclass(extends=PyDict)], it’s PyDict.

fn items_iter() -> PyClassItemsIter

fn lazy_type_object() -> &'static LazyTypeObject<Self>

fn dict_offset() -> Option<isize>

fn weaklist_offset() -> Option<isize>

impl PyClassNewTextSignature for DMSCDatabaseConfig

const TEXT_SIGNATURE: &'static str = "(database_type, host, port, database, username, password, max_connections, min_idle_connections, connection_timeout_secs, idle_timeout_secs, max_lifetime_secs, ssl_mode, statement_cache_size)"

impl PyMethods<DMSCDatabaseConfig> for PyClassImplCollector<DMSCDatabaseConfig>

fn py_methods(self) -> &'static PyClassItems

impl PyTypeInfo for DMSCDatabaseConfig

const NAME: &'static str = "DMSCDatabaseConfig"

Class name.

const MODULE: Option<&'static str> = ::core::option::Option::None

Module name, if any.

fn type_object_raw(py: Python<'_>) -> *mut PyTypeObject

Returns the PyTypeObject instance for this type.

fn type_object(py: Python<'_>) -> Bound<'_, PyType>

Returns the safe abstraction over the type object.

fn is_type_of(object: &Bound<'_, PyAny>) -> bool

Checks if object is an instance of this type or a subclass of this type.

fn is_exact_type_of(object: &Bound<'_, PyAny>) -> bool

Checks if object is an instance of this type.

impl Serialize for DMSCDatabaseConfig

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl DerefToPyAny for DMSCDatabaseConfig

impl ExtractPyClassWithClone for DMSCDatabaseConfig