tessl/maven-com-dmetasoul--lakesoul-common

Core utilities and metadata management library for the LakeSoul lakehouse framework providing database connection management, RBAC authorization, protobuf serialization, and native library integration.

—

Pending

Overview

Eval results

Files

Database Connection Management

Name: tessl/maven-com-dmetasoul--lakesoul-common
Author: tessl

The database connection management system provides efficient PostgreSQL connectivity using HikariCP connection pooling. This system handles all database connections for metadata operations, providing both DataSource and Connection-level access with proper resource management.

Capabilities

DBConnector Class

The central connection management class providing singleton access to database connections with HikariCP pooling.

/**
 * Database connection management using HikariCP connection pooling
 * Provides singleton access to database connections for PostgreSQL backend
 */
public class DBConnector {
    // Static methods for singleton access - no public constructor
}

Connection Access

Methods for obtaining database connections and data sources with proper resource management.

/**
 * Get HikariCP DataSource instance (singleton)
 * Creates new connection pool on first access using database configuration
 * @return DataSource instance for connection pooling
 */
public static synchronized DataSource getDS();

/**
 * Get database connection from connection pool
 * @return Connection instance from HikariCP pool
 * @throws SQLException if connection cannot be obtained
 */
public static synchronized Connection getConn() throws SQLException;

Connection Cleanup

Methods for properly closing connections and managing connection pool lifecycle.

/**
 * Close all connections and shutdown connection pool
 * Should be called during application shutdown
 */
public static synchronized void closeAllConnections();

/**
 * Close specific database connection
 * @param conn Connection to close (null-safe)
 */
public static void closeConn(Connection conn);

/**
 * Close statement and connection
 * @param statement Statement to close (null-safe)
 * @param conn Connection to close (null-safe)
 */
public static void closeConn(Statement statement, Connection conn);

/**
 * Close result set, statement, and connection
 * @param set ResultSet to close (null-safe)
 * @param statement Statement to close (null-safe)  
 * @param conn Connection to close (null-safe)
 */
public static void closeConn(ResultSet set, Statement statement, Connection conn);

Database Configuration

Database configuration is managed through the DBUtil and DataBaseProperty classes which provide connection parameters.

/**
 * Utility class for database configuration management
 */
public class DBUtil {
    // Configuration keys for database connection
    public static final String urlKey = "lakesoul.pg.url";
    public static final String usernameKey = "lakesoul.pg.username"; 
    public static final String passwordKey = "lakesoul.pg.password";
    public static final String domainKey = "lakesoul.current.domain";
    
    /**
     * Get database connection information from configuration
     * @return DataBaseProperty object with connection details
     */
    public static DataBaseProperty getDBInfo();
    
    /**
     * Fill HikariCP DataSource configuration with connection parameters
     * @param config HikariConfig object to configure
     */
    public static void fillDataSourceConfig(HikariConfig config);
}

/**
 * Data transfer object for database connection properties
 */
public class DataBaseProperty {
    /**
     * Get JDBC driver class name
     * @return Driver class name (typically "org.postgresql.Driver")
     */
    public String getDriver();
    
    /**
     * Get database connection URL
     * @return JDBC URL for PostgreSQL connection
     */
    public String getUrl();
    
    /**
     * Get database username
     * @return Username for database authentication
     */
    public String getUsername();
    
    /**
     * Get database password
     * @return Password for database authentication
     */
    public String getPassword();
    
    /**
     * Get database name
     * @return Name of the target database
     */
    public String getDbName();
    
    /**
     * Get database host
     * @return Hostname or IP address of database server
     */
    public String getHost();
    
    /**
     * Get database port
     * @return Port number for database connection
     */
    public int getPort();
    
    /**
     * Get maximum commit attempt count
     * @return Maximum number of retry attempts for commits
     */
    public int getMaxCommitAttempt();
    
    // Corresponding setter methods
    public void setDriver(String driver);
    public void setUrl(String url);
    public void setUsername(String username);
    public void setPassword(String password);
    public void setDbName(String dbName);
    public void setHost(String host);
    public void setPort(int port);
    public void setMaxCommitAttempt(int maxCommitAttempt);
    
    /**
     * String representation of database properties
     * @return Formatted string with connection details (password masked)
     */
    public String toString();
}

DAO Factory

The DBFactory class provides singleton access to Data Access Objects that use the connection management system.

/**
 * Factory class for creating DAO instances using singleton pattern
 * All DAOs use the DBConnector for database access
 */
public class DBFactory {
    /**
     * Get NamespaceDao singleton instance
     * @return NamespaceDao instance for namespace operations
     */
    public static NamespaceDao getNamespaceDao();
    
    /**
     * Get TableInfoDao singleton instance
     * @return TableInfoDao instance for table metadata operations
     */
    public static TableInfoDao getTableInfoDao();
    
