Skip to content

Databases

This guide explains how to create and configure database connections in Raikoo. Database connections enable your AI agents to query data, execute modifications, and explore database schemas.

Understanding Databases in Raikoo

Databases in Raikoo are organization-level entities that define secure connections to external database systems. They provide:

  • Centralized Configuration - Define connections once and use them across multiple agents and workflows
  • Secure Credential Storage - Connection credentials are stored in Azure Key Vault, never in the application database
  • Granular Permission Control - Two-level read-only settings for defense in depth
  • Safety Guardrails - Query validation, row limits, and timeouts

Database connections are shared across all projects within an organization, making them ideal for data sources that serve multiple teams and use cases.

Accessing the Databases Page

To access databases in your organization:

  1. Navigate to your organization's dashboard
  2. Click on "Databases" in the left navigation menu under Organization Settings
  3. You'll see a list of all database connections configured for your organization

The Databases page displays:

  • Connection name - A descriptive identifier for each database
  • Database type - The type of database (e.g., PostgreSQL)
  • Read-only status - Whether write operations are allowed
  • Action buttons - Edit, test connection, or delete

!!! note "Permissions Required" You need the appropriate organization permissions to view, create, edit, or delete database connections.

Creating a New Database Connection

To create a new database connection:

  1. From the Databases page, click the "Create" button
  2. You'll be taken to the database editor with three tabs:
    • Details - Basic information
    • Connection - Database credentials and host information
    • Settings - Safety limits and permissions

Configuring Details

In the Details tab:

  1. Name (required)

    • Enter a descriptive name for your database connection
    • Example: Production Analytics DB or Dev PostgreSQL

  2. Description (optional)

    • Provide additional context about this database
    • Describe its purpose, data contents, or usage restrictions
    • Example: "Read-only access to analytics data warehouse"

  3. Database Type (required)

    • Select the type of database
    • Supported SQL databases: PostgreSQL, MySQL/MariaDB, SQL Server
    • Supported document databases: MongoDB

!!! tip "Naming Best Practice" Use clear, descriptive names that indicate the environment and purpose, such as "Prod_CustomerDB" or "Staging_Analytics". This helps team members quickly identify the right database for their needs.

Configuring Connection

In the Connection tab, enter your database credentials:

  1. Host (required)

    • The hostname or IP address of your database server
    • Example: db.example.com or 10.0.1.50

  2. Port (required)

    • The port your database is listening on
    • Default ports by database type:
      • PostgreSQL: 5432
      • MySQL/MariaDB: 3306
      • SQL Server: 1433
      • MongoDB: 27017

  3. Database (required)

    • The name of the database to connect to
    • Example: analytics or myapp_production

  4. Username (required)

    • The database user account
    • Example: raikoo_readonly

  5. Password (required)

    • The password for the database user
    • This is stored securely in Azure Key Vault

  6. SSL Mode (required)

    • How to handle SSL/TLS encryption
    • Options:
      • disable - No SSL (not recommended for production)
      • require - Use SSL but don't verify certificate (default)
      • verify-ca - Verify the server certificate is signed by a trusted CA
      • verify-full - Verify certificate and hostname match

!!! warning "SSL in Production" Always use require or stricter SSL modes for production databases. The disable option should only be used for local development.

Configuring Settings

In the Settings tab, configure safety limits and permissions:

  1. Read Only (default: enabled)

    • When enabled, no write operations are allowed regardless of tool configuration
    • This is an administrator-level control that acts as a hard ceiling
    • Disable only when you explicitly need agents to modify data

  2. Max Row Limit (default: 1000)

    • Maximum number of rows returned per query
    • Prevents queries from returning excessive data
    • Adjust based on your use case needs

  3. Query Timeout (default: 30 seconds)

    • Maximum time a query can run before being cancelled
    • Prevents long-running queries from blocking agents
    • Adjust for complex analytical queries if needed

!!! note "Two-Level Permission Model" The Read Only setting here is the first level of permission control. Even if disabled, individual tools must also have write access enabled. This defense-in-depth approach requires explicit enablement at both levels.

Testing Your Connection

Before using a database connection, verify it works:

  1. After saving your connection, click the "Test Connection" button
  2. Raikoo will attempt to connect to the database using your credentials
  3. You'll see either:
    • Success - Connection details are displayed (host, port, database)
    • Failure - An error message explaining what went wrong

