NineData Skill

NineData-Skill gives AI Agents and vibe-coding tools governed access to NineData platform capabilities. It uses NineData authentication, permission checks, SQL rule checks, data masking, throttling, approval, and audit logging. Typical scenarios include listing data sources, executing read-only SQL, submitting SQL tasks, and exporting query results.

What NineData Skill Can Do

• SQL execution: Execute explicit SQL in a permitted data source context, or retrieve execution plans and related information.
• SQL task: Submit SQL to a secure approval workflow for scenarios that require rule checks, approval, and audit.
• Data export: Export read-only query results to CSV, Excel, SQL, JSON, XML, or text files and track approval, execution, logs, and file status.
• Platform capability calls: Let AI Agents call NineData platform capabilities through OpenAPI, such as listing data sources, checking database status, or validating development data.
• Security controls: Skill calls are governed by NineData account identity, organization permissions, SQL rules, data masking, throttling, and audit logs.

Skill tools

Tool	Purpose
list-datasource	List data sources visible to the current OpenAPI credential.
sql-execute	Execute read-only DQL or metadata checks and return the platform decision and result preview.
sql-task	Submit and operate SQL tasks that require rule checks, approval, or execution control.
data-export	Submit and operate Data Export workflows for read-only query results.

Use cases

Use case	Description
Discover accessible data sources	List the data sources visible to the current OpenAPI credential before selecting a target environment.
Run read-only queries	Execute explicit query SQL within the authorized scope and return a result preview.
Analyze execution plans	Retrieve execution plans or diagnostic information for read-only SQL.
Submit SQL tasks	Route SQL that changes data, schema, permissions, or transaction state through a governed workflow.
Export query results	Create a Data Export workflow for read-only query results and follow platform approval, execution, and file permissions.
Assist development workflows	Validate development data within NineData identity and permission boundaries.

Security considerations

• Confirm the target data source, complete SQL, operation reason, and account permissions before an Agent calls Skill.
• Use SQL execution only for read-only DQL and metadata checks.
• Use SQL task for SQL that can change data, schema, permissions, transaction state, or stored procedure state.
• Use Data export when a read-only query must produce a file. File download and encryption-password retrieval require separate authorization.
• Do not store database usernames or passwords in Skill or let the Agent connect directly to a database.
• Do not expose accessKeySecret, cookies, tokens, signatures, or database credentials in chats, logs, screenshots, or commits.
• Do not bypass a platform rejection, confirmation requirement, SQL task requirement, or approval requirement.
• Approval actions such as approve, reject, and transfer-approval require explicit authorization for the exact action.

caution

Keep config.json only in the local Agent runtime and restrict its file permissions. Treat exported files and encryption passwords as sensitive data. Do not place them in documentation, screenshots, chats, or repositories.

Before you begin

• You are logged in to the NineData console.
• Your account has permission to access the Skill page.
• OpenAPI AccessKey is enabled for the calling account in NineData user management, and you have saved the AccessKey and SecretKey.
• To execute SQL or submit SQL tasks through Skill, your account must have the required permissions on the target data source and DevOps workflow.

View Skill Capabilities

1. Sign in to the NineData Console.

2. From the left sidebar, open Skill.

3. On the NineData-Skill page, view the supported Skill capabilities.

   The page shows what NineData-Skill is used for and lists the feature name, description, and release time of each capability.

Page Actions

On the NineData-Skill page toolbar, use these actions:

Action	Description
Description	View the NineData-Skill version, tool IDs, invocation method, OpenAPI endpoints, return fields, and usage boundaries.
Download	Download ninedata-skill.zip, which includes the Skill guide, sample configuration, client installation references, and scripts.
Quick setup guide	View installation paths and validation prompts for Claude Code, Codex, Cursor, Hermes, OpenClaw, Trae, Qoder, Open Code, and other clients.

Download and Configure Skill

1. On the NineData-Skill page toolbar, click the download icon to download ninedata-skill.zip.

2. Extract the package to get the ninedata-skill directory.

3. Copy the complete ninedata-skill directory to the Skill directory of the target AI Agent client.

   Client	Installation path example
   Claude Code	~/.claude/skills/ninedata-skill/
   Codex	~/.codex/skills/ninedata-skill/
   Cursor	~/.cursor/skills/ninedata-skill/
   Hermes Agent	~/.hermes/skills/ninedata-skill/
   OpenClaw	~/.openclaw/skills/ninedata-skill/
   Trae	~/.trae/skills/ninedata-skill/
   Qoder	~/.qoder/skills/ninedata-skill/
   Open Code	~/.opencode/skills/ninedata-skill/

4. Copy config.example.json to config.json, then edit the file in the Skill root directory.

   {
     "endpoint": "https://your-ninedata-domain.example.com",
     "accessKeyId": "replace-with-access-key-id",
     "accessKeySecret": "replace-with-access-key-secret",
     "defaultDsId": "replace-with-default-datasource-id",
     "defaultDbName": "replace-with-default-database-name",
     "defaultSchemaName": "replace-with-default-schema-name",
     "source": "NINEDATA_SKILL",
     "defaultPageSize": 50,
     "defaultLanguage": "enus"
   }

   Configuration item	Description
   endpoint	NineData console root endpoint. For SaaS, use https://console.ninedata.cloud. For private deployment or Dedicated Cluster, use the actual console endpoint.
   accessKeyId, accessKeySecret	NineData OpenAPI credentials obtained after AccessKey is enabled in user management. Keep them in a restricted local configuration.
   defaultDsId	Default data source ID. It is optional for listing data sources. SQL execution uses it when no data source is specified in command arguments.
   defaultDbName	Default database name.
   defaultSchemaName	Default schema name. Set it when the database type requires a schema.
   source	Invocation source. Keep NINEDATA_SKILL unless you have a specific reason to change it.
   defaultPageSize	Default page size.
   defaultLanguage	Response language, such as enus.

