Databases

This page describes database connections in Raikoo and how they enable AI agents and workflows to interact with external databases for querying data, executing modifications, and introspecting schema information.

What are Database Connections?

Database connections in Raikoo represent secure links to external database systems that AI agents can use to read and write data. They provide a controlled way for agents to interact with your organization's databases while maintaining security through credential isolation and permission controls.

Think of a database connection as a secure bridge between your AI workflows and your data—complete with authentication, authorization controls, and safety guardrails to prevent unintended operations.

Why Databases Matter

Connecting AI agents to databases unlocks powerful capabilities:

Data-Driven Responses - Agents can query real-time data to provide accurate, up-to-date answers
Automated Data Entry - Workflows can insert or update records based on processed information
Dynamic Analysis - Agents can explore database schemas and run analytical queries on demand
Integration with Business Systems - Connect to existing databases powering your applications

Key Concepts

Supported Database Types

Raikoo supports two categories of databases with specialized tools for each:

SQL (Relational) Databases:

PostgreSQL - Full support including queries, modifications, and schema introspection
MySQL / MariaDB - Full support with mysql2 driver
SQL Server - Full support including Azure SQL Database

Document Databases:

MongoDB - Full support for find, aggregate, and modify operations

Workspace Databases:

SQLite - File-based databases stored within workspaces (up to 100MB)

Connection Security

Database credentials are never stored in the Raikoo database. Instead, all connection details (host, port, username, password, SSL settings) are securely stored in Azure Key Vault:

Credential Isolation - Connection credentials are encrypted and stored separately from metadata
Access Control - Only authorized operations can retrieve credentials at runtime
Audit Trail - All credential access is logged for compliance purposes

This architecture ensures that even if the application database were compromised, your database credentials would remain protected.

Two-Level Permission Model

Raikoo implements a defense-in-depth approach with two levels of write permission control:

Connection Level (Administrator Controlled)

Each database connection has a Read Only setting that acts as a hard ceiling:

When enabled (default), no tool can perform write operations regardless of its configuration
Only organization administrators can change this setting
Provides a safety net for compliance-sensitive environments

Tool Level (Agent Configuration)

For connections that allow writes, individual tool instances can still be restricted:

The sql_execute tool has an Allow Write configuration option
Even on a writable connection, the tool defaults to read-only
Enables fine-grained control per agent or workflow

This two-level model ensures that write access requires explicit enablement at both the infrastructure and application levels.

Query Validation

All queries are validated before execution to prevent dangerous operations:

For SQL SELECT Queries (sql_query tool)

Must be a valid SELECT statement
Blocked keywords: INSERT, UPDATE, DELETE, DROP, TRUNCATE, ALTER, CREATE
Row limits are automatically enforced to prevent runaway queries

For SQL Modification Statements (sql_execute tool)

DDL operations are blocked: DROP, TRUNCATE, ALTER, CREATE
UPDATE and DELETE statements require a WHERE clause
Both permission levels must allow writes

For MongoDB Operations

$where operator is blocked (prevents arbitrary JavaScript execution)
$merge and $out aggregation stages are blocked (prevents writing to other collections)
All operations require a valid JSON filter/pipeline

Row Limits and Timeouts

Each database connection can configure safety limits:

Max Row Limit - Maximum rows returned per query (default: 1000)
Query Timeout - Maximum execution time in milliseconds (default: 30000)

These limits protect against queries that could return excessive data or run indefinitely.

Available Database Tools

Raikoo provides specialized tools for each database category.

SQL Database Tools

These tools work with PostgreSQL, MySQL/MariaDB, and SQL Server.

sql_query

Execute read-only SELECT queries against a SQL database.

Capabilities:

Run any SELECT query within the configured limits
Multiple output formats: JSON, CSV, or Markdown tables
Automatic row limit enforcement
Query timeout protection

Configuration:

Database Connection (required) - Which database to query

Parameters:

query - The SQL SELECT statement to execute
description - Why this query is being executed (for audit purposes)
outputFormat - Result format: json, csv, or markdown

sql_execute

Execute data modification statements (INSERT, UPDATE, DELETE).

Capabilities:

Insert new records
Update existing records (WHERE clause required)
Delete records (WHERE clause required)
Returns affected row count

Configuration:

Database Connection (required) - Which database to modify
Allow Write (required) - Must be explicitly enabled

Parameters:

statement - The SQL modification statement
description - What this change does (required for audit)

!!! warning "Two-Level Permission Required" Both the database connection's Read Only setting must be disabled AND the tool's Allow Write must be enabled for modifications to succeed.

sql_schema

Introspect database structure on demand.

Capabilities:

List all tables in the database
Get detailed schema for specific tables
Include index and constraint information
Show approximate row counts

Configuration:

Database Connection (required) - Which database to introspect

Parameters:

tableName (optional) - Specific table to describe, or omit for all tables
includeIndexes - Whether to include index information
includeConstraints - Whether to include constraint details

!!! tip "On-Demand Schema Loading" Schema information is fetched when the agent needs it, rather than being pre-loaded into the system prompt. This keeps context focused and avoids bloating prompts for databases with many tables.

MongoDB Tools

These tools are designed specifically for document databases.

mongodb_find

Query documents from a MongoDB collection using find operations.

Capabilities:

Query documents with filter expressions
Project specific fields
Sort, limit, and skip results
Count matching documents

Configuration:

Database Connection (required) - Which MongoDB database to query

Parameters:

collection - The collection name to query
filter - JSON filter document (e.g., {"status": "active"})
projection - JSON projection document for field selection
sort - JSON sort document (e.g., {"createdAt": -1})
limit - Maximum documents to return
skip - Number of documents to skip
countOnly - Return only the count without fetching documents
description - Why this query is being executed

mongodb_aggregate

Run aggregation pipelines on a MongoDB collection.

Capabilities:

Execute complex aggregation pipelines
Group, filter, project, and transform data
Perform lookups across collections
Calculate statistics and analytics

Configuration:

Database Connection (required) - Which MongoDB database to query

Parameters:

collection - The collection name
pipeline - JSON array of aggregation stages
description - Why this aggregation is being executed

mongodb_modify

Insert, update, or delete documents in a MongoDB collection.

Capabilities:

Insert single or multiple documents
Update documents with query operators ($set, $inc, etc.)
Delete documents matching a filter

Configuration:

Database Connection (required) - Which MongoDB database to modify
Allow Write (required) - Must be explicitly enabled

Parameters:

collection - The collection name
operation - One of: insertOne, insertMany, updateOne, updateMany, deleteOne, deleteMany
filter - JSON filter for update/delete operations
document - JSON document(s) for insert operations
update - JSON update document with operators
description - What this modification does

mongodb_schema

List collections and infer document structure from a MongoDB database.

Capabilities:

List all collections in the database
Sample documents to infer field types
Show index information
Estimate document counts

Configuration:

Database Connection (required) - Which MongoDB database to introspect

Parameters:

collectionName (optional) - Specific collection to describe
includeSampleFields - Sample documents to infer field types
includeIndexes - Include index information

SQLite Tools

These tools work with SQLite database files stored in workspaces.

sqlite_query

Query a SQLite database file in the workspace.

Capabilities:

Execute SELECT queries on workspace-local SQLite files
Great for local data processing and agentic memory
Maximum file size: 100MB

Configuration:

FilePath (required) - Path to SQLite file in workspace

Parameters:

query - SQL SELECT query to execute

sqlite_execute

Execute SQL statements on a SQLite database file.

Capabilities:

INSERT, UPDATE, DELETE operations
DDL statements (CREATE TABLE, etc.)
Changes automatically saved on completion

Configuration:

FilePath (required) - Path to SQLite file in workspace
CreateIfMissing - Create the database file if it doesn't exist

Parameters:

statement - SQL statement to execute

sqlite_schema

Get schema information from a SQLite database file.

Capabilities:

List all tables in the database
Get column definitions and types
Show index information

Configuration:

FilePath (required) - Path to SQLite file in workspace

Parameters:

tableName (optional) - Specific table to describe

Security Model

Defense in Depth

The database integration is designed with multiple security layers:

Credential Storage - All credentials in Key Vault, never in application database
Permission Levels - Two-level read-only controls (connection + tool)
Query Validation - DDL blocked, WHERE clauses required for modifications
Resource Limits - Row limits and timeouts prevent resource exhaustion
Audit Parameters - Description fields for compliance tracking

Permission Scoping

Raikoo trusts the database user credentials provided by your organization. The permissions of that database user become the effective permissions of the AI agent:

If the database user can only SELECT from certain tables, the agent inherits those restrictions
If the database user has full access, Raikoo's permission controls provide the guardrails
No duplication of table/schema permissions inside Raikoo

!!! note "Database User Permissions" The database user's permissions are the agent's permissions. Configure your database user with the minimum privileges needed for the intended use case.

Best Practices

Security

Use dedicated database users - Create specific users for Raikoo with minimal required permissions
Enable read-only by default - Only enable write access when explicitly needed
Prefer SSL connections - Use require or stricter SSL modes in production
Rotate credentials regularly - Update database passwords periodically

Performance

Set appropriate row limits - Balance data needs against response size
Configure reasonable timeouts - Prevent long-running queries from blocking agents
Consider connection pooling - For high-volume usage, point Raikoo at a connection pooler like PgBouncer

Organization

Name connections clearly - Use descriptive names indicating purpose and environment
Document access patterns - Note what data each connection is intended to access
Separate environments - Use different connections for development, staging, and production

Connection Pooling

For high-volume deployments, consider placing a connection pooler between Raikoo and your database:

Recommended: PgBouncer

Transaction pooling mode works well for typical query patterns
Session pooling mode if you need session-level features

Considerations:

Transaction-mode poolers may have quirks with prepared statements
Some session state features may not work across pooled connections
Document any pooler-specific limitations for your team

Future Capabilities

The database integration will continue to evolve:

Query Templates - Pre-defined, parameterized queries for common operations
Query History - Audit log UI for reviewing executed queries
Workflow Operations - Database operations as workflow steps (not just chat tools)
Additional Database Types - Oracle, Snowflake, and other databases

Conclusion

Database connections provide a secure, controlled way for AI agents to interact with your organization's data. The two-level permission model, credential isolation, and query validation ensure that agents can access the data they need while maintaining security guardrails. By properly configuring connections and following best practices, you can safely enable data-driven AI capabilities across your workflows.