Connection Setup
The Connection Setup page guides users through configuring their first data source connection. It supports multiple database types, validates connectivity in real-time, and optionally scans the schema to prepare the AI Service for conversational queries against the connected data.
Supported Data Sources
| Data Source | Driver | Default Port | TLS Support |
|---|---|---|---|
| PostgreSQL | asyncpg | 5432 | Yes |
| MySQL | aiomysql | 3306 | Yes |
| SQL Server | pymssql | 1433 | Yes |
| Snowflake | snowflake-connector | 443 | Required |
| BigQuery | google-cloud-bigquery | 443 | Required |
| Databricks | databricks-sql-connector | 443 | Required |
| Trino | trino | 8080 | Optional |
| ClickHouse | clickhouse-driver | 8123 | Optional |
Connection Form
The connection form (ConnectionSetupPage.tsx) adapts its fields based on the selected data source type:
Common Fields
| Field | Type | Required | Description |
|---|---|---|---|
| Connection name | Text | Yes | Friendly name for the connection |
| Data source type | Dropdown | Yes | Database engine selection |
| Host | Text | Yes | Database hostname or IP |
| Port | Number | Yes | Connection port (pre-filled per type) |
| Database | Text | Yes | Database name |
| Username | Text | Yes | Authentication username |
| Password | Password | Yes | Authentication password |
| SSL/TLS | Toggle | No | Enable encrypted connection |
Cloud-Specific Fields
| Data Source | Additional Fields |
|---|---|
| Snowflake | Account, Warehouse, Role, Schema |
| BigQuery | Project ID, Dataset, Service Account JSON |
| Databricks | Workspace URL, HTTP Path, Token |
Connection Testing
Real-time connection validation runs when the user clicks "Test Connection":
interface ConnectionTestResult {
success: boolean;
latency_ms: number;
server_version: string;
database_accessible: boolean;
schemas_found: number;
tables_found: number;
error?: string;
}Test Steps
| Step | Check | Timeout |
|---|---|---|
| 1 | TCP connectivity | 5 seconds |
| 2 | Authentication | 10 seconds |
| 3 | Database access | 5 seconds |
| 4 | Schema discovery | 15 seconds |
Schema Scanning
After a successful connection, the user can optionally scan the schema:
| Scan Type | Description | Duration |
|---|---|---|
| Quick | Table and column names only | Seconds |
| Standard | Names, types, and basic statistics | Minutes |
| Full | Complete profiling with sample data | 5-15 minutes |
Security
Connection credentials are handled securely:
| Security Measure | Implementation |
|---|---|
| Credential storage | Encrypted in Kubernetes Secrets |
| Transit encryption | TLS for all database connections |
| Password masking | Passwords never displayed after entry |
| Audit logging | Connection creation logged in audit trail |
Error Handling
| Error | User Message | Suggested Action |
|---|---|---|
| Connection refused | "Unable to connect to the database server" | Check hostname, port, and firewall |
| Authentication failed | "Invalid username or password" | Verify credentials |
| Database not found | "Database does not exist" | Check database name |
| SSL required | "Server requires an encrypted connection" | Enable TLS toggle |
| Timeout | "Connection timed out" | Check network connectivity |
Skip Option
Users who do not have a database ready can skip this step and configure connections later through the Data Workbench settings. A sample dataset is available for users who want to explore the platform without their own data.