5. Set permissions for the configuration file. On Linux or macOS, run the following command. On Windows, use the file security settings to restrict access to the current user.

   chmod 600 config.json

6. Confirm that the client can execute scripts/*.sh in the Skill directory, then restart the client or start a new Agent session.

7. Ask the Agent to use NineData Skill.

   Use ninedata-skill to list available MySQL data sources.

Validate Configuration

After configuration, run the validation script and list a small number of accessible data sources.

scripts/validate-config.sh
scripts/list-datasource.sh --page-size 5

If no default data source is configured, select a datasourceId from the result. To temporarily select another configuration file, use --config or NINEDATA_SKILL_CONFIG. Validation returns data sources visible to the current OpenAPI credential or a platform error. It does not connect directly to a database.

Query Data with Skill

After Skill is configured, describe your query requirement in natural language in the AI Agent client. For example:

Use ninedata-skill to query the order count in the production MySQL data source.

The Agent should identify accessible data sources and present the full SQL that will be executed. Confirm the SQL, target data source, and query purpose before letting the Agent continue. sql-execute is limited to read-only DQL and metadata checks. SQL that can change data, schema, permissions, or transaction state must use SQL Task.

NineData returns the execution result or the next recommended action based on platform rules. Common outcomes include:

• The query is executed and a result preview is returned.
• Full SQL confirmation is required again.
• The SQL is rejected by permission, rule, or safety policy.
• The SQL must be handled through a SQL task or approval workflow.
• Database execution fails, and an error message and request ID are returned.

Common decisions are EXECUTED, REJECTED, NEED_CONFIRMATION, NEED_SQL_TASK, and FAILED. A result preview may be limited by pagination or platform protection. Check the returned truncation state before treating the preview as complete.

Submit SQL Changes with Skill

For SQL that changes data, schema, permissions, or transaction state, route the statement through a NineData SQL task. This includes INSERT, UPDATE, DELETE, CREATE, ALTER, DROP, GRANT, REVOKE, transaction control, potentially state-changing procedure calls, and mixed batches that contain any non-read-only statement.

The typical workflow is:

1. Describe the change requirement in the AI Agent client.

   Use ninedata-skill to submit a SQL task for adding a remark column to the orders table in the test database.

2. The Agent displays the target data source, database, full SQL, and optional rollback SQL.

3. After confirming the content, explicitly agree to submit the SQL task.

4. NineData creates the SQL task and returns the task ID, rule check result, approval status, and console task link.

5. Continue to submit for approval, wait for approval, or execute the task based on the task status. For multi-step approval, process the current approval nodes until detail returns canExecute=true.

For approval, execution, pause, resume, stop, cancel, reject, or approval transfer operations, the Agent should present the current task status and operation impact, and continue only after your explicit confirmation.

Export Query Results with Skill

Data Export generates a file from read-only query results. Supported file types include csv, excel, sql, json, xml, and txt. The workflow remains subject to rule checks, approval, execution permissions, and audit logging.

1. Confirm the data source, database, schema, and complete read-only SQL.
2. Submit the Data Export workflow and specify file type, charset, and export content when required.
3. Query task detail and inspect rule checks, approval status, execution status, and fileAvailable.
4. When approval is required, process the current approval node returned by the platform. Handle multi-step approval one node at a time.
5. Execute the export only when canExecute=true and the user explicitly authorizes execution.
6. Use the workflow log or process log to diagnose execution state.
7. Request a download link only when detail returns fileAvailable=true and the user explicitly asks for it. Encryption-password retrieval requires separate authorization.

Submit, update, approval, execution, suspend, resume, stop, cancel, skip, download, and password retrieval are separate operations. Skill does not automatically approve a workflow, download a file, reveal an encryption password, or skip an export task.

Recommendations

• Before letting an AI Agent call Skill, confirm that the target data source, SQL content, and account permissions are correct.
• For SQL that changes data or schema, use the SQL task capability to submit the SQL to an approval workflow.
• For exports, confirm the SQL and file scope first, then follow Data Export approval, execution, and download permissions.
• For read-only queries, execution plan retrieval, or development data validation, use the SQL execution capability within your organization permissions and security rules.
• Skill results can help an AI Agent make decisions, but production changes should still be reviewed together with approval, audit, and business impact.
• Do not let the Agent connect directly to databases, and do not store database usernames or passwords in the Skill.
• Do not expose accessKeySecret, cookies, tokens, signatures, or database credentials in chats, logs, or commits.
• When the platform returns rejection, failure, confirmation required, SQL task required, or approval required, do not bypass the platform decision.
• Approval actions such as approve, reject, and transfer-approval are high-risk operations. Run them only after the user explicitly confirms the exact action.

Related documentation

• SQL Task
• Data Export
• OpenAPI
• ChatDBA