Struct DatabaseConnection 

pub struct DatabaseConnection { /* private fields */ }

Available on crate feature database and native only.

Database connection wrapper

Implementations

impl DatabaseConnection

pub fn new(backend: Arc<dyn DatabaseBackend>) -> DatabaseConnection

Creates a new instance.

Defaults to is_cockroachdb = false, which is the correct choice when the caller has not (or cannot) probe the server. If the supplied backend is known to be CockroachDB, use Self::new_with_flavor instead so the migration recorder routes through the sentinel-row lock path rather than pg_advisory_lock (issue #4642).

pub fn new_with_flavor( backend: Arc<dyn DatabaseBackend>, is_cockroachdb: bool, ) -> DatabaseConnection

Creates a new instance with an explicit CockroachDB flavor flag.

Use this when wrapping an externally constructed Postgres backend whose flavor is already known — e.g. tests that mount a CockroachDB pool, or adapters that pre-probe SELECT version() themselves.

pub async fn connect_postgres( url: &str, ) -> Result<DatabaseConnection, DatabaseError>

Available on crate feature postgres only.

Connects to postgres.

pub async fn connect_postgres_with_pool_size( url: &str, pool_size: Option<u32>, ) -> Result<DatabaseConnection, DatabaseError>

Available on crate feature postgres only.

Connects to postgres with pool size.

pub async fn connect_postgres_or_create( url: &str, ) -> Result<DatabaseConnection, DatabaseError>

Available on crate feature postgres only.

Connect to PostgreSQL with automatic database creation if it doesn’t exist.

This method first attempts to connect to the specified database. If the connection fails due to the database not existing, it will:

1. Connect to the default postgres database
2. Create the target database
3. Reconnect to the newly created database

Arguments

• url - PostgreSQL connection URL (e.g., “postgres://user:pass@localhost/mydb”)

Example

use reinhardt_db::backends::connection::DatabaseConnection;

// Will create 'mydb' if it doesn't exist
let conn = DatabaseConnection::connect_postgres_or_create(
    "postgres://postgres@localhost/mydb"
).await?;

pub async fn connect_postgres_or_create_with_pool_size( url: &str, pool_size: Option<u32>, ) -> Result<DatabaseConnection, DatabaseError>

Available on crate feature postgres only.

Connect to PostgreSQL with automatic database creation and custom pool size.

See Self::connect_postgres_or_create for details on automatic database creation.

pub async fn connect_sqlite( url: &str, ) -> Result<DatabaseConnection, DatabaseError>

Available on crate feature sqlite only.

Connects to a SQLite database at the given URL.

pub fn from_sqlite_pool(pool: Pool<Sqlite>) -> DatabaseConnection

Available on crate feature sqlite only.

Creates a connection from an existing SQLite pool.

pub async fn connect_mysql( url: &str, ) -> Result<DatabaseConnection, DatabaseError>

Available on crate feature mysql only.

Connects to a MySQL database at the given URL.

pub fn backend(&self) -> Arc<dyn DatabaseBackend>

Performs the backend operation.

pub fn database_type(&self) -> DatabaseType

Get the database type

pub fn is_cockroachdb(&self) -> bool

Returns true when the underlying server is CockroachDB.

CockroachDB is wire-compatible with PostgreSQL and uses the same PostgresBackend, so database_type() returns DatabaseType::Postgres for both. Callers that must dispatch on the server flavour (e.g. the migration-lock path, which cannot use pg_advisory_lock on CockroachDB — see issue #4642) should check this flag first.

The flag is determined at connection time via a single SELECT version() probe and is false for any non-Postgres backend.

pub fn insert(&self, table: impl Into<String>) -> InsertBuilder

Performs the insert operation.

pub fn update(&self, table: impl Into<String>) -> UpdateBuilder

Performs the update operation.

pub fn select(&self) -> SelectBuilder

Performs the select operation.

pub fn delete(&self, table: impl Into<String>) -> DeleteBuilder

Performs the delete operation.

pub fn database_url_from<S>( settings: &S, env_override: Option<&str>, ) -> Result<String, DatabaseError>

where S: HasCoreSettings + ?Sized,

Available on crate feature settings only.

Resolve a database URL from an already-built composed settings value.

This is the preferred entry point for callers that already hold a ProjectSettings (or any type that implements reinhardt_conf::HasCoreSettings). It reads the default entry of CoreSettings::databases and converts it to a URL via DatabaseConfig::to_url.

The optional env_override argument is honored first: if it is Some(url), that URL is returned verbatim. Pass None to skip the override entirely. To opt into the env-var short circuit, bind the result of std::env::var first so the temporary String outlives the borrow:

let database_url_env = std::env::var("DATABASE_URL").ok();
let url = DatabaseConnection::database_url_from(
    settings,
    database_url_env.as_deref(),
)?;

Errors

Returns a ConnectionError if the core.databases.default entry is missing from the composed settings. DatabaseConfig::to_url itself is infallible, so a successfully resolved default entry always yields Ok(_).

Example

use reinhardt_db::backends::connection::DatabaseConnection;
let url = DatabaseConnection::database_url_from(settings, None)
    .expect("database url");

pub fn get_database_url_from_env_or_settings( base_dir: Option<PathBuf>, ) -> Result<String, DatabaseError>

👎Deprecated since 0.1.0-rc.29:

use DatabaseConnection::database_url_from with a pre-built ProjectSettings instead

Available on crate feature settings only.

Get database URL from environment variable or settings files

This function first checks the DATABASE_URL environment variable. If not found, it attempts to load database configuration from settings files in the settings/ directory.

Arguments

• base_dir - Base directory for the project (defaults to current directory if None)

Returns

Returns the database URL string, or an error if neither environment variable nor settings configuration is found.

Deprecated

This function reloads settings/<profile>.toml from disk every time it is invoked, which is wasteful and duplicates settings-loading logic. Use Self::database_url_from with an already-built ProjectSettings instead.

Example

use reinhardt_db::backends::connection::DatabaseConnection;

let url = DatabaseConnection::get_database_url_from_env_or_settings(None)?;
let conn = DatabaseConnection::connect_sqlite(&url).await?;

pub async fn execute( &self, sql: &str, params: Vec<QueryValue>, ) -> Result<QueryResult, DatabaseError>

Executes the operation.

pub async fn fetch_one( &self, sql: &str, params: Vec<QueryValue>, ) -> Result<Row, DatabaseError>

Fetches one.

pub async fn fetch_all( &self, sql: &str, params: Vec<QueryValue>, ) -> Result<Vec<Row>, DatabaseError>

Fetches all.

pub async fn fetch_optional( &self, sql: &str, params: Vec<QueryValue>, ) -> Result<Option<Row>, DatabaseError>

Fetches optional.

pub async fn begin(&self) -> Result<Box<dyn TransactionExecutor>, DatabaseError>

Begin a database transaction and return a dedicated executor

This method acquires a dedicated database connection and begins a transaction on it. All queries executed through the returned TransactionExecutor are guaranteed to run on the same physical connection, ensuring proper transaction isolation.

Returns

A boxed TransactionExecutor that holds the dedicated connection and provides methods for executing queries within the transaction.

Example

use reinhardt_db::backends::connection::DatabaseConnection;

let conn = DatabaseConnection::connect_postgres("postgres://localhost/mydb").await?;
let mut tx = conn.begin().await?;

tx.execute("INSERT INTO users (name) VALUES ($1)", vec!["Alice".into()]).await?;
tx.commit().await?;

pub async fn begin_with_isolation( &self, level: IsolationLevel, ) -> Result<Box<dyn TransactionExecutor>, DatabaseError>

Begin a transaction with a specific isolation level

Examples

use reinhardt_db::backends::connection::DatabaseConnection;
use reinhardt_db::backends::types::IsolationLevel;

let conn = DatabaseConnection::connect_postgres("postgres://localhost/mydb").await?;
let mut tx = conn.begin_with_isolation(IsolationLevel::Serializable).await?;

tx.execute("INSERT INTO users (name) VALUES ($1)", vec!["Alice".into()]).await?;
tx.commit().await?;

pub fn into_postgres(&self) -> Option<Pool<Postgres>>

Available on crate feature postgres only.

Converts into postgres.

pub fn into_sqlite(&self) -> Option<Pool<Sqlite>>

Available on crate feature sqlite only.

Converts into the underlying SQLite pool, if the backend is SQLite.

pub fn into_mysql(&self) -> Option<Pool<MySql>>

Available on crate feature mysql only.

Converts into the underlying MySQL pool, if the backend is MySQL.

Trait Implementations

impl Clone for DatabaseConnection

fn clone(&self) -> DatabaseConnection

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Injectable for DatabaseConnection

Injectable implementation for DatabaseConnection

DatabaseConnection must be explicitly registered in the DI context using InjectionContextBuilder::singleton(). It cannot be auto-injected because it requires runtime configuration (connection URL, pool settings, etc.).

Example

use reinhardt_di::{InjectionContext, SingletonScope};
use reinhardt_db::backends::DatabaseConnection;
use std::sync::Arc;

// Create and configure the connection
let db = DatabaseConnection::connect_postgres("postgres://localhost/mydb")
    .await
    .expect("Failed to connect to database");

// Register in DI context
let singleton_scope = Arc::new(SingletonScope::new());
let ctx = InjectionContext::builder(singleton_scope)
    .singleton(db)
    .build();

fn inject<'life0, 'async_trait>( ctx: &'life0 InjectionContext, ) -> Pin<Box<dyn Future<Output = Result<DatabaseConnection, DiError>> + Send + 'async_trait>>

where 'life0: 'async_trait, DatabaseConnection: 'async_trait,

Creates an instance of this type by resolving dependencies from the injection context.

fn inject_uncached<'life0, 'async_trait>( ctx: &'life0 InjectionContext, ) -> Pin<Box<dyn Future<Output = Result<DatabaseConnection, DiError>> + Send + 'async_trait>>

where 'life0: 'async_trait, DatabaseConnection: 'async_trait,

Inject without using cache (for cache = false support).