Alibabacloud Analyticdb Postgresql Ai Coaching Best Practice

ADBPG AI Coaching Best Practice

Build RAG-driven coaching systems using ADBPG Supabase (training data management) + ADBPG Vector Knowledge Base (RAG-driven intelligent coaching).

Core Capabilities:

Pre-check: Aliyun CLI >= 3.3.3 Required

> IMPORTANT: Run aliyun version to verify >= 3.3.3. If not installed or version too low, > run curl -fsSL https://aliyuncli.alicdn.com/setup.sh | bash to update, > or see references/cli-installation-guide.md for installation instructions. > > Then [MUST] run aliyun configure set --auto-plugin-install true to enable automatic plugin installation. > [MUST] run aliyun plugin update to ensure that any existing plugins on your local machine are always up-to-date.

[MUST] CLI User-Agent

> Every aliyun CLI command invocation must include: > --user-agent AlibabaCloud-Agent-Skills/alibabacloud-analyticdb-postgresql-ai-coaching-best-practice

[MUST] CLI AI-Mode Configuration

At the start of the Core Workflow (before any CLI invocation):

[MUST] Enable AI-Mode — AI-mode is required for Agent Skill execution. Run the following commands before any CLI invocation:

aliyun configure ai-mode enable
aliyun configure ai-mode set-user-agent --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-analyticdb-postgresql-ai-coaching-best-practice"

[MUST] Disable AI-Mode at EVERY exit point — Before delivering the final response for ANY reason, always disable AI-mode first. This applies to ALL exit paths: workflow success, workflow failure, error/exception, user cancellation, session end, or any other scenario where no further CLI commands will be executed. AI-mode is only used for Agent Skill invocation scenarios and MUST NOT remain enabled after the skill stops running.

aliyun configure ai-mode disable

Pre-check: Alibaba Cloud Credentials Required

> Security Rules: > - NEVER read, echo, or print AK/SK values > - NEVER ask the user to input AK/SK directly > - NEVER print passwords or API Keys in plain text in logs or stdout > - ONLY use aliyun configure list to check credential status > - When displaying API Keys, show only the first 6 characters + * (e.g., sk-abc1*)

aliyun configure list

If no valid profile exists, STOP here. Configure credentials outside of this session via aliyun configure or environment variables.

Scenario Description

| Scenario | Use Case | Target Users | |----------|----------|--------------| | Workflow Coaching | Guide professionals through structured business processes (sales cycles, project management) | Sales teams, project managers | | Decision Support | Help engineers evaluate trade-offs and make informed technical decisions | Engineers, architects | | Skill Development | Develop communication, negotiation, or technical skills through guided practice | Professionals, new hires | | Onboarding | Systematically guide new team members through technical and process onboarding | New employees, mentors |

Architecture

User (Web / Terminal / Agent)
           │
    ┌──────┴──────┐
    v             v
┌─────────────┐  ┌────────────────────────┐
│  Supabase   │  │  Agent Mode            │
│  (spb-xxx)  │  │  ChatWithKnowledgeBase │
│  - Domains  │  └───────────┬────────────┘
│  - Sessions │              │
└──────┬──────┘              │
       v                     v
┌────────────────────────────────────────┐
│  ADBPG Instance (gp-xxx) + KB          │
│  Domain Knowledge + RAG + LLM          │
└────────────────────────────────────────┘

RAM Policy

Required Permissions

| Operation | RAM Permission | |-----------|----------------| | Supabase Project Management | gpdb:CreateSupabaseProject, gpdb:GetSupabaseProject, gpdb:ModifySupabaseProjectSecurityIps | | ADBPG Instance Management | gpdb:CreateDBInstance, gpdb:DescribeDBInstances, gpdb:ModifySecurityIps | | Account Management | gpdb:DescribeAccounts, gpdb:CreateAccount | | Knowledge Base Operations | gpdb:InitVectorDatabase, gpdb:CreateNamespace, gpdb:CreateDocumentCollection, gpdb:UploadDocumentAsync, gpdb:ChatWithKnowledgeBase | | VPC Network | vpc:DescribeVpcs, vpc:DescribeVSwitches, vpc:DescribeVSwitchAttributes | | NAT Gateway & EIP | vpc:DescribeNatGateways, vpc:CreateNatGateway, vpc:DescribeEipAddresses, vpc:AllocateEipAddress, vpc:AssociateEipAddress, vpc:CreateSnatEntry |