    /**
     * Get TableNameIdDao singleton instance
     * @return TableNameIdDao instance for table name mapping operations
     */
    public static TableNameIdDao getTableNameIdDao();
    
    /**
     * Get TablePathIdDao singleton instance
     * @return TablePathIdDao instance for table path mapping operations
     */
    public static TablePathIdDao getTablePathIdDao();
    
    /**
     * Get DataCommitInfoDao singleton instance
     * @return DataCommitInfoDao instance for data commit operations
     */
    public static DataCommitInfoDao getDataCommitInfoDao();
    
    /**
     * Get PartitionInfoDao singleton instance
     * @return PartitionInfoDao instance for partition metadata operations
     */
    public static PartitionInfoDao getPartitionInfoDao();
}

Usage Examples:

import com.dmetasoul.lakesoul.meta.DBConnector;
import com.dmetasoul.lakesoul.meta.DBUtil;
import com.dmetasoul.lakesoul.meta.DataBaseProperty;
import javax.sql.DataSource;
import java.sql.*;

// Basic connection usage
public class DatabaseExample {
    
    public void basicConnectionExample() throws SQLException {
        // Get connection from pool
        Connection conn = null;
        PreparedStatement stmt = null;
        ResultSet rs = null;
        
        try {
            // Get connection from HikariCP pool
            conn = DBConnector.getConn();
            
            // Execute query
            stmt = conn.prepareStatement("SELECT * FROM table_info WHERE table_id = ?");
            stmt.setString(1, "table_123");
            rs = stmt.executeQuery();
            
            // Process results
            while (rs.next()) {
                String tableName = rs.getString("table_name");
                String tablePath = rs.getString("table_path");
                System.out.println("Table: " + tableName + " at " + tablePath);
            }
            
        } finally {
            // Proper cleanup - connection returned to pool
            DBConnector.closeConn(rs, stmt, conn);
        }
    }
    
    public void dataSourceExample() {
        // Get DataSource for advanced usage
        DataSource ds = DBConnector.getDS();
        
        // Use with connection pools, frameworks, etc.
        try (Connection conn = ds.getConnection()) {
            // Your database operations here
            DatabaseMetaData metaData = conn.getMetaData();
            System.out.println("Database: " + metaData.getDatabaseProductName());
            System.out.println("Version: " + metaData.getDatabaseProductVersion());
        } catch (SQLException e) {
            e.printStackTrace();
        }
    }
    
    public void configurationExample() {
        // Get database configuration
        DataBaseProperty dbProps = DBUtil.getDBInfo();
        
        System.out.println("Database URL: " + dbProps.getUrl());
        System.out.println("Database Name: " + dbProps.getDbName());
        System.out.println("Host: " + dbProps.getHost());
        System.out.println("Port: " + dbProps.getPort());
        System.out.println("Username: " + dbProps.getUsername());
        System.out.println("Max Commit Attempts: " + dbProps.getMaxCommitAttempt());
        
        // Note: Password is not exposed for security
    }
    
    public void shutdownExample() {
        // During application shutdown
        try {
            // Close all connections and shutdown pool
            DBConnector.closeAllConnections();
            System.out.println("Database connections closed successfully");
        } catch (Exception e) {
            System.err.println("Error closing database connections: " + e.getMessage());
        }
    }
}

Configuration Requirements:

The database connection requires the following system properties or environment variables:

# Required PostgreSQL connection settings
lakesoul.pg.url=jdbc:postgresql://localhost:5432/lakesoul_test
lakesoul.pg.username=lakesoul_test
lakesoul.pg.password=lakesoul_test

# Optional security domain setting
lakesoul.current.domain=public

Connection Pool Configuration:

The HikariCP connection pool is automatically configured with optimal settings:

Driver: org.postgresql.Driver
Connection Validation: Automatic validation on borrow
Pool Sizing: Dynamic based on system resources
Connection Timeout: Configurable via HikariCP settings
Idle Timeout: Automatic cleanup of idle connections
Maximum Lifetime: Prevents connection leaks

Error Handling:

The connection management system handles various error scenarios:

Connection Failures: Automatic retry with exponential backoff
Pool Exhaustion: Blocking wait with timeout for available connections
Database Unavailability: Proper exception propagation with detailed error messages
Configuration Errors: Clear error messages during initialization

Thread Safety:

All connection management operations are thread-safe:

Singleton Initialization: Thread-safe lazy initialization using synchronized blocks
Connection Pool: HikariCP provides thread-safe connection pooling
Resource Cleanup: Safe cleanup operations with null checks
Concurrent Access: Multiple threads can safely obtain connections simultaneously

Install with Tessl CLI

npx tessl i tessl/maven-com-dmetasoul--lakesoul-common

docs

authorization-security.md

configuration-management.md

database-connection.md

entity-models.md

index.md

metadata-management.md

native-operations.md

scala-functional-api.md

tile.json