Common test failures:

Error Likely Cause
Connection refused Wrong host/port, firewall blocking, database not running
Authentication failed Wrong username or password
Database does not exist Typo in database name
SSL required Database requires SSL but mode is set to disable

Configuring Database Tools on Agents

Once you have a database connection, you can add database tools to your AI agents. Different tools are available depending on the database type.

SQL Database Tools

For PostgreSQL, MySQL/MariaDB, and SQL Server connections:

Adding the sql_query Tool

The sql_query tool allows agents to run SELECT queries:

  1. Navigate to your agent's configuration
  2. Go to the Tools section
  3. Click "Add Tool" and select "SQL Query"
  4. Configure the tool:
    • Database Connection - Select your SQL database connection from the dropdown
  5. Save the agent configuration

The agent can now execute read-only queries against this database.

Adding the sql_execute Tool

The sql_execute tool allows agents to run INSERT, UPDATE, and DELETE statements:

  1. Navigate to your agent's configuration
  2. Go to the Tools section
  3. Click "Add Tool" and select "SQL Execute"
  4. Configure the tool:
    • Database Connection - Select your SQL database connection
    • Allow Write - Enable this to allow modifications

!!! warning "Write Access Requirements" For write operations to succeed:

1. The database connection's **Read Only** setting must be **disabled**
2. The tool's **Allow Write** setting must be **enabled**

If either is not configured, write operations will be rejected with a clear error message.

Adding the sql_schema Tool

The sql_schema tool allows agents to explore database structure:

  1. Navigate to your agent's configuration
  2. Go to the Tools section
  3. Click "Add Tool" and select "SQL Schema"
  4. Configure the tool:
    • Database Connection - Select your SQL database connection
  5. Save the agent configuration

The agent can now introspect table structures, columns, indexes, and constraints.

MongoDB Tools

For MongoDB connections, use these specialized tools:

Adding the mongodb_find Tool

The mongodb_find tool allows agents to query documents:

  1. Navigate to your agent's configuration
  2. Go to the Tools section
  3. Click "Add Tool" and select "MongoDB Find"
  4. Configure the tool:
    • Database Connection - Select your MongoDB connection
  5. Save the agent configuration

Adding the mongodb_aggregate Tool

The mongodb_aggregate tool allows agents to run aggregation pipelines:

  1. Navigate to your agent's configuration
  2. Go to the Tools section
  3. Click "Add Tool" and select "MongoDB Aggregate"
  4. Configure the tool:
    • Database Connection - Select your MongoDB connection
  5. Save the agent configuration

Adding the mongodb_modify Tool

The mongodb_modify tool allows agents to insert, update, and delete documents:

  1. Navigate to your agent's configuration
  2. Go to the Tools section
  3. Click "Add Tool" and select "MongoDB Modify"
  4. Configure the tool:
    • Database Connection - Select your MongoDB connection
    • Allow Write - Enable this to allow modifications
  5. Save the agent configuration

Adding the mongodb_schema Tool

The mongodb_schema tool allows agents to explore collections and infer document structure:

  1. Navigate to your agent's configuration
  2. Go to the Tools section
  3. Click "Add Tool" and select "MongoDB Schema"
  4. Configure the tool:
    • Database Connection - Select your MongoDB connection
  5. Save the agent configuration

SQLite Tools

For working with SQLite files in the workspace (no external connection needed):

Adding the sqlite_query Tool

The sqlite_query tool allows agents to query SQLite files in the workspace:

  1. Navigate to your agent's configuration
  2. Go to the Tools section
  3. Click "Add Tool" and select "SQLite Query"
  4. Configure the tool:
    • FilePath - Path to the SQLite file in the workspace
  5. Save the agent configuration

!!! note "SQLite File Size Limit" SQLite files are limited to 100MB as they are loaded into memory for processing.

Using Database Tools in Chat

Once configured, agents can use database tools naturally in conversation:

Example: Querying SQL Data

User: "How many orders were placed last month?"

Agent: Uses sql_query tool "Based on the orders table, there were 1,247 orders placed in December 2024."

Example: Exploring SQL Schema

User: "What tables are in the database?"

Agent: Uses sql_schema tool "The database contains 15 tables including: customers, orders, products, inventory..."

Example: Modifying SQL Data (when write access is enabled)

