Database

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

Prerequiste

You must provision required DB in My Vault before making any requests.

Core Database Architecture

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

Key Data Types

Type	Description
`DBContext`	Contains , `tenant_id` and `database` accessing.
`QueryIntent`	A generic JSON structure containing the `collection/table`, `action` (find, insert, etc.), `filter`, and `payload`.

DBContext


export interface DBContext {
  tenant_id: string;
  provider: string; // The specific database engine accessing
}

DBContext must be sent as _meta - As mentioned in request payload for every method below

As it stands today, we support Postgres. Make sure you pass postgres for Postgres as the value(s) in provider under DBContext

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 DB providers.

`execute_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.

Example


{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "tools/call",
  "params": {
      "name": "execute_raw_query",
      "arguments": {
          "query": "CREATE TABLE IF NOT EXISTS inventory (id SERIAL PRIMARY KEY, sku VARCHAR(50) UNIQUE NOT NULL, name TEXT NOT NULL, quantity INTEGER DEFAULT 0, category VARCHAR(100), price DECIMAL(12,2), is_active BOOLEAN DEFAULT true, created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP);"
      },
      "_meta": {
          "tenant_id": "theCipherBlock",
          "provider": "postgres"
      }
  }
}

`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.

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

Example


{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "tools/call",
  "params": {
      "name": "execute_intent",
      "arguments": {
          "intent": {
              "collection": "inventory",
              "action": "insert",
              "payload": {
                  "sku": "PROD-111-SMP",
                  "name": "Wires",
                  "quantity": 1250,
                  "category": "electronics",
                  "price": 1.99,
                  "is_active": true
              }
          }
      },
      "_meta": {
          "tenant_id": "theCipherBlock",
          "provider": "postgres"
      }
  }
}

Example with options


{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "tools/call",
  "params": {
      "name": "execute_intent",
      "arguments": {
          "intent": {
              "collection": "vishakapatnam",
              "action": "find",
              "filter": {
                  "sku": "PROD-111-SMP",
                  "is_active": true
              },
              "options": {
                  "projection": [
                      "name",
                      "quantity",
                      "price"
                  ],
                  "sort": {
                      "price": -1
                  },
                  "limit": 1
              }
          }
      },
      "_meta": {
          "tenant_id": "theCipherBlock",
          "provider": "postgres"
      }
  }
}

`list_schemas`

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

Crucial for agents to understand data boundaries before executing queries.