Recommended System Policies: AliyunGPDBFullAccess, AliyunVPCFullAccess (or AliyunVPCReadOnlyAccess if NAT already exists)

See references/ram-policies.md for complete list.

> [MUST] Permission Failure Handling: When any command fails due to permission errors: > 1. Read references/ram-policies.md for required permissions > 2. Use ram-permission-diagnose skill to guide the user > 3. Pause and wait until user confirms permissions granted

Core Workflow

When user says "Help me set up an AI coaching system" or similar, execute the following steps:

> Smart Defaults Mode: User only needs minimal input (e.g., "北京i"). The agent auto-parses region, discovers VPC/VSwitch, generates passwords, and presents all parameters for one-click confirmation.

Step 1: Create Supabase Project

> Parameters to confirm for this step: > > | Parameter | Default | Notes | > |-----------|---------|-------| > | RegionId | Auto-parse | "北京i" → cn-beijing, "上海b" → cn-shanghai, "杭州" → cn-hangzhou, "深圳" → cn-shenzhen | > | ZoneId | Auto-parse | "北京i" → cn-beijing-i; query zones when only city provided | > | VpcId | Auto-discover | Query available VPCs, select one with most available IPs | > | VSwitchId | Auto-discover | Query VSwitches in target zone, select one with most available IPs | > | ProjectName | ai_coaching | Supabase project name | > | AccountPassword | Auto-generate | Password rules: 8-32 chars, at least 3 of uppercase/lowercase/digits/special (@#$%^&*), avoid ! |

#### 1.1 Check/Create NAT Gateway

> Important: Supabase public connection requires a NAT Gateway with SNAT rules in the VPC.

# Check existing NAT Gateways in VPC
aliyun vpc describe-nat-gateways --profile adbpg \
  --biz-region-id  --vpc-id  \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-analyticdb-postgresql-ai-coaching-best-practice

# 1.1a: Get VSwitch CIDR
aliyun vpc describe-vswitch-attributes --profile adbpg \
  --biz-region-id  --vswitch-id  \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-analyticdb-postgresql-ai-coaching-best-practice
Record: CidrBlock
1.1b: Create Enhanced NAT Gateway (requires user confirmation)
💰 Cost note: NAT Gateway incurs hourly charges
aliyun vpc create-nat-gateway --profile adbpg \
  --biz-region-id  --vpc-id  --vswitch-id  \
  --nat-type Enhanced \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-analyticdb-postgresql-ai-coaching-best-practice
Record: NatGatewayId and SnatTableIds.SnatTableId[0]
Poll until Status=Available
1.1c: Find or allocate EIP (requires user confirmation)
💰 Cost note: EIP incurs charges; release via VPC console when no longer needed
aliyun vpc describe-eip-addresses --profile adbpg \
  --biz-region-id  \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-analyticdb-postgresql-ai-coaching-best-practice
If no available EIP:
aliyun vpc allocate-eip-address --profile adbpg \
  --biz-region-id  \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-analyticdb-postgresql-ai-coaching-best-practice
Record: AllocationId and EipAddress
1.1d: Bindind EIP to NAT Gateway (requires user confirmation)
aliyun vpc associate-eip-address --profile adbpg \
  --biz-region-id  \
  --allocation-id  --instance-id  \
  --instance-type Nat \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-analyticdb-postgresql-ai-coaching-best-practice
1.1e: Create SNAT entry (requires user confirmation)
aliyun vpc create-snat-entry --profile adbpg \
  --biz-region-id  \
  --snat-table-id  \
  --source-cidr "" --snat-ip "" \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-analyticdb-postgresql-ai-coaching-best-practice

#### 1.2 Create Supabase Project

aliyun gpdb create-supabase-project --profile adbpg \
  --biz-region-id  --zone-id  \
  --project-name  --account-password '' \
  --security-ip-list "127.0.0.1" --vpc-id  --vswitch-id  \
  --project-spec 2C4G --storage-size 20 --pay-type Postpaid \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-analyticdb-postgresql-ai-coaching-best-practice

Record: ProjectId (sbp-xxx), PublicConnectUrl, API Keys (store securely; do NOT print full API Keys in logs)

> Timeout: Supabase project creation takes 5-10 minutes. Poll status until running: >

> aliyun gpdb get-supabase-project --profile adbpg \
>   --biz-region-id  --project-id  \
>   --user-agent AlibabaCloud-Agent-Skills/alibabacloud-analyticdb-postgresql-ai-coaching-best-practice
> 

Step 2: Initialize Coaching Platform Database

> Note: Steps 2-3 execute on Supabase Project, Steps 4-8 on ADBPG Instance. They are independent.

Modify whitelist, then connect via psql and execute schema from references/database-schema.md.

# Ask user for whitelist IP (do NOT use curl to external services)
Example: "Please provide the IP address to add to the whitelist"
Set whitelist
aliyun gpdb modify-supabase-project-security-ips --profile adbpg \
  --biz-region-id  --project-id  \
  --security-ip-list "" \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-analyticdb-postgresql-ai-coaching-best-practice

Step 3: Insert Preset Coaching Domains

Execute SQL from references/database-schema.md via psql to insert coaching domains and coaching personas.

Step 4: Discover / Select / Create ADBPG Instance

#### 4.1 Discover Existing Instances

aliyun gpdb describe-db-instances --profile adbpg \
  --biz-region-id  --page-size 100 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-analyticdb-postgresql-ai-coaching-best-practice

Filter results: DBInstanceStatus=Running AND VectorConfigurationStatus=enabled.

#### 4.2 User Selects Instance

Present qualifying instances to user:

> Available Instances (Running + Vector Enabled): > | # | Instance ID | Spec | Region | Status | Description | > |---|-------------|------|--------|--------|-------------| > | 1 | gp-xxxxx | 4C32G | cn-hangzhou | Running | Production | > | 2 | gp-yyyyy | 8C64G | cn-hangzhou | Running | Testing | > > Select an instance, or enter "Create New".

#### 4.3 Verify Selected Instance (when using existing)

aliyun gpdb describe-db-instance-attribute --profile adbpg \
  --db-instance-id  --region  \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-analyticdb-postgresql-ai-coaching-best-practice

Confirm: DBInstanceStatus=Running + VectorConfigurationStatus=enabled. Then proceed to Step 5.

#### 4.4 Create New Instance (when no existing or user chooses new)

> Must present configuration and get user confirmation before execution: > > 💰 Cost note: Creating an instance incurs charges. Release or pause via ADBPG Console when not in use.

| Config | Default | Notes | |--------|---------|-------| | RegionId | cn-hangzhou | User-specified | | ZoneId | cn-hangzhou-j | Auto-query VPC/VSwitch after selection | | EngineVersion | 7.0 | | | DBInstanceMode | StorageElastic | Storage elastic mode | | DBInstanceCategory | Basic | Default Basic; optional HighAvailability | | InstanceSpec | 4C16G | Basic: 4C16G/8C32G/16C64G; HA: 4C32G/8C64G/16C128G | | SegNodeNum | 2 | Basic default 2 (multiples of 2); HA default 4 (multiples of 4) | | StorageSize | 50 GB | Range: 50–8000 GB | | SegStorageType | cloud_essd | ESSD cloud disk | | VPC/VSwitch | Auto-discover | Select VSwitch with most available IPs | | VectorConfigurationStatus | enabled | Must be enabled for AI coaching | | PayType | Postpaid | Pay-as-you-go; optional Prepaid |

Query VSwitch list for the zone:

aliyun vpc describe-vswitches --profile adbpg \
  --biz-region-id  --zone-id  \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-analyticdb-postgresql-ai-coaching-best-practice

Present VSwitch options to user, recommend the one with most available IPs.

After user confirms:

aliyun gpdb create-db-instance --profile adbpg \
  --biz-region-id  --zone-id  \
  --engine gpdb --engine-version "7.0" \
  --db-instance-mode StorageElastic --db-instance-category Basic \
  --instance-spec 4C16G --seg-node-num 2 \
  --storage-size 50 --seg-storage-type cloud_essd \
  --vpc-id  --vswitch-id  \
  --vector-configuration-status enabled --pay-type Postpaid \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-analyticdb-postgresql-ai-coaching-best-practice

> Timeout: Instance creation takes 10–15 minutes (max 30 min). Poll every 30–60 seconds: >

> aliyun gpdb describe-db-instance-attribute --profile adbpg \
>   --db-instance-id  --region  \
>   --user-agent AlibabaCloud-Agent-Skills/alibabacloud-analyticdb-postgresql-ai-coaching-best-practice
> 

Step 5: Configure Database Account

Check if the ADBPG instance already has a database account:

aliyun gpdb describe-accounts --profile adbpg \
  --db-instance-id  \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-analyticdb-postgresql-ai-coaching-best-practice

Case A: No existing account → Create a new account:

> Suggest account creation, confirm with user before executing: > - Account name: auto-generate ai_coaching_XX (XX = random 2-digit number), or user-specified > - Password: auto-generate a compliant password (8-32 chars, at least 3 character types, avoid !), or user-specified > - Example: Account: ai_coaching_01, Password: Coach3Acc#2x9K — Please confirm or provide your own. > > ⚠️ Important: > - Account name cannot be changed after creation — confirm carefully! > - Password can be reset via console, but save it securely now. > - This account will be used as ManagerAccount in Step 6.

aliyun gpdb create-account --profile adbpg \
  --db-instance-id  --region  \
  --account-name  --account-password '' \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-analyticdb-postgresql-ai-coaching-best-practice

Case B: Account already exists → Inform the user. If the account was not created by the agent, ask the user for the existing account password before proceeding to Step 6.

> Record: ManagerAccount and ManagerAccountPassword — these will be used in Step 6 for knowledge base initialization.

Step 6: Create Knowledge Base

> Parameters to confirm for this step: Auto-generate the following, present to user for confirmation (user may modify), then execute. > > | Parameter | Default | Notes | > |-----------|---------|-------| > | Namespace | ns_coaching | Namespace name, cannot be changed after creation | > | NamespacePassword | Auto-generate | Namespace password (same password rules); needed for uploads and coaching sessions | > | Collection | coaching_knowledge | Knowledge base name | > | EmbeddingModel | text-embedding-v4 | Embedding model |

Using the ManagerAccount and ManagerAccountPassword from Step 5, after user confirms the above parameters, execute:

# Initialize vector database
aliyun gpdb init-vector-database --profile adbpg \
  --biz-region-id  --db-instance-id  \
  --manager-account  --manager-account-password '' \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-analyticdb-postgresql-ai-coaching-best-practice
Create namespace
aliyun gpdb create-namespace --profile adbpg \
  --biz-region-id  --db-instance-id  \
  --manager-account  --manager-account-password '' \
  --namespace  --namespace-password '' \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-analyticdb-postgresql-ai-coaching-best-practice
Create document collection
aliyun gpdb create-document-collection --profile adbpg \
  --biz-region-id  --db-instance-id  \
  --manager-account  --manager-account-password '' \
  --namespace  --collection  \
  --embedding-model  --dimension 1024 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-analyticdb-postgresql-ai-coaching-best-practice

Step 7 (Optional): Upload Domain Knowledge Documents

> If the user has domain knowledge documents (PDF/TXT/Markdown, etc.), upload them to the knowledge base to enhance coaching quality. This step can be skipped — proceed directly to Step 8 to start coaching.

aliyun gpdb upload-document-async --profile adbpg \
  --biz-region-id  --db-instance-id  \
  --namespace  --namespace-password '' \
  --collection  --file-name "domain_knowledge.pdf" \
  --file-url "https://example.com/knowledge.pdf" \
  --document-loader-name ADBPGLoader --chunk-size 500 --chunk-overlap 50 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-analyticdb-postgresql-ai-coaching-best-practice

Recommended documents by scenario: Sales methodologies, process guides (Workflow); Architecture patterns, design docs (Decision Support); Communication frameworks, best practices (Skill Development); Tech stack docs, onboarding guides (Onboarding).

Step 8: Start Coaching Session

> Optional parameters for this step: > > | Parameter | Default | Notes | > |-----------|---------|-------| > | Model | qwen-max | LLM model; use qwen-turbo for daily practice (lower cost) | > | TopK | 5 | RAG retrieval count |

> Note: SourceCollection element MUST include Namespace field.

aliyun gpdb chat-with-knowledge-base --profile adbpg \
  --biz-region-id  --db-instance-id  \
  --model-params '{"Model": "", "Messages": [
    {"Role": "system", "Content": ""},
    {"Role": "user", "Content": ""}
  ]}' \
  --knowledge-params '{"SourceCollection": [{
    "Collection": "", "Namespace": "",
    "NamespacePassword": "", "QueryParams": {"TopK": }
  }]}' \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-analyticdb-postgresql-ai-coaching-best-practice

