Datasource Registration — SQL Server Guide

What Is a Datasource?

A datasource in BizFirstGO is a named, tenant-scoped connection to an external data store. Each datasource has a unique datasourceId string identifier that workflow nodes reference. The actual connection string is stored securely in the BizFirstGO credential store and resolved at runtime — it never appears in workflow definitions.

Datasources are registered once per environment and can be reused across any number of workflows. To change the connection target (e.g., promote from staging to production), you update the datasource's credential — not every workflow that uses it.

Registration: Two Options

Option A — Through the BizFirstGO Admin Portal

Register the Credential

Go to Admin → Credential Store → Add Credential. Select type ConnectionString. Paste the SQL Server connection string. Note the generated credentialId.

Register the Datasource

Go to Admin → Datasources → Add Datasource. Set:

datasourceId: a slug like customer-data-db
type: SqlServer
credentialId: the ID from step 1
defaultSchema: dbo (or your application schema)
commandTimeoutSeconds: 30

Test the Connection

Click Test Connection. The portal executes SELECT 1 against the datasource and reports success or the error message.

Option B — Via the Datasource API

// POST /api/datasources
{
  "datasourceId": "customer-data-db",
  "tenantId": 42,
  "type": "SqlServer",
  "credentialId": 1001,
  "defaultSchema": "dbo",
  "commandTimeoutSeconds": 30,
  "maxRetryCount": 3,
  "metadata": {
    "description": "Customer data domain — Data Ocean primary store",
    "environment": "production",
    "owner": "platform-team"
  }
}

Datasource Configuration Fields

Field	Type	Required	Description
`datasourceId`	string	Yes	Unique identifier used in SQL node configuration. Use kebab-case slugs. Example: `customer-data-db`
`tenantId`	int	Yes	Tenant that owns this datasource. Datasources are tenant-scoped.
`type`	enum	Yes	Must be `SqlServer` for SQL Server datasources. Other values: `PostgreSQL`, `MySQL`, `Oracle`.
`credentialId`	int	Yes	References the credential store entry holding the connection string.
`defaultSchema`	string	No	Default schema for unqualified table references. Defaults to `dbo`.
`commandTimeoutSeconds`	int	No	SQL command timeout. Default: 30. Increase for long-running batch queries. Max: 300.
`maxRetryCount`	int	No	Retry count for transient SQL errors. Default: 3. Uses exponential back-off.
`metadata`	object	No	Free-form JSON for documentation/tagging purposes. Not used at runtime.

How the Runtime Resolves a Datasource

// Simplified IDatasourceConnectionFactory implementation
public interface IDatasourceConnectionFactory
{
    Task<SqlConnection> GetConnectionAsync(
        string datasourceId,
        int tenantId,
        CancellationToken ct = default);
}

// Internal resolution sequence:
// 1. Load datasource record from cache (keyed by tenantId + datasourceId)
// 2. Call ICredentialResolver.GetConnectionStringAsync(datasource.CredentialId)
// 3. Open SqlConnection with the resolved connection string
// 4. Return the open connection to the SQL node for query execution

Using the Datasource in a SQL Node

Once registered, reference the datasourceId directly in Flow Studio SQL nodes:

// SqlQueryNode configuration (JSON representation)
{
  "nodeType": "SqlQueryNode",
  "datasourceId": "customer-data-db",
  "query": "SELECT CustomerId, Name, Email FROM Customer WHERE TenantId = @tenantId AND CustomerId = @customerId",
  "parameters": {
    "tenantId": "{{workflow.tenantId}}",
    "customerId": "{{input.customerId}}"
  },
  "outputVariable": "customer"
}

Datasource Changes Are Zero-Downtime

If you need to point a datasource to a different server (e.g., after a database migration), update the credential in the credential store. The datasource cache invalidates automatically on credential update. Running workflows pick up the new connection on their next SQL node execution — no workflow restarts required.

Multiple Datasources Per Tenant

A single tenant can have many datasources — one per application domain, one per environment, one per third-party database integration. There is no practical limit. Name them clearly:

customer-data-prod, customer-data-staging
inventory-db, finance-db, hr-db
legacy-erp-readonly

Workflows use the datasourceId string, so migrating from staging to production is as simple as updating the node configuration from customer-data-staging to customer-data-prod.

← SQL Server Setup Next: AI-Ready Schema Design →