# database.do

*/Software/database.do*

## Solution Overview

database.do is a headless API primitive that translates natural language intents into validated PostgreSQL and Snowflake operations. It exposes a single REST endpoint where external AI agents submit data requests in plain text. The system maps these requests against the live database schema, generates the required SQL, executes the query, and returns the result as structured JSON arrays.

AI infrastructure engineers and agent builders integrate database.do to give their autonomous systems direct access to enterprise data. Instead of forcing an LLM to memorize complex schemas or risking hallucinated SQL syntax that breaks production tables, developers route data requests through this abstraction layer. The primitive handles dialect-specific syntax formatting, ensuring agents read and write state without carrying native SQL drivers.

Sitting at the foundational layer of the AI stack, database.do consumes raw database connections via standard connection strings and is consumed by higher-level reasoning agents. To protect data integrity, the system enforces a strict human-in-the-loop checkpoint for destructive operations. While SELECT and INSERT commands execute autonomously, requests involving DROP, TRUNCATE, or bulk DELETE trigger a webhook requiring manual authorization from a database administrator.

## Headless Saas Data Model

**Entities**:
- Name: DataRequest · Description: Natural language intent submitted by an AI agent for database execution
- Name: DataSource · Description: Target database connection configuration storing credentials and dialect
- Name: TranslatedQuery · Description: The generated SQL statement translated from the natural language intent
- Name: ApprovalCheckpoint · Description: Human-in-the-loop authorization request for destructive database operations
- Name: ExecutionResult · Description: The payload and metadata returned from the target database after execution
- Name: Workspace · Description: Tenant anchor managing agent resources and database connections
**Relations**:
- To: DataRequest · From: Workspace · Label: owns data requests · Cardinality: one-to-many
- To: DataSource · From: Workspace · Label: owns data sources · Cardinality: one-to-many
- To: DataRequest · From: DataSource · Label: processes requests · Cardinality: one-to-many
- To: TranslatedQuery · From: DataRequest · Label: translates into · Cardinality: one-to-one
- To: ApprovalCheckpoint · From: TranslatedQuery · Label: requires approval checkpoint · Cardinality: one-to-one
- To: ExecutionResult · From: TranslatedQuery · Label: yields execution result · Cardinality: one-to-one
**Tenant Anchor**: Workspace
**Primary Resource**: DataRequest

## Api Definition

**Protocols**:
- REST
- MCP
- Webhooks
- SDK
**Consumed By**:
- [Data Analytics Agent](/Agents/Data_Analytics_Agent)
- [Business Intelligence Agent](/Agents/Business_Intelligence_Agent)
- [ETL Automation Agent](/Agents/ETL_Automation_Agent)
**Integrations**:
- [PostgreSQL](/Products/PostgreSQL)
- [Snowflake](/Products/Snowflake)
**Consumption Model**: An agent registers the MCP server to pass natural language intents via REST, receiving synchronous JSON payloads for safe reads or webhook callbacks for destructive operation approvals.
**Workflow Wrappers**:
- Name: Execute Data Intent · Wraps: translates plain text to SQL, evaluates risk, and executes or pauses for manual approval
- Name: Resolve Approval Checkpoint · Wraps: processes administrator webhook authorization, executes the pending destructive query, and returns the result

## Api Function Cascade

**Ai Role**: As a stateless software primitive, generative AI translates natural language intents into database queries end-to-end, executing safe reads autonomously while deterministic code pauses destructive operations for human webhook approval.
**Cascade**:
- Kind: Code · Step: Ingest Natural Language Intent · Verb: ingest · Realizes: Receive Data Request · Oversight: none
- Kind: Generative · Note: Converts plain text request into a syntactically valid database query. · Step: Translate Intent To SQL · Verb: translate · Realizes: Translate Natural Language · Oversight: none
- Kind: Code · Note: Parses the query AST to separate safe reads from destructive operations. · Step: Evaluate Execution Risk · Verb: evaluate · Realizes: Evaluate Risk Level · Oversight: none
- Kind: Code · Note: Emits a webhook to pause non-read queries pending administrator authorization. · Step: Gate Destructive Queries · Verb: route · Realizes: Route For Approval · Oversight: review-on-exception
- Kind: Code · Note: Runs the approved query against PostgreSQL or Snowflake. · Step: Execute Authorized Query · Verb: execute · Realizes: Execute Database Operation · Oversight: none
- Kind: Code · Step: Emit Result Payload · Verb: emit · Realizes: Transmit Data Payload · Oversight: none
**Optimizes**:
- [Query Generation Accuracy](/Metrics/Query_Generation_Accuracy)
- [Query Execution Latency](/Metrics/Query_Execution_Latency)
- [Destructive Incident Rate](/Metrics/Destructive_Incident_Rate)

## Headless Saas Representative Offer

**Warranty**: The service guarantees 99.9% uptime for the REST and MCP endpoints and valid SQL generation for PostgreSQL and Snowflake, providing automated usage credits if error rates exceed defined thresholds.
**Price Band**: ~$0.005 to $0.05 per processed intent, depending on query complexity and payload size.
**Pricing Kind**: UsageMeter
**Deliverables**:
- REST endpoint access for plain text query intents
- Synchronous JSON payloads containing read-only query results
- Webhook configurations for destructive operation approvals
- MCP server registration manifests
**Delivery Mode**: Buyers provision access instantly through a self-serve portal, receiving API credentials that allow autonomous agents to immediately submit intents and consume execution endpoints.
**Business Function**: ProvideService
**Agent Checkout Support**:
- agentic-commerce-protocol
- stored-credential

## Headless Saas Crud Surface

**Auth Model**: API Key
**Endpoints**:
- GET /data-requests — list data requests
- POST /data-requests — submit a natural language data request
- GET /data-requests/{id} — fetch a data request
- PATCH /data-requests/{id} — update a data request
- GET /data-requests/{id}/translated-query — fetch the translated query for this request
- GET /data-sources — list data sources
- POST /data-sources — create a data source
- GET /data-sources/{id} — fetch a data source
- PATCH /data-sources/{id} — update a data source
- GET /data-sources/{id}/data-requests — list data requests processed by this data source
- GET /translated-queries — list translated queries
- POST /translated-queries — create a translated query
- GET /translated-queries/{id} — fetch a translated query
- PATCH /translated-queries/{id} — update a translated query
- GET /translated-queries/{id}/approval-checkpoint — fetch the approval checkpoint for this query
- GET /translated-queries/{id}/execution-result — fetch the execution result for this query
- GET /approval-checkpoints — list approval checkpoints
- POST /approval-checkpoints — create an approval checkpoint
- GET /approval-checkpoints/{id} — fetch an approval checkpoint
- PATCH /approval-checkpoints/{id} — update an approval checkpoint
- POST /approval-checkpoints/{id}/approve — approve the destructive database operation
- POST /approval-checkpoints/{id}/reject — reject the destructive database operation
- GET /execution-results — list execution results
- POST /execution-results — create an execution result
- GET /execution-results/{id} — fetch an execution result
- PATCH /execution-results/{id} — update an execution result
- GET /workspaces — list workspaces
- POST /workspaces — create a workspace
- GET /workspaces/{id} — fetch a workspace
- PATCH /workspaces/{id} — update a workspace
- GET /workspaces/{id}/data-requests — list data requests owned by this workspace
- GET /workspaces/{id}/data-sources — list data sources owned by this workspace
**Multitenancy**: Row-level isolation
**Webhook Events**:
- data_request.created
- translated_query.generated
- approval_checkpoint.created
- approval_checkpoint.resolved
- execution_result.returned

## Headless Saas Erd

```mermaid
erDiagram
    Workspace ||--o{ DataRequest : "owns data requests"
    Workspace ||--o{ DataSource : "owns data sources"
    DataSource ||--o{ DataRequest : "processes requests"
    DataRequest ||--|| TranslatedQuery : "translates into"
    TranslatedQuery ||--|| ApprovalCheckpoint : "requires approval checkpoint"
    TranslatedQuery ||--|| ExecutionResult : "yields execution result"

    DataRequest {
        UUID id PK
        UUID workspaceId FK
        UUID dataSourceId FK
        TEXT intentText
        VARCHAR status
        TIMESTAMP createdAt
    }
    DataSource {
        UUID id PK
        UUID workspaceId FK
        VARCHAR connectionString
        VARCHAR dialect
        BOOLEAN isHealthy
    }
    TranslatedQuery {
        UUID id PK
        UUID dataRequestId FK
        TEXT sqlStatement
        VARCHAR operationType
        BOOLEAN isDestructive
    }
    ApprovalCheckpoint {
        UUID id PK
        UUID translatedQueryId FK
        VARCHAR adminWebhookUrl
        VARCHAR status
        TIMESTAMP resolvedAt
    }
    ExecutionResult {
        UUID id PK
        UUID translatedQueryId FK
        JSONB payload
        DECIMAL rowsAffected
        TIMESTAMP executedAt
    }
    Workspace {
        UUID id PK "Tenant Key"
        VARCHAR name
        VARCHAR apiToken
        TIMESTAMP createdAt
    }
```

## Software Primitive Card

**Noun**: Database
**Tier**: free
**Verb**: store
**Genre**: primitive-page
**Domain**: database.do
**Status**: planned
**Tagline**: Data that persists
**Rendered**: Database — Data that persists.
Database abstraction. On the workers.do roadmap.
**Adjective**: persistent
**Mechanism**: primitive-composition-v1
**Noun Plural**: Databases
**Stack Layer**: data
**Verb Gerund**: storing
**Description**: Database abstraction
**Primitive Card**: Database — Data that persists.
Database abstraction. On the workers.do roadmap.
**Deployment Model**: Database ships as an npm package; self-host on any workers.do-compatible runtime. The managed version is on the roadmap.
**Template Results**:
- Rendered: Database — Data that persists.
Database abstraction. On the workers.do roadmap. · Template Id: primitive-card
- Rendered: Database is a data primitive on workers.do.
It builds on Platform and is consumed by Agent and Workflow. · Template Id: platform-position
- Rendered: Database is called via API and MCP, authenticated through Key. The canonical first call is to store database: Database abstraction. · Template Id: consumption-pattern
- Rendered: Database ships as an npm package; self-host on any workers.do-compatible runtime. The managed version is on the roadmap. · Template Id: self-hosted-vs-managed
**Platform Position**: Database is a data primitive on workers.do.
It builds on Platform and is consumed by Agent and Workflow.
**Vocab Fingerprint**: 7ca98dbd9f7a4f1c
**Consumption Pattern**: Database is called via API and MCP, authenticated through Key. The canonical first call is to store database: Database abstraction.

## Neighborhood

### Optimizes

- [Query Generation Accuracy](/Metrics/Query_Generation_Accuracy) — optimizes · Metrics
- [Destructive Incident Rate](/Metrics/Destructive_Incident_Rate) — optimizes · Metrics
- [Query Execution Latency](/Metrics/Query_Execution_Latency) — optimizes · Metrics
- [Unauthorized Execution Rate](/Metrics/Unauthorized_Execution_Rate) — optimizes · Metrics
- [Data Retrieval Cycle Time](/Metrics/Data_Retrieval_Cycle_Time) — optimizes · Metrics
- [Query Translation Accuracy](/Metrics/Query_Translation_Accuracy) — optimizes · Metrics
- [Destructive Mutation Intercept Rate](/Metrics/Destructive_Mutation_Intercept_Rate) — optimizes · Metrics
- [Intent-to-Query Accuracy](/Metrics/Intent-to-Query_Accuracy) — optimizes · Metrics
- [Query Success Rate](/Metrics/Query_Success_Rate) — optimizes · Metrics

### Who consumes this

- [Data Analytics Agent](/Agents/Data_Analytics_Agent) — consumed by · Agents
- [ETL Automation Agent](/Agents/ETL_Automation_Agent) — consumed by · Agents
- [Business Intelligence Agent](/Agents/Business_Intelligence_Agent) — consumed by · Agents
- [BI Reporting Agent](/Agents/BI_Reporting_Agent) — consumed by · Agents
- [Data Engineering Agent](/Agents/Data_Engineering_Agent) — consumed by · Agents
- [Data Analysis Agent](/Agents/Data_Analysis_Agent) — consumed by · Agents

### What it uses

- [PostgreSQL](/Software/PostgreSQL) — uses · Software
- [Snowflake](/Software/Snowflake) — uses · Software

### Similar Agents

- [Pipeline Gateway API](/Agents/Pipeline_Gateway_API) — similar · Agents
- [Declarative Provisioning API](/Agents/Declarative_Provisioning_API) — similar · Agents
- [Query Execution Engine](/Agents/Query_Execution_Engine) — similar · Agents
- [Infrastructure State SDK](/Agents/Infrastructure_State_SDK) — similar · Agents

### Similar Software

- [Text-to-SQL Engine](/Software/Text-to-SQL_Engine) — similar · Software
- [Data Governance Engine](/Software/Data_Governance_Engine) — similar · Software
- [Identity Provider Integration](/Resources/Secure_document_storage/Software/Identity_Provider_Integration) — similar · Software
- [Document Databases](/Resources/Secure_document_storage/Software/Document_Databases) — similar · Software
- [Pipeline Control API](/Software/Pipeline_Control_API) — similar · Software
- [GitHub](/Competitors/Datafold/Software/GitHub) — similar · Software
- [Sandbox Sequencing API](/Software/Sandbox_Sequencing_API) — similar · Software
- [Performance Monitoring Software](/Metrics/Reliability_Analysis_Cycle_Time/Software/Performance_Monitoring_Software) — similar · Software
- [Instrument Control APIs](/Partners/Lab_equipment_vendors/Software/Instrument_Control_APIs) — similar · Software
- [Data Reliability Engine](/Software/Data_Reliability_Engine) — similar · Software
- [Open Banking APIs](/Resources/Client_financial_data/Software/Open_Banking_APIs) — similar · Software

### Similar Resources

- [Encrypted database infrastructure](/Resources/Encrypted_database_infrastructure) — similar · Resources
- [Secure financial databases](/Resources/Secure_financial_databases) — similar · Resources

### Similar Competitors

- [dbt](/Competitors/dbt) — similar · Competitors