polite 0.1.3

rusqlite × Polars bridge library
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133

//! # Polite: SQLite × Polars Integration
//!
//! A Rust library that provides seamless integration between SQLite databases
//! and Polars DataFrames using ConnectorX for efficient data transfer.
//!
//! ## Features
//!
//! - **Fast data loading**: Use ConnectorX to efficiently load SQLite query results into Polars DataFrames
//! - **Easy data writing**: Save Polars DataFrames directly to SQLite tables
//! - **Type preservation**: Automatic mapping between Polars and SQLite data types
//! - **Simple API**: Minimal boilerplate for common database operations
//!
//! ## Quick Start
//!
//! ```rust
//! use polite::{connect_sqlite, to_dataframe, from_dataframe};
//! use polars::prelude::*;
//!
//! // Open a SQLite connection
//! let conn = connect_sqlite(Some("data.db")).unwrap();
//!
//! // Load data from SQLite into a DataFrame
//! let df = to_dataframe("data.db", "SELECT * FROM users").unwrap();
//!
//! // Save a DataFrame to SQLite
//! from_dataframe(&conn, "new_table", &df).unwrap();
//! ```
//!
//! ## Modules
//!
//! - [`dataframe`] - Functions for converting between DataFrames and SQLite
//! - [`db`] - Database connection utilities
//! - [`error`] - Custom error types

mod connectorx;
pub mod dataframe;
pub mod db;
pub mod error;
pub(crate) mod types;

// Re-export the main entrypoints at crate root
pub use dataframe::{from_dataframe, to_dataframe};
pub use db::{connect_sqlite, execute_query};
pub use error::PoliteError;

/// Common imports for polite users.
///
/// This prelude module re-exports the most commonly used items from polite,
/// allowing users to quickly import everything they need with a single glob import.
///
/// # Examples
///
/// ```rust
/// use polite::prelude::*;
///
/// // Now you have access to all the main functions:
/// let conn = connect_sqlite(Some("data.db")).unwrap();
/// let df = to_dataframe("data.db", "SELECT * FROM users").unwrap();
/// from_dataframe(&conn, "backup_users", &df).unwrap();
/// ```
pub mod prelude {
    pub use crate::{connect_sqlite, execute_query, from_dataframe, to_dataframe, PoliteError};

    // Convenience functions from lib module:
    pub use crate::{load_dataframe, save_dataframe};
}

/// Create a DataFrame from a SQLite file with error handling and logging.
///
/// This convenience function provides better error messages and optional logging
/// compared to the raw `to_dataframe` function.
///
/// # Arguments
///
/// * `db_path` - Path to the SQLite database file
/// * `sql` - SQL query to execute
///
/// # Examples
///
/// ```rust
/// use polite::load_dataframe;
///
/// let df = load_dataframe("data.db", "SELECT id, name FROM users LIMIT 10")
///     .expect("Failed to load data");
///
/// println!("Loaded {} rows", df.height());
/// ```
pub fn load_dataframe(db_path: &str, sql: &str) -> Result<polars::prelude::DataFrame, PoliteError> {
    to_dataframe(db_path, sql).map_err(|e| PoliteError::Load {
        db_path: db_path.to_string(),
        source: Box::new(e),
    })
}

/// Save a DataFrame to SQLite with automatic table creation and better error handling.
///
/// This convenience function handles connection creation and provides clearer error messages.
///
/// # Arguments
///
/// * `db_path` - Path to the SQLite database file (will be created if it doesn't exist)
/// * `table_name` - Name of the table to create/insert into
/// * `df` - The DataFrame to save
///
/// # Examples
///
/// ```rust
/// use polite::save_dataframe;
/// use polars::prelude::*;
///
/// let df = df! {
///     "id" => [1, 2, 3],
///     "name" => ["Alice", "Bob", "Charlie"],
/// }.unwrap();
///
/// save_dataframe("output.db", "users", &df)
///     .expect("Failed to save DataFrame");
/// ```
pub fn save_dataframe(
    db_path: &str,
    table_name: &str,
    df: &polars::prelude::DataFrame,
) -> Result<(), PoliteError> {
    let conn = connect_sqlite(Some(db_path))?;

    from_dataframe(&conn, table_name, df).map_err(|e| PoliteError::Save {
        db_path: db_path.to_string(),
        table_name: table_name.to_string(),
        source: Box::new(e),
    })?;

    Ok(())
}