Scenario Quick Reference

| Scenario | Flow | |----------|------| | Workflow Coaching | Query sales_workflow_coach → Inject coaching persona + process KB → Guide learner through sales stages → Record session | | Decision Support | Query architecture_advisor → Inject coaching persona + tech KB → Guide trade-off analysis → Document decision | | Skill Development | Query communication_coach → Inject coaching persona + best practices KB → Practice scenarios → Provide feedback | | Onboarding | Query onboarding_mentor → Inject coaching persona + tech docs KB → Progressive learning → Verify understanding |

Success Verification

See references/verification-method.md for detailed verification steps.

Quick verification: 1. Supabase project exists and is Running 2. ADBPG instance has VectorConfigurationStatus=enabled 3. Database tables exist (coaching_domains, coaching_personas, learners, coaching_sessions) 4. Preset coaching domains are queryable 5. ChatWithKnowledgeBase returns meaningful coaching responses

Best Practices

1. Supabase for data, KB for AI — Session records through Supabase, coaching dialogue through RAG 2. Coaching persona is key — Quality of system_prompt determines coaching effectiveness 3. Always store session records — Write every coaching round for review and improvement 4. All operations use --profile adbpg — Consistent credential management 5. Team isolation with namespaces — Different teams use different Namespace 6. TopK recommendation: 5 — Reduces token consumption 7. Daily practice: qwen-turbo (low cost), assessments: qwen-max (high quality) 8. Idempotent write operations — Before any resource creation (CreateSupabaseProject, CreateDBInstance, CreateAccount, CreateNamespace, etc.), always query first (Describe/List) to check if the resource already exists. Only create when the resource does not exist. This prevents duplicate resources on retry

References

| Document | Description | |----------|-------------| | references/cli-installation-guide.md | Aliyun CLI installation | | references/related-apis.md | All CLI commands and APIs used | | references/ram-policies.md | Required RAM permissions | | references/database-schema.md | SQL schema and preset coaching domains | | references/acceptance-criteria.md | Correct/incorrect patterns | | references/verification-method.md | Success verification steps |

1. Supabase for data, KB for AI — Session records through Supabase, coaching dialogue through RAG 2. Coaching persona is key — Quality of system_prompt determines coaching effectiveness 3. Always store session records — Write every coaching round for review and improvement 4. All operations use --profile adbpg — Consistent credential management 5. Team isolation with namespaces — Different teams use different Namespace 6. TopK recommendation: 5 — Reduces token consumption 7. Daily practice: qwen-turbo (low cost), assessments: qwen-max (high quality) 8. Idempotent write operations — Before any resource creation (CreateSupabaseProject, CreateDBInstance, CreateAccount, CreateNamespace, etc.), always query first (Describe/List) to check if the resource already exists. Only create when the resource does not exist. This prevents duplicate resources on retry