Dynamic Database Switching at Session-Creation Time

This document supplements the instructions in chatbot-embed.md.
It explains how to leverage the optional databaseConfig field when calling

POST /api/chatbot/v2/session

so that a single chatbot can connect to different underlying databases on a per-session (or per-tenant) basis.

Typical use-case: in a multi-tenant SaaS architecture every customer (or team) owns its own database, but all databases share an identical schema.
By passing the tenant-specific connection information in databaseConfig at session-creation time you can transparently route queries to the correct database without creating multiple chatbots.

Request Body (excerpt)

{
  "chatbotid": "<your-bot-id>",
  "name": "Alice",
  "email": "alice@example.com",
  "databaseConfig": {
    /* DB-specific connection fields */
  }
}

databaseConfig is simply an object whose shape depends on the target database (see next section).
If the field is omitted, the chatbot will fall back to the default connection settings saved in the dashboard.

Supported Databases & Configuration Shapes

Below are the exact JSON shapes accepted by the backend.
Copy the template that matches your database, fill in real values, and embed it inside databaseConfig.

All examples show minimal required fields; optional fields are marked accordingly.

1. MySQL / PostgreSQL / SQL Server / Vertica

{
  "connectionString": "mysql://user:pass@host:3306/dbname"
}

2. Snowflake

{
  "accountName": "my_account",
  "database": "MY_DB",
  "username": "USER",
  "password": "********",
  "schema": "PUBLIC",
  "warehouse": "COMPUTE_WH",   // optional
  "role": "ACCOUNTADMIN"       // optional
}

3. SAP HANA

{
  "serverNode": "hanahost:39015",
  "uid": "USER",
  "pwd": "********",
  "databaseName": "MY_DB",
  "currentSchema": "PUBLIC",
  "encrypt": "true",                 // optional
  "sslValidateCertificate": "false"  // optional
}

4. BigQuery

{
  "projectId": "my-gcp-project",
  "credentials": "{...service-account-json...}"
}

5. Trino

{
  "server": "https://trino.example.com:8443",
  "catalog": "hive",
  "schema": "default",
  "username": "USER",
  "password": "********"
}

Example: Creating a Session for Tenant A

curl --location 'https://www.askyourdatabase.com/api/chatbot/v2/session' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer ${API_KEY}' \
--data-raw '{
  "chatbotid": "5da7b8cf3a372f5e6e6b64af9ae189c7",
  "name": "Tenant A User",
  "email": "user@tenant-a.com",
  "databaseConfig": {
    "connectionString": "postgres://tenant_a:secret@db.tenant-a.com:5432/data"
  }
}'

The response contains the usual OAuth-style url.
When the user loads that URL (e.g. in an <iframe>), every query issued by the chatbot will run against the tenant-specific database provided above.

Tips & Best Practices

1. Security – Keep database credentials on the server side; never expose them to the browser.
   The example above uses curl for clarity, but in production you should wrap the request in your backend (see chatbot-embed.md).

2. Schema-compatible design – Ensure all tenant databases follow the same schema so that your prompt engineering and SQL generation remain valid across tenants.

3. Connection pooling – If you manage many tenants, reuse connections (or connection pools) keyed by a hash of databaseConfig to avoid overhead.

By adopting dynamic databaseConfig, a single chatbot definition can securely serve hundreds of isolated data stores—keeping your code DRY and your architecture scalable.