fh-saas 0.9.5__py3-none-any.whl

fh_saas/utils_polars_mapper.py

@@ -0,0 +1,134 @@
+"""High-performance JSON-to-database pipeline using Polars vectorized transformations."""
+
+# AUTOGENERATED! DO NOT EDIT! File to edit: ../nbs/09_utils_polars_mapper.ipynb.
+
+# %% ../nbs/09_utils_polars_mapper.ipynb 2
+from __future__ import annotations
+import polars as pl
+from sqlalchemy import create_engine, text
+from typing import Dict, List, Optional
+import uuid
+import logging
+from nbdev.showdoc import show_doc
+
+
+logger = logging.getLogger(__name__)
+
+# %% auto 0
+__all__ = ['logger', 'map_and_upsert', 'apply_schema']
+
+# %% ../nbs/09_utils_polars_mapper.ipynb 5
+def map_and_upsert(
+    df: pl.DataFrame, # The raw Polars DataFrame from JSON
+    table_name: str, # Target database table name
+    key_col: str, # Primary key column for conflict resolution
+    db_uri: str, # SQLAlchemy connection string (e.g., 'sqlite:///db.db' or 'postgresql://...')
+    column_map: dict = None, # Optional rename map {json_key: db_col}
+    unnest_cols: list[str] = None # List of Struct columns to flatten
+):
+    """Map JSON data to database columns and upsert using staging table pattern."""
+    # Step 1: Rename columns if mapping provided
+    if column_map:
+        df = df.rename(column_map)
+        logger.info(f"Renamed columns: {column_map}")
+    
+    # Step 2: Flatten nested columns if specified
+    if unnest_cols:
+        for col in unnest_cols:
+            if col in df.columns:
+                df = df.unnest(col)
+                logger.info(f"Unnested column: {col}")
+    
+    # Step 3: Select only columns that exist in target table (drop extras)
+    # This prevents errors from extra JSON fields
+    engine = create_engine(db_uri)
+    
+    # Get target table columns
+    with engine.connect() as conn:
+        result = conn.execute(text(f"SELECT * FROM {table_name} LIMIT 0"))
+        target_columns = list(result.keys())
+    
+    # Filter DataFrame to only target columns
+    available_cols = [col for col in target_columns if col in df.columns]
+    df = df.select(available_cols)
+    logger.info(f"Selected columns for {table_name}: {available_cols}")
+    
+    # Step 4: Generate unique staging table name
+    staging_table = f"staging_{uuid.uuid4().hex[:8]}"
+    
+    try:
+        # Step 5: Write to staging table (fast bulk insert)
+        df.write_database(
+            table_name=staging_table,
+            connection=db_uri,
+            if_table_exists='replace'
+        )
+        logger.info(f"Wrote {len(df)} rows to staging table {staging_table}")
+        
+        # Step 6: Determine database type for dialect-specific SQL
+        is_sqlite = 'sqlite' in db_uri.lower()
+        
+        # Step 7: Execute upsert from staging to target
+        with engine.connect() as conn:
+            if is_sqlite:
+                # SQLite: INSERT OR REPLACE
+                cols_str = ', '.join(available_cols)
+                upsert_sql = f"""
+                    INSERT OR REPLACE INTO {table_name} ({cols_str})
+                    SELECT {cols_str} FROM {staging_table}
+                """
+            else:
+                # PostgreSQL: INSERT ... ON CONFLICT DO UPDATE
+                cols_str = ', '.join(available_cols)
+                update_cols = [col for col in available_cols if col != key_col]
+                update_set = ', '.join([f"{col} = EXCLUDED.{col}" for col in update_cols])
+                
+                upsert_sql = f"""
+                    INSERT INTO {table_name} ({cols_str})
+                    SELECT {cols_str} FROM {staging_table}
+                    ON CONFLICT ({key_col}) DO UPDATE SET {update_set}
+                """
+            
+            conn.execute(text(upsert_sql))
+            conn.commit()
+            logger.info(f"Upserted {len(df)} rows into {table_name}")
+    
+    finally:
+        # Step 8: Cleanup - drop staging table
+        with engine.connect() as conn:
+            conn.execute(text(f"DROP TABLE IF EXISTS {staging_table}"))
+            conn.commit()
+            logger.info(f"Dropped staging table {staging_table}")
+
+# %% ../nbs/09_utils_polars_mapper.ipynb 8
+def apply_schema(
+    df: pl.DataFrame, # Input DataFrame
+    type_map: dict # Column name -> Polars dtype (e.g., {'created_at': pl.Date, 'is_active': pl.Boolean})
+) -> pl.DataFrame:
+    """Apply explicit type conversions to DataFrame columns."""
+    conversions = []
+    
+    for col_name, dtype in type_map.items():
+        if col_name not in df.columns:
+            logger.warning(f"Column {col_name} not found in DataFrame, skipping")
+            continue
+        
+        # Handle different type conversions
+        if dtype == pl.Date:
+            conversions.append(pl.col(col_name).str.strptime(pl.Date, "%Y-%m-%d").alias(col_name))
+        elif dtype == pl.Datetime:
+            conversions.append(pl.col(col_name).str.strptime(pl.Datetime).alias(col_name))
+        elif dtype == pl.Boolean:
+            # Handle "true"/"false" strings
+            conversions.append(
+                pl.col(col_name).str.to_lowercase().eq("true").alias(col_name)
+            )
+        else:
+            # Cast to specified type (works for numeric types)
+            conversions.append(pl.col(col_name).cast(dtype).alias(col_name))
+    
+    if conversions:
+        df = df.with_columns(conversions)
+        logger.info(f"Applied schema conversions to {len(type_map)} columns")
+    
+    return df

