mirror of https://github.com/trustgraph-ai/trustgraph.git synced 2026-04-29 02:23:44 +02:00

Structure the tech specs directory (#836 )

Tech spec some subdirectories for different languages

2026-04-21 16:06:41 +01:00

21 KiB

Raw Blame History

layout	title	parent
default	तकनीकी विनिर्देश: कैसेंड्रा कॉन्फ़िगरेशन समेकन	Hindi (Beta)

तकनीकी विनिर्देश: कैसेंड्रा कॉन्फ़िगरेशन समेकन

Beta Translation: This document was translated via Machine Learning and as such may not be 100% accurate. All non-English languages are currently classified as Beta.

स्थिति: मसौदा लेखक: सहायक तिथि: 2024-09-03

अवलोकन

यह विनिर्देश ट्रस्टग्राफ कोडबेस में कैसेंड्रा कनेक्शन मापदंडों के लिए असंगत नामकरण और कॉन्फ़िगरेशन पैटर्न को संबोधित करता है। वर्तमान में, दो अलग-अलग पैरामीटर नामकरण योजनाएं मौजूद हैं (cassandra_* बनाम graph_*), जिससे भ्रम और रखरखाव जटिलता होती है।

समस्या विवरण

कोडबेस वर्तमान में कैसेंड्रा कॉन्फ़िगरेशन मापदंडों के दो अलग-अलग सेट का उपयोग करता है:

ज्ञान/कॉन्फ़िग/लाइब्रेरी मॉड्यूल निम्नलिखित का उपयोग करते हैं: cassandra_host (होस्ट की सूची) cassandra_user cassandra_password
ग्राफ/भंडारण मॉड्यूल निम्नलिखित का उपयोग करते हैं: graph_host (एकल होस्ट, कभी-कभी सूची में परिवर्तित) graph_username graph_password
असंगत कमांड-लाइन एक्सपोजर: कुछ प्रोसेसर (जैसे, kg-store) कैसेंड्रा सेटिंग्स को कमांड-लाइन तर्कों के रूप में उजागर नहीं करते हैं अन्य प्रोसेसर उन्हें अलग-अलग नामों और प्रारूपों के साथ उजागर करते हैं सहायता पाठ पर्यावरण चर डिफ़ॉल्ट को प्रतिबिंबित नहीं करता है

दोनों पैरामीटर सेट एक ही कैसेंड्रा क्लस्टर से जुड़ते हैं, लेकिन अलग-अलग नामकरण सम्मेलनों के साथ, जिससे: उपयोगकर्ताओं के लिए कॉन्फ़िगरेशन भ्रम रखरखाव का बढ़ता बोझ असंगत प्रलेखन गलत कॉन्फ़िगरेशन की संभावना कुछ प्रोसेसर में कमांड-लाइन के माध्यम से सेटिंग्स को ओवरराइड करने में असमर्थता

प्रस्तावित समाधान

1. पैरामीटर नामों का मानकीकरण

सभी मॉड्यूल सुसंगत cassandra_* पैरामीटर नामों का उपयोग करेंगे: cassandra_host - होस्ट की सूची (आंतरिक रूप से सूची के रूप में संग्रहीत) cassandra_username - प्रमाणीकरण के लिए उपयोगकर्ता नाम cassandra_password - प्रमाणीकरण के लिए पासवर्ड

2. कमांड-लाइन तर्क

सभी प्रोसेसर को कैसेंड्रा कॉन्फ़िगरेशन को कमांड-लाइन तर्कों के माध्यम से उजागर करना होगा: --cassandra-host - होस्ट की अल्पविराम-विभाजित सूची --cassandra-username - प्रमाणीकरण के लिए उपयोगकर्ता नाम --cassandra-password - प्रमाणीकरण के लिए पासवर्ड

3. पर्यावरण चर बैकअप

यदि कमांड-लाइन पैरामीटर स्पष्ट रूप से प्रदान नहीं किए जाते हैं, तो सिस्टम पर्यावरण चर की जांच करेगा: CASSANDRA_HOST - होस्ट की अल्पविराम-विभाजित सूची CASSANDRA_USERNAME - प्रमाणीकरण के लिए उपयोगकर्ता नाम CASSANDRA_PASSWORD - प्रमाणीकरण के लिए पासवर्ड

4. डिफ़ॉल्ट मान

यदि न तो कमांड-लाइन पैरामीटर और न ही पर्यावरण चर निर्दिष्ट हैं: cassandra_host डिफ़ॉल्ट रूप से ["cassandra"] है cassandra_username डिफ़ॉल्ट रूप से None है (कोई प्रमाणीकरण नहीं) cassandra_password डिफ़ॉल्ट रूप से None है (कोई प्रमाणीकरण नहीं)

5. सहायता पाठ आवश्यकताएँ

--help आउटपुट को: जब सेट किया गया हो तो पर्यावरण चर मानों को डिफ़ॉल्ट के रूप में दिखाना चाहिए पासवर्ड मानों को कभी भी प्रदर्शित नहीं करना चाहिए (इसके बजाय **** या <set> दिखाएं) सहायता पाठ में समाधान क्रम को स्पष्ट रूप से इंगित करना चाहिए

उदाहरण सहायता आउटपुट:

--cassandra-host HOST
    Cassandra host list, comma-separated (default: prod-cluster-1,prod-cluster-2)
    [from CASSANDRA_HOST environment variable]

--cassandra-username USERNAME
    Cassandra username (default: cassandra_user)
    [from CASSANDRA_USERNAME environment variable]
    
--cassandra-password PASSWORD  
    Cassandra password (default: <set from environment>)

कार्यान्वयन विवरण

पैरामीटर समाधान का क्रम

प्रत्येक कैसेंड्रा पैरामीटर के लिए, समाधान का क्रम इस प्रकार होगा:

कमांड-लाइन तर्क मान
पर्यावरण चर (CASSANDRA_*)
डिफ़ॉल्ट मान

होस्ट पैरामीटर हैंडलिंग

cassandra_host पैरामीटर: कमांड-लाइन अल्पविराम-विभाजित स्ट्रिंग स्वीकार करता है: --cassandra-host "host1,host2,host3" पर्यावरण चर अल्पविराम-विभाजित स्ट्रिंग स्वीकार करता है: CASSANDRA_HOST="host1,host2,host3" आंतरिक रूप से हमेशा सूची के रूप में संग्रहीत किया जाता है: ["host1", "host2", "host3"] एकल होस्ट: "localhost" → ["localhost"] में परिवर्तित पहले से ही एक सूची: ["host1", "host2"] → जैसा है उपयोग किया जाता है

प्रमाणीकरण तर्क

प्रमाणीकरण का उपयोग तब किया जाएगा जब cassandra_username और cassandra_password दोनों प्रदान किए जाते हैं:

if cassandra_username and cassandra_password:
    # Use SSL context and PlainTextAuthProvider
else:
    # Connect without authentication

संशोधित करने योग्य फ़ाइलें

`graph_*` पैरामीटर का उपयोग करने वाले मॉड्यूल (जिन्हें बदला जाना है):

trustgraph-flow/trustgraph/storage/triples/cassandra/write.py trustgraph-flow/trustgraph/storage/objects/cassandra/write.py trustgraph-flow/trustgraph/storage/rows/cassandra/write.py trustgraph-flow/trustgraph/query/triples/cassandra/service.py

`cassandra_*` पैरामीटर का उपयोग करने वाले मॉड्यूल (जिन्हें पर्यावरण बैकअप के साथ अपडेट किया जाना है):

trustgraph-flow/trustgraph/tables/config.py trustgraph-flow/trustgraph/tables/knowledge.py trustgraph-flow/trustgraph/tables/library.py trustgraph-flow/trustgraph/storage/knowledge/store.py trustgraph-flow/trustgraph/cores/knowledge.py trustgraph-flow/trustgraph/librarian/librarian.py trustgraph-flow/trustgraph/librarian/service.py trustgraph-flow/trustgraph/config/service/service.py trustgraph-flow/trustgraph/cores/service.py

अपडेट करने योग्य परीक्षण फ़ाइलें:

tests/unit/test_cores/test_knowledge_manager.py tests/unit/test_storage/test_triples_cassandra_storage.py tests/unit/test_query/test_triples_cassandra_query.py tests/integration/test_objects_cassandra_integration.py

कार्यान्वयन रणनीति

चरण 1: सामान्य कॉन्फ़िगरेशन हेल्पर बनाएं

सभी प्रोसेसरों में कैसेंड्रा कॉन्फ़िगरेशन को मानकीकृत करने के लिए उपयोगिता फ़ंक्शन बनाएं:

import os
import argparse

def get_cassandra_defaults():
    """Get default values from environment variables or fallback."""
    return {
        'host': os.getenv('CASSANDRA_HOST', 'cassandra'),
        'username': os.getenv('CASSANDRA_USERNAME'),
        'password': os.getenv('CASSANDRA_PASSWORD')
    }

def add_cassandra_args(parser: argparse.ArgumentParser):
    """
    Add standardized Cassandra arguments to an argument parser.
    Shows environment variable values in help text.
    """
    defaults = get_cassandra_defaults()
    
    # Format help text with env var indication
    host_help = f"Cassandra host list, comma-separated (default: {defaults['host']})"
    if 'CASSANDRA_HOST' in os.environ:
        host_help += " [from CASSANDRA_HOST]"
    
    username_help = f"Cassandra username"
    if defaults['username']:
        username_help += f" (default: {defaults['username']})"
        if 'CASSANDRA_USERNAME' in os.environ:
            username_help += " [from CASSANDRA_USERNAME]"
    
    password_help = "Cassandra password"
    if defaults['password']:
        password_help += " (default: <set>)"
        if 'CASSANDRA_PASSWORD' in os.environ:
            password_help += " [from CASSANDRA_PASSWORD]"
    
    parser.add_argument(
        '--cassandra-host',
        default=defaults['host'],
        help=host_help
    )
    
    parser.add_argument(
        '--cassandra-username',
        default=defaults['username'],
        help=username_help
    )
    
    parser.add_argument(
        '--cassandra-password',
        default=defaults['password'],
        help=password_help
    )

def resolve_cassandra_config(args) -> tuple[list[str], str|None, str|None]:
    """
    Convert argparse args to Cassandra configuration.
    
    Returns:
        tuple: (hosts_list, username, password)
    """
    # Convert host string to list
    if isinstance(args.cassandra_host, str):
        hosts = [h.strip() for h in args.cassandra_host.split(',')]
    else:
        hosts = args.cassandra_host
    
    return hosts, args.cassandra_username, args.cassandra_password

चरण 2: `graph_*` पैरामीटर का उपयोग करके मॉड्यूल को अपडेट करें

पैरामीटर नामों को graph_* से cassandra_* में बदलें
कस्टम add_args() विधियों को मानकीकृत add_cassandra_args() से बदलें
सामान्य कॉन्फ़िगरेशन सहायक फ़ंक्शन का उपयोग करें
दस्तावेज़ स्ट्रिंग को अपडेट करें

उदाहरण परिवर्तन:

# OLD CODE
@staticmethod
def add_args(parser):
    parser.add_argument(
        '-g', '--graph-host',
        default="localhost",
        help=f'Graph host (default: localhost)'
    )
    parser.add_argument(
        '--graph-username',
        default=None,
        help=f'Cassandra username'
    )

# NEW CODE  
@staticmethod
def add_args(parser):
    FlowProcessor.add_args(parser)
    add_cassandra_args(parser)  # Use standard helper

चरण 3: `cassandra_*` पैरामीटर का उपयोग करके मॉड्यूल को अपडेट करें

उन स्थानों पर कमांड-लाइन तर्क समर्थन जोड़ें जहां यह गायब है (उदाहरण के लिए, kg-store)
मौजूदा तर्क परिभाषाओं को add_cassandra_args() से बदलें
सुसंगत समाधान के लिए resolve_cassandra_config() का उपयोग करें
सुसंगत होस्ट सूची प्रबंधन सुनिश्चित करें

चरण 4: परीक्षण और दस्तावेज़ को अपडेट करें

सभी परीक्षण फ़ाइलों को नए पैरामीटर नामों का उपयोग करने के लिए अपडेट करें
CLI दस्तावेज़ को अपडेट करें
API दस्तावेज़ को अपडेट करें
पर्यावरण चर दस्तावेज़ जोड़ें

पिछली अनुकूलता

संक्रमण के दौरान पिछली अनुकूलता बनाए रखने के लिए:

graph_* पैरामीटर के लिए अवरोधन चेतावनी
पैरामीटर उपनाम - शुरू में पुराने और नए दोनों नामों को स्वीकार करें
कई रिलीज़ में चरणबद्ध कार्यान्वयन
माइग्रेशन गाइड के साथ दस्तावेज़ अपडेट

पिछली अनुकूलता कोड का उदाहरण:

def __init__(self, **params):
    # Handle deprecated graph_* parameters
    if 'graph_host' in params:
        warnings.warn("graph_host is deprecated, use cassandra_host", DeprecationWarning)
        params.setdefault('cassandra_host', params.pop('graph_host'))
    
    if 'graph_username' in params:
        warnings.warn("graph_username is deprecated, use cassandra_username", DeprecationWarning)
        params.setdefault('cassandra_username', params.pop('graph_username'))
    
    # ... continue with standard resolution

परीक्षण रणनीति

यूनिट परीक्षण कॉन्फ़िगरेशन रिज़ॉल्यूशन लॉजिक के लिए
विभिन्न कॉन्फ़िगरेशन संयोजनों के साथ एकीकरण परीक्षण
पर्यावरण चर परीक्षण
पिछड़ा संगतता परीक्षण अप्रचलित मापदंडों के साथ
डॉकर कंपोज़ परीक्षण पर्यावरण चर के साथ

दस्तावेज़ अपडेट

सभी CLI कमांड दस्तावेज़ों को अपडेट करें
API दस्तावेज़ों को अपडेट करें
माइग्रेशन गाइड बनाएं
डॉकर कंपोज़ उदाहरणों को अपडेट करें
कॉन्फ़िगरेशन संदर्भ दस्तावेज़ को अपडेट करें

जोखिम और निवारण

जोखिम	प्रभाव	निवारण
उपयोगकर्ताओं के लिए ब्रेकिंग परिवर्तन	उच्च	पिछड़े संगतता अवधि लागू करें
संक्रमण के दौरान कॉन्फ़िगरेशन भ्रम	मध्यम	स्पष्ट दस्तावेज़ और अवमूल्यन चेतावनियाँ
परीक्षण विफलताएँ	मध्यम	व्यापक परीक्षण अपडेट
डॉकर परिनियोजन मुद्दे	उच्च	सभी डॉकर कंपोज़ उदाहरणों को अपडेट करें

सफलता मानदंड

[ ] सभी मॉड्यूल सुसंगत cassandra_* पैरामीटर नामों का उपयोग करते हैं [ ] सभी प्रोसेसर कमांड-लाइन तर्कों के माध्यम से कैसेंड्रा सेटिंग्स को उजागर करते हैं [ ] कमांड-लाइन सहायता पाठ पर्यावरण चर डिफ़ॉल्ट दिखाता है [ ] पासवर्ड मान कभी भी सहायता पाठ में प्रदर्शित नहीं होते हैं [ ] पर्यावरण चर बैकअप सही ढंग से काम करता है [ ] cassandra_host को आंतरिक रूप से लगातार एक सूची के रूप में संभाला जाता है [ ] कम से कम 2 रिलीज़ के लिए पिछड़े संगतता बनाए रखी जाती है [ ] सभी परीक्षण नए कॉन्फ़िगरेशन सिस्टम के साथ पास होते हैं [ ] दस्तावेज़ पूरी तरह से अपडेट किया गया है [ ] डॉकर कंपोज़ उदाहरण पर्यावरण चर के साथ काम करते हैं

समयरेखा

सप्ताह 1: सामान्य कॉन्फ़िगरेशन हेल्पर लागू करें और graph_* मॉड्यूल को अपडेट करें सप्ताह 2: मौजूदा cassandra_* मॉड्यूल में पर्यावरण चर समर्थन जोड़ें सप्ताह 3: परीक्षण और दस्तावेज़ अपडेट करें सप्ताह 4: एकीकरण परीक्षण और बग फिक्स

भविष्य के विचार

अन्य डेटाबेस कॉन्फ़िगरेशन (जैसे, Elasticsearch) के लिए इस पैटर्न को विस्तारित करने पर विचार करें कॉन्फ़िगरेशन सत्यापन और बेहतर त्रुटि संदेश लागू करें कैसेंड्रा कनेक्शन पूलिंग कॉन्फ़िगरेशन के लिए समर्थन जोड़ें कॉन्फ़िगरेशन फ़ाइल समर्थन (.env फ़ाइलें) जोड़ने पर विचार करें

21 KiB Raw Blame History