Database

The Z-Database service is a protocol-agnostic bridge designed to unify interactions across diverse database engines (e.g., PostgreSQL, MongoDB, DynamoDB). It functions as a stateless proxy, translating high-level “Intents” from AI agents into native query languages (SQL or NoSQL) without maintaining permanent state or persistent connections.

Core Database Architecture

To remain stateless while ensuring security, every request must include a DBContext. This context allows the service to retrieve the necessary credentials from the ZenZ Vault in real-time.

Key Data Types

DBContext

export interface DBContext {
  networkID: string;  // The target network (e.g., "pg-mainnet", "mongo-cluster-01")
  databaseName: string; // The specific logical database name
}
 
export enum DatabaseType {
  SQL = "sql",       // Relational (Postgres, MySQL, SQLite)
  NOSQL = "nosql"    // Document/Key-Value (MongoDB, DynamoDB, Redis)
}

QueryIntent

export interface QueryIntent {
  collection: string; // Table name for SQL, Collection for NoSQL
  action: 'find' | 'insert' | 'update' | 'delete' | 'aggregate';
  filter?: Record<string, any>; // WHERE clause for SQL, Filter for NoSQL
  payload?: Record<string, any>; // Data for insert/update
  options?: {
    limit?: number;
    sort?: Record<string, number>;
    projection?: string[]; // Specific fields to return
  };
}

Service Tools

These tools are exposed to AI agents to perform data operations safely and efficiently across different backend providers.

execute_intent

Description: The primary tool for generic data operations. It translates the abstract QueryIntent into native database commands.

• Input Schema:

  • intent (object): The structured query intent.
  • context (object): The target DBContext.

• Logic: For SQL backends, it generates sanitized, parameterized queries. For NoSQL, it invokes native driver methods (e.g., collection.find()).

list_schemas

Description: Automatically discovers and returns the structure of the target database (tables for SQL, collections for NoSQL).

• Input Schema:

  • context (object): The target DBContext.

• Use Case: Crucial for agents to understand data boundaries before executing queries.

run_raw_query

Description: Executes native query strings or pipelines directly on the backend.

Warning: This should be restricted to high-privilege sessions as it bypasses generic safety abstractions.

• Input Schema:
  • query (string | object): The raw SQL string or NoSQL aggregation pipeline.
  • context (object): The target DBContext.