hana-developer-cli-tool-example database-client-implementation.instructions.md

Database Client Implementation Guidelines

Use this guide when creating or modifying database client adapter files in the utils/database/ directory.

Scope and Purpose

This guide applies to database-specific client implementations that provide a unified interface for database operations across different database systems and connection modes:

• index.js - Abstract base class dbClientClass
• hanaCDS.js - SAP HANA via CDS connection
• hanaDirect.js - SAP HANA direct connection (non-CDS)
• postgres.js - PostgreSQL via CDS connection
• sqlite.js - SQLite via CDS connection

Critical Principles

1. Abstraction: All clients extend the abstract dbClientClass base class
2. Factory Pattern: Use static factory method for client instantiation
3. Profile-Based: Support multiple connection profiles (CDS profiles)
4. Lifecycle Management: Implement proper connect/disconnect patterns
5. Error Handling: Provide database-specific error enrichment
6. Type Safety: Use JSDoc and TypeScript annotations
7. Credential Security: Handle credentials safely, never log passwords
8. Graceful Degradation: Handle missing credentials and connection failures

Abstract Base Class Pattern

Base Class Structure: utils/database/index.js

import * as base from '../base.js'
import cds from '@sap/cds'

/**
 * Database Client Abstract Super Class 
 * @class
 * @constructor
 * @public
 * @classdesc Database Client Abstract Level
 */
export default class dbClientClass {
    /**
     * Prompts current value
     * @type {typeof import("prompt")}
     */
    #prompts
    
    /**
     * CDS connection options
     * @type {Object}
     */
    #optionsCDS
    
    /**
     * CDS connection object - returned from cds.connect.to or hdb module instance
     * @type {Object}
     */
    #db
    
    /**
     * Database Client type/flavor
     * @type {String}
     */
    #clientType = 'generic'

    /**
     * Create an instance of the database client
     * @param {typeof import("prompt")} prompts - Input prompts current value
     * @param {Object} [optionsCDS] - Optional CDS connection options
     */
    constructor(prompts, optionsCDS) {
        this.#prompts = prompts
        this.#optionsCDS = optionsCDS
        base.setPrompts(prompts)
        base.debug(base.bundle.getText("debug.dbClientGenericProfile", [this.#prompts.profile]))
    }

    /**
     * Static Factory Method to initialize the DB Client in your selected Flavor
     * @param {object} prompts - Processed input prompts
     * @returns {Promise<dbClientClass>} Flavor-specific DB client class instance
     */
    static async getNewClient(prompts) {
        let childClass = Object
        
        if (!prompts.profile) {
            // HANA Without CDS - Direct connection
            prompts.profile = 'hybrid'
            const { default: classAccess } = await import("./hanaDirect.js")
            childClass = new classAccess(prompts)
        } else {
            // CDS based connectivity
            process.env.CDS_ENV = prompts.profile
            process.env.NODE_ENV = prompts.profile
            let optionsCDS = cds.env.requires.db
            
            if (!optionsCDS || !optionsCDS.kind) {
                throw new Error(base.bundle.getText("error.cdsProjectMissing"))
            }
            
            // Load credentials from connections utility
            const conn = await import("../connections.js")
            const credentials = await conn.getConnOptions(prompts)
            
            if (optionsCDS.kind === 'sqlite') {
                if (credentials && credentials.sqlite) {
                    optionsCDS.credentials = credentials.sqlite
                }
                const { default: classAccess } = await import("./sqlite.js")
                childClass = new classAccess(prompts, optionsCDS)
            }
            else if (optionsCDS.kind === 'postgres') {
                if (credentials && credentials.postgres) {
                    optionsCDS.credentials = credentials.postgres
                }
                const { default: classAccess } = await import("./postgres.js")
                childClass = new classAccess(prompts, optionsCDS)
            }
            else if (optionsCDS.kind === 'hana') {
                if (credentials && credentials.hana) {
                    optionsCDS.credentials = credentials.hana
                }
                const { default: classAccess } = await import("./hanaCDS.js")
                childClass = new classAccess(prompts, optionsCDS)
            }
            else {
                throw new Error(base.bundle.getText("error.unsupportedDbClient", [optionsCDS.kind]))
            }
        }
        return childClass
    }

    // Protected getters/setters
    getDB() { return this.#db }
    setDB(db) { this.#db = db }
    getPrompts() { return this.#prompts }
    getOptionsCDS() { return this.#optionsCDS }

    /**
     * Abstract method - must be implemented by child classes
     * @returns {Promise<object>}
     */
    async connect() {
        throw new Error(base.bundle.getText("error.abstractMethod", ["connect"]))
    }

    /**
     * Abstract method - must be implemented by child classes
     * @returns {Promise<void>}
     */
    async disconnect() {
        throw new Error(base.bundle.getText("error.abstractMethod", ["disconnect"]))
    }

    /**
     * Abstract method - must be implemented by child classes
     * @returns {Promise<Array>}
     */
    async listTables() {
        throw new Error(base.bundle.getText("error.abstractMethod", ["listTables"]))
    }
}