fh_saas/utils_seo.py

@@ -0,0 +1,230 @@
+"""Generate meta tags, sitemaps, and structured data for search engines."""
+
+# AUTOGENERATED! DO NOT EDIT! File to edit: ../nbs/12_utils_seo.ipynb.
+
+# %% ../nbs/12_utils_seo.ipynb 2
+from __future__ import annotations
+from typing import List, Dict, Optional
+from datetime import datetime
+from html import escape
+from nbdev.showdoc import show_doc
+
+# %% auto 0
+__all__ = ['generate_head_tags', 'generate_sitemap_xml', 'generate_rss_xml']
+
+# %% ../nbs/12_utils_seo.ipynb 5
+def generate_head_tags(
+    title: str, # Page title
+    description: str, # Page description (150-160 chars optimal)
+    url: str, # Canonical URL
+    image_url: Optional[str] = None, # OpenGraph image URL
+    article_published: Optional[datetime] = None, # Publication date
+    article_modified: Optional[datetime] = None, # Last modified date
+    author: Optional[str] = None # Author name
+) -> List[tuple]:
+    """
+    Generate meta tags for SEO.
+    
+    Returns list of (tag_name, attributes_dict) tuples for FastHTML components.
+    Includes standard, OpenGraph, and Twitter Card tags.
+    
+    Example:
+        ```python
+        from fasthtml.common import *
+        
+        tags = generate_head_tags(
+            title='My Blog Post',
+            description='Learn about Python',
+            url='https://example.com/blog/my-post',
+            image_url='https://example.com/image.jpg'
+        )
+        
+        # Use in FastHTML app
+        @app.get('/blog/my-post')
+        def post():
+            return Html(
+                Head(
+                    *[Meta(**attrs) if tag == 'meta' else Link(**attrs) 
+                      for tag, attrs in tags]
+                ),
+                Body('...')
+            )
+        ```
+    """
+    tags = []
+    
+    # Standard meta tags
+    tags.append(('title', {'content': title}))
+    tags.append(('meta', {'name': 'description', 'content': description}))
+    
+    # Canonical URL
+    tags.append(('link', {'rel': 'canonical', 'href': url}))
+    
+    # OpenGraph tags (Facebook, WhatsApp, etc.)
+    tags.extend([
+        ('meta', {'property': 'og:title', 'content': title}),
+        ('meta', {'property': 'og:description', 'content': description}),
+        ('meta', {'property': 'og:url', 'content': url}),
+        ('meta', {'property': 'og:type', 'content': 'article'})
+    ])
+    
+    if image_url:
+        tags.append(('meta', {'property': 'og:image', 'content': image_url}))
+    
+    # Article metadata
+    if article_published:
+        tags.append(('meta', {
+            'property': 'article:published_time',
+            'content': article_published.isoformat()
+        }))
+    
+    if article_modified:
+        tags.append(('meta', {
+            'property': 'article:modified_time',
+            'content': article_modified.isoformat()
+        }))
+    
+    if author:
+        tags.append(('meta', {'property': 'article:author', 'content': author}))
+    
+    # Twitter Card tags
+    tags.extend([
+        ('meta', {'name': 'twitter:card', 'content': 'summary_large_image'}),
+        ('meta', {'name': 'twitter:title', 'content': title}),
+        ('meta', {'name': 'twitter:description', 'content': description})
+    ])
+    
+    if image_url:
+        tags.append(('meta', {'name': 'twitter:image', 'content': image_url}))
+    
+    return tags
+
+# %% ../nbs/12_utils_seo.ipynb 8
+def generate_sitemap_xml(
+    posts: List[Dict], # List of posts from PostLoader
+    base_url: str, # Base URL (e.g., 'https://example.com')
+    blog_path: str = '/blog' # Blog path prefix
+) -> str:
+    """
+    Generate XML sitemap for blog posts.
+    
+    Returns sitemap XML string with proper structure and lastmod dates.
+    
+    Example:
+        ```python
+        from fasthtml.common import *
+        from fh_saas.utils_blog import PostLoader
+        
+        app = FastHTML()
+        loader = PostLoader('blog/posts')
+        
+        @app.get('/sitemap.xml')
+        def sitemap():
+            posts = loader.load_posts()
+            xml = generate_sitemap_xml(
+                posts=posts,
+                base_url='https://example.com',
+                blog_path='/blog'
+            )
+            return Response(xml, media_type='application/xml')
+        ```
+    """
+    xml_parts = [
+        '<?xml version="1.0" encoding="UTF-8"?>',
+        '<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">'
+    ]
+    
+    # Add blog index
+    xml_parts.append(f'  <url>')
+    xml_parts.append(f'    <loc>{escape(base_url + blog_path)}</loc>')
+    xml_parts.append(f'    <changefreq>daily</changefreq>')
+    xml_parts.append(f'    <priority>1.0</priority>')
+    xml_parts.append(f'  </url>')
+    
+    # Add each post
+    for post in posts:
+        url = f"{base_url}{blog_path}/{post['slug']}"
+        xml_parts.append(f'  <url>')
+        xml_parts.append(f'    <loc>{escape(url)}</loc>')
+        
+        if post.get('date'):
+            lastmod = post['date'].strftime('%Y-%m-%d')
+            xml_parts.append(f'    <lastmod>{lastmod}</lastmod>')
+        
+        xml_parts.append(f'    <changefreq>monthly</changefreq>')
+        xml_parts.append(f'    <priority>0.8</priority>')
+        xml_parts.append(f'  </url>')
+    
+    xml_parts.append('</urlset>')
+    return '\n'.join(xml_parts)
+
+# %% ../nbs/12_utils_seo.ipynb 11
+def generate_rss_xml(
+    posts: List[Dict], # List of posts from PostLoader
+    blog_title: str, # Blog title
+    blog_description: str, # Blog description
+    base_url: str, # Base URL
+    blog_path: str = '/blog' # Blog path prefix
+) -> str:
+    """
+    Generate RSS 2.0 feed for blog posts.
+    
+    Returns RSS XML string for feed readers (Feedly, etc.).
+    
+    Example:
+        ```python
+        from fasthtml.common import *
+        from fh_saas.utils_blog import PostLoader
+        
+        app = FastHTML()
+        loader = PostLoader('blog/posts')
+        
+        @app.get('/rss.xml')
+        def rss():
+            posts = loader.load_posts()[:20]  # Latest 20 posts
+            xml = generate_rss_xml(
+                posts=posts,
+                blog_title='My Blog',
+                blog_description='Tech tutorials and insights',
+                base_url='https://example.com'
+            )
+            return Response(xml, media_type='application/xml')
+        ```
+    """
+    from email.utils import formatdate
+    
+    xml_parts = [
+        '<?xml version="1.0" encoding="UTF-8"?>',
+        '<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom">',
+        '  <channel>',
+        f'    <title>{escape(blog_title)}</title>',
+        f'    <link>{escape(base_url + blog_path)}</link>',
+        f'    <description>{escape(blog_description)}</description>',
+        f'    <atom:link href="{escape(base_url)}/rss.xml" rel="self" type="application/rss+xml" />'
+    ]
+    
+    # Add items
+    for post in posts:
+        url = f"{base_url}{blog_path}/{post['slug']}"
+        
+        xml_parts.append('    <item>')
+        xml_parts.append(f'      <title>{escape(post["title"])}</title>')
+        xml_parts.append(f'      <link>{escape(url)}</link>')
+        xml_parts.append(f'      <guid>{escape(url)}</guid>')
+        
+        if post.get('description'):
+            xml_parts.append(f'      <description>{escape(post["description"])}</description>')
+        
+        if post.get('date'):
+            pub_date = formatdate(post['date'].timestamp(), usegmt=True)
+            xml_parts.append(f'      <pubDate>{pub_date}</pubDate>')
+        
+        if post.get('author'):
+            xml_parts.append(f'      <author>{escape(post["author"])}</author>')
+        
+        xml_parts.append('    </item>')
+    
+    xml_parts.append('  </channel>')
+    xml_parts.append('</rss>')
+    
+    return '\n'.join(xml_parts)

fh_saas/utils_sql.py

@@ -0,0 +1,320 @@
+"""Comprehensive SQL helper library for database operations with multi-database support."""
+
+# AUTOGENERATED! DO NOT EDIT! File to edit: ../nbs/02_utils_sql.ipynb.
+
+# %% auto 0
+__all__ = ['logger', 'get_db_type', 'validate_params', 'run_id', 'insert_only', 'bulk_insert_only', 'upsert', 'bulk_upsert',
+           'get_by_id', 'update_record', 'delete_record', 'bulk_delete', 'with_transaction', 'paginate_sql',
+           'batch_execute', 'to_cents', 'from_cents']
+
+# %% ../nbs/02_utils_sql.ipynb 2
+from fastsql import *
+from sqlalchemy import text
+import os
+import re
+import logging
+from typing import List, Dict, Any, Optional
+from contextlib import contextmanager
+from nbdev.showdoc import show_doc
+
+# Module-level logger - configured by app via configure_logging()
+logger = logging.getLogger(__name__)
+
+# %% ../nbs/02_utils_sql.ipynb 5
+def get_db_type():
+    """Get database type from environment variable"""
+    return os.getenv("DB_TYPE", "SQLITE").upper()
+
+# %% ../nbs/02_utils_sql.ipynb 8
+def _extract_params(sql: str) -> List[str]:
+    """Extract parameter names from SQL string (e.g., :param_name)"""
+    return re.findall(r':(\w+)', sql)
+
+def validate_params(sql: str, params: Dict[str, Any]) -> None:
+    """Validate that all required parameters are provided"""
+    required = _extract_params(sql)
+    provided = set(params.keys()) if params else set()
+    missing = set(required) - provided
+    
+    if missing:
+        raise ValueError(f"Missing required parameters: {', '.join(missing)}")
+
+def run_id(db: Database, registry: Dict[str, str], query_id: str, params: Optional[Dict[str, Any]] = None) -> Any:
+    """Execute a query by ID from a query registry."""
+    # Get query from registry
+    if query_id not in registry:
+        raise ValueError(f"Query ID '{query_id}' not found in registry")
+    
+    sql = registry[query_id]
+    params = params or {}
+    
+    # Validate parameters
+    validate_params(sql, params)
+    
+    # Execute query
+    try:
+        result = db.conn.execute(text(sql), params)
+        return result
+    except Exception as e:
+        logger.error(f"Query '{query_id}' failed: {e}", exc_info=True)
+        raise Exception(f"Failed to execute query '{query_id}': {str(e)}") from e
+
+
+# %% ../nbs/02_utils_sql.ipynb 12
+def insert_only(db: Database, table_name: str, record: Dict[str, Any], conflict_cols: List[str], auto_commit: bool = True) -> None:
+    """Insert a single record only if it doesn't exist (ignores conflicts)."""
+    db_type = get_db_type()
+    columns = list(record.keys())
+    placeholders = [f":{col}" for col in columns]
+    
+    if db_type == "POSTGRESQL":
+        # ON CONFLICT DO NOTHING
+        conflict_clause = f"ON CONFLICT ({', '.join(conflict_cols)}) DO NOTHING"
+        sql = f"""
+            INSERT INTO {table_name} ({', '.join(columns)})
+            VALUES ({', '.join(placeholders)})
+            {conflict_clause}
+        """
+    else:  # SQLite
+        # INSERT OR IGNORE
+        sql = f"""
+            INSERT OR IGNORE INTO {table_name} ({', '.join(columns)})
+            VALUES ({', '.join(placeholders)})
+        """
+    
+    try:
+        db.conn.execute(text(sql), record)
+        if auto_commit:
+            db.conn.commit()
+    except Exception as e:
+        logger.error(f"Insert into '{table_name}' failed: {e}", exc_info=True)
+        if auto_commit:
+            db.conn.rollback()
+        raise Exception(f"Failed to insert record into {table_name}: {str(e)}") from e
+
+def bulk_insert_only(db: Database, table_name: str, records: List[Dict[str, Any]], conflict_cols: List[str], auto_commit: bool = True) -> None:
+    """Insert multiple records, skipping conflicts (optimized batch operation)."""
+    if not records:
+        return
+    
+    db_type = get_db_type()
+    columns = list(records[0].keys())
+    placeholders = [f":{col}" for col in columns]
+    
+    if db_type == "POSTGRESQL":
+        conflict_clause = f"ON CONFLICT ({', '.join(conflict_cols)}) DO NOTHING"
+        sql = f"""
+            INSERT INTO {table_name} ({', '.join(columns)})
+            VALUES ({', '.join(placeholders)})
+            {conflict_clause}
+        """
+    else:  # SQLite
+        sql = f"""
+            INSERT OR IGNORE INTO {table_name} ({', '.join(columns)})
+            VALUES ({', '.join(placeholders)})
+        """
+    
+    try:
+        for record in records:
+            db.conn.execute(text(sql), record)
+        if auto_commit:
+            db.conn.commit()
+    except Exception as e:
+        logger.error(f"Bulk insert into '{table_name}' failed: {e}", exc_info=True)
+        if auto_commit:
+            db.conn.rollback()
+        raise Exception(f"Failed to bulk insert into {table_name}: {str(e)}") from e
+
+# %% ../nbs/02_utils_sql.ipynb 16
+def upsert(db: Database, table_name: str, record: Dict[str, Any], 
+           conflict_cols: List[str], update_cols: Optional[List[str]] = None, auto_commit: bool = True) -> None:
+    """Insert a record or update if it exists (upsert)."""
+    db_type = get_db_type()
+    columns = list(record.keys())
+    placeholders = [f":{col}" for col in columns]
+    
+    # Determine which columns to update
+    if update_cols is None:
+        update_cols = [col for col in columns if col not in conflict_cols]
+    
+    if db_type == "POSTGRESQL":
+        # ON CONFLICT DO UPDATE
+        update_set = ', '.join([f"{col} = EXCLUDED.{col}" for col in update_cols])
+        sql = f"""
+            INSERT INTO {table_name} ({', '.join(columns)})
+            VALUES ({', '.join(placeholders)})
+            ON CONFLICT ({', '.join(conflict_cols)}) 
+            DO UPDATE SET {update_set}
+        """
+    else:  # SQLite
+        # INSERT OR REPLACE
+        sql = f"""
+            INSERT OR REPLACE INTO {table_name} ({', '.join(columns)})
+            VALUES ({', '.join(placeholders)})
+        """
+    
+    try:
+        db.conn.execute(text(sql), record)
+        if auto_commit:
+            db.conn.commit()
+    except Exception as e:
+        logger.error(f"Upsert into '{table_name}' failed: {e}", exc_info=True)
+        if auto_commit:
+            db.conn.rollback()
+        raise Exception(f"Failed to upsert record into {table_name}: {str(e)}") from e
+
+def bulk_upsert(db: Database, table_name: str, records: List[Dict[str, Any]], 
+                conflict_cols: List[str], update_cols: Optional[List[str]] = None, auto_commit: bool = True) -> None:
+    """Insert or update multiple records (optimized batch operation)."""
+    if not records:
+        return
+    
+    db_type = get_db_type()
+    columns = list(records[0].keys())
+    placeholders = [f":{col}" for col in columns]
+    
+    # Determine which columns to update
+    if update_cols is None:
+        update_cols = [col for col in columns if col not in conflict_cols]
+    
+    if db_type == "POSTGRESQL":
+        update_set = ', '.join([f"{col} = EXCLUDED.{col}" for col in update_cols])
+        sql = f"""
+            INSERT INTO {table_name} ({', '.join(columns)})
+            VALUES ({', '.join(placeholders)})
+            ON CONFLICT ({', '.join(conflict_cols)}) 
+            DO UPDATE SET {update_set}
+        """
+    else:  # SQLite
+        sql = f"""
+            INSERT OR REPLACE INTO {table_name} ({', '.join(columns)})
+            VALUES ({', '.join(placeholders)})
+        """
+    
+    try:
+        for record in records:
+            db.conn.execute(text(sql), record)
+        if auto_commit:
+            db.conn.commit()
+    except Exception as e:
+        logger.error(f"Bulk upsert into '{table_name}' failed: {e}", exc_info=True)
+        if auto_commit:
+            db.conn.rollback()
+        raise Exception(f"Failed to bulk upsert into {table_name}: {str(e)}") from e
+
+# %% ../nbs/02_utils_sql.ipynb 20
+def get_by_id(db: Database, table_name: str, id_value: Any, id_col: str = "id") -> Any:
+    """Get a single record by ID."""
+    sql = f"SELECT * FROM {table_name} WHERE {id_col} = :id_value"
+    try:
+        result = db.conn.execute(text(sql), {"id_value": id_value})
+        return result
+    except Exception as e:
+        logger.error(f"Get by ID from '{table_name}' failed: {e}", exc_info=True)
+        raise Exception(f"Failed to get record from {table_name}: {str(e)}") from e
+
+def update_record(db: Database, table_name: str, id_value: Any, 
+                  id_col: str = "id", auto_commit: bool = True, **updates) -> None:
+    """Update a single record by ID."""
+    if not updates:
+        return
+    
+    set_clause = ', '.join([f"{col} = :{col}" for col in updates.keys()])
+    sql = f"UPDATE {table_name} SET {set_clause} WHERE {id_col} = :id_value"
+    
+    params = {**updates, "id_value": id_value}
+    
+    try:
+        db.conn.execute(text(sql), params)
+        if auto_commit:
+            db.conn.commit()
+    except Exception as e:
+        logger.error(f"Update record in '{table_name}' failed: {e}", exc_info=True)
+        if auto_commit:
+            db.conn.rollback()
+        raise Exception(f"Failed to update record in {table_name}: {str(e)}") from e
+
+def delete_record(db: Database, table_name: str, id_value: Any, id_col: str = "id", auto_commit: bool = True) -> None:
+    """Delete a single record by ID."""
+    sql = f"DELETE FROM {table_name} WHERE {id_col} = :id_value"
+    
+    try:
+        db.conn.execute(text(sql), {"id_value": id_value})
+        if auto_commit:
+            db.conn.commit()
+    except Exception as e:
+        logger.error(f"Delete from '{table_name}' failed: {e}", exc_info=True)
+        if auto_commit:
+            db.conn.rollback()
+        raise Exception(f"Failed to delete record from {table_name}: {str(e)}") from e
+
+def bulk_delete(db: Database, table_name: str, id_list: List[Any], id_col: str = "id", auto_commit: bool = True) -> None:
+    """Delete multiple records by ID list."""
+    if not id_list:
+        return
+    
+    # Create placeholder for IN clause
+    placeholders = ', '.join([f":id_{i}" for i in range(len(id_list))])
+    sql = f"DELETE FROM {table_name} WHERE {id_col} IN ({placeholders})"
+    
+    # Build params dict
+    params = {f"id_{i}": val for i, val in enumerate(id_list)}
+    
+    try:
+        db.conn.execute(text(sql), params)
+        if auto_commit:
+            db.conn.commit()
+    except Exception as e:
+        logger.error(f"Bulk delete from '{table_name}' failed: {e}", exc_info=True)
+        if auto_commit:
+            db.conn.rollback()
+        raise Exception(f"Failed to bulk delete from {table_name}: {str(e)}") from e
+
+# %% ../nbs/02_utils_sql.ipynb 26
+@contextmanager
+def with_transaction(db: Database):
+    """Context manager for safe transaction handling with auto-rollback on error."""
+    try:
+        yield db
+        db.conn.commit()
+    except Exception as e:
+        db.conn.rollback()
+        raise e
+
+def paginate_sql(sql: str, page: int, page_size: int) -> str:
+    """Add LIMIT/OFFSET pagination to a SQL query."""
+    offset = (page - 1) * page_size
+    return f"{sql.rstrip(';')} LIMIT {page_size} OFFSET {offset}"
+
+def batch_execute(db: Database, operation_func, items: List[Any], batch_size: int = 100) -> None:
+    """Execute an operation on items in batches with commits after each batch."""
+    for i in range(0, len(items), batch_size):
+        batch = items[i:i + batch_size]
+        try:
+            for item in batch:
+                operation_func(db, item)
+            db.conn.commit()
+        except Exception as e:
+            logger.error(f"Batch execution failed at batch {i//batch_size + 1}: {e}", exc_info=True)
+            db.conn.rollback()
+            raise Exception(f"Batch execution failed at batch {i//batch_size + 1}: {str(e)}") from e
+
+# %% ../nbs/02_utils_sql.ipynb 31
+def to_cents(dollars: str | float | None) -> int | None:
+    """Convert dollar amount to integer cents for database storage."""
+    if dollars is None or dollars == '':
+        return None
+    try:
+        return int(float(dollars) * 100)
+    except (ValueError, TypeError):
+        return None
+
+
+def from_cents(cents: int | None) -> str:
+    """Convert integer cents to formatted dollar string for display."""
+    if cents is None:
+        return "$0.00"
+    dollars = cents / 100
+    if dollars < 0:
+        return f"-${abs(dollars):,.2f}"
+    return f"${dollars:,.2f}"