User: "Update the status of order #12345 to 'shipped'"

Agent: Uses sql_execute tool "I've updated order #12345. Status is now 'shipped'. 1 row affected."

Example: Querying MongoDB

User: "Find all active users created this month"

Agent: Uses mongodb_find tool "Found 342 active users created in January 2025."

Example: MongoDB Aggregation

User: "What's the average order value by customer segment?"

Agent: Uses mongodb_aggregate tool "Based on the aggregation: Premium customers average $234, Standard $89, Basic $42."

Connection Pooling Recommendations

For high-volume production deployments, consider using a connection pooler:

PostgreSQL: PgBouncer

PgBouncer is recommended for PostgreSQL:

  1. Install and configure PgBouncer in front of your database
  2. Point your Raikoo database connection at PgBouncer instead of the database directly
  3. Configure PgBouncer in transaction mode for best compatibility

MySQL/MariaDB: ProxySQL

ProxySQL is recommended for MySQL:

  1. Install and configure ProxySQL in front of your database
  2. Configure connection multiplexing for optimal performance
  3. Set up read/write split if using replicas

SQL Server: Built-in Pooling

SQL Server and Azure SQL Database have built-in connection pooling.

MongoDB: Connection String Options

MongoDB connections can be optimized via connection string parameters:

  • maxPoolSize - Maximum connections in the pool (default: 5)
  • minPoolSize - Minimum connections to maintain
  • serverSelectionTimeoutMS - Timeout for server selection

Benefits of Pooling:

  • Reduced connection overhead
  • Better handling of many concurrent agents
  • Connection reuse across requests

Considerations:

  • Session-level features (temp tables, session variables) may not work as expected in transaction mode
  • Prepared statements may need special configuration
  • Monitor pool utilization to ensure adequate capacity

Troubleshooting Common Issues

Connection Timeouts

Symptoms: Connection test fails with timeout error

Solutions:

  • Verify the host and port are correct
  • Check that your database allows connections from Raikoo's IP addresses
  • Ensure no firewall is blocking the connection
  • Verify the database server is running

Authentication Failures

Symptoms: "Authentication failed" or "password authentication failed"

Solutions:

  • Double-check the username and password
  • Verify the user exists in the database
  • Check if the user is allowed to connect from Raikoo's IP
  • Ensure the user has permissions on the specified database

Permission Denied on Queries

Symptoms: Queries fail with permission errors

Solutions:

  • Verify the database user has SELECT permissions on the required tables
  • Check if row-level security policies are blocking access
  • Ensure the user can access the specified schema

Write Operations Blocked

Symptoms: "Read-only" or "Write access not enabled" errors

Solutions:

  • Check the database connection's Read Only setting (must be disabled)
  • Check the tool's Allow Write configuration (must be enabled)
  • Verify the database user has INSERT/UPDATE/DELETE permissions

Query Timeout

Symptoms: Queries are cancelled before completing

Solutions:

  • Optimize the query to run faster
  • Increase the Query Timeout setting on the database connection
  • Add appropriate indexes to the database tables
  • Consider breaking large queries into smaller ones

Security Best Practices

Credential Management

  • Create dedicated users - Don't use admin accounts; create specific users for Raikoo
  • Minimal permissions - Grant only the permissions needed for the intended use case
  • Rotate passwords - Update database passwords periodically

Network Security

  • Use SSL - Always use require or stricter SSL modes in production
  • Restrict IP access - Configure database firewalls to allow only necessary IP addresses
  • Use private networks - When possible, keep databases on private networks with VPN access

Permission Configuration

  • Default to read-only - Only enable write access when explicitly needed
  • Document access - Keep records of which connections allow writes and why
  • Review regularly - Periodically audit database connections and their permissions

Audit and Compliance

  • Use description fields - Both connections and tool calls include description fields for audit trails
  • Monitor usage - Review query logs for unusual patterns
  • Track changes - Document when connections are created, modified, or deleted

Next Steps

Now that you've configured database connections, you can:

  • Add database tools to agents - Enable agents to query and interact with your data
  • Create data-driven workflows - Build workflows that leverage database information
  • Monitor usage - Track how agents are using database connections
  • Expand access - Add more databases as your needs grow

Database connections provide a powerful foundation for data-driven AI capabilities. By properly configuring security settings and following best practices, you can safely enable your agents to work with your organization's data.