Multi-Tenant Database Connectivity Using Custom Attributes

In multi-tenant environments, it is common for each customer (tenant) to have a dedicated database within the same SQL Server instance. Maintaining separate data sources and report definitions for every tenant can become difficult to manage and scale.

To address this, Bold Reports provides Custom Attributes, which allow you to dynamically determine the target database at runtime while reusing the same reports and data source definitions across tenants.

To learn more about Custom Attributes and their capabilities, refer to:

• Custom Attribute Feature Documentation
  https://help.boldreports.com/enterprise-reporting/designer-guide/report-designer/manage-data/dataset/configure-custom-attribute/

• Custom Attributes Overview Blog
  https://www.boldreports.com/blog/custom-attributes-in-bold-reports/

Configuring a Dynamic Database Connection

When designing the data source, configure the connection string to use a Custom Attribute placeholder for the database name.

Example Connection String

Server=SQL01;
Database=${{:DatabaseName}};
User Id=ReportUser;
Password=********;

In this example, DatabaseName is a Custom Attribute. At runtime, Bold Reports resolves the attribute value and connects to the corresponding tenant database.

For detailed configuration steps, see:
https://help.boldreports.com/enterprise-reporting/designer-guide/report-designer/manage-data/dataset/configure-custom-attribute/

Example

Company1 → DatabaseName = Company1DB
Company2 → DatabaseName = Company2DB
Company3 → DatabaseName = Company3DB

The same report and data source can be reused across all tenants without modifying the report definition.

Managing Custom Attribute Values

The Custom Attribute values can be supplied through several mechanisms depending on your deployment model.

Site-Level Attributes

If reports are organized using tenant-specific sites, Custom Attribute values can be configured at the site level.

Site: Company1
└── DatabaseName = Company1DB

Site: Company2
└── DatabaseName = Company2DB

When the report runs within a site, the corresponding database value is automatically resolved.

Best suited for:

• One Site per Tenant architecture.
• Independent tenant administration.
• Tenant-specific configurations maintained at the site level.

User or Group-Level Attributes

Custom Attribute values can be assigned to users or groups.

Group: Company1
└── DatabaseName = Company1DB

Group: Company2
└── DatabaseName = Company2DB

or

User: [email protected]
└── DatabaseName = Company1DB

User: [email protected]
└── DatabaseName = Company2DB

This approach is particularly useful in a single-site multi-tenant architecture, where tenant access is controlled through users or groups and reports are organized using Categories and Subcategories.

Token-Based Attributes (Recommended for Embedded Deployments)

For embedded scenarios, the recommended approach is to pass the Custom Attribute values through the embed token.

In this model:

1. The application determines the current tenant.
2. The application generates the embed token.
3. Tenant-specific attribute values are included in the token.
4. Bold Reports resolves the attribute at runtime and connects to the appropriate database.

For implementation details, refer to:

Generate Embed Token Using Embed Secret and Pass User Context to Reports
https://support.boldreports.com/kb/article/19407/generate-embed-token-using-embed-secret-and-pass-user-context-to-reports

Benefits

• No tenant-specific configuration required inside Bold Reports.
• Centralized tenant management within the application.
• Simplified onboarding of new tenants.
• Best suited for SaaS and embedded deployments.

Single Data Source Across Multiple Databases

A common question is whether a single data source can automatically connect to all databases on a SQL Server instance or support database include/exclude filters.

Currently, there is no recommended approach to configure a data source that:

• Automatically includes all databases on a SQL Server instance.
• Supports “all databases except X” filtering.
• Dynamically discovers tenant databases.

Instead, the recommended approach is to:

1. Create a single logical data source.
2. Define the database name as a Custom Attribute.
3. Supply the appropriate database value based on the current tenant.

Shared Data Source
└── Database=${{:DatabaseName}}

This provides better:

• Security
• Tenant isolation
• Maintainability
• Scalability

Example Multi-Tenant Architecture

SQL Server
├── Company1DB
├── Company2DB
├── Company3DB
└── Company4DB

Shared Data Source
└── Database=${{:DatabaseName}}

Tenant Context
├── Company1 → Company1DB
├── Company2 → Company2DB
├── Company3 → Company3DB
└── Company4 → Company4DB

In this architecture:

• One report definition is maintained.
• One data source definition is maintained.
• Only the Custom Attribute value changes per tenant.

Benefits of Using Custom Attributes

• Single report definition across all tenants.
• Single data source definition across all tenants.
• Simplified report maintenance.
• Easier deployment and upgrades.
• Reduced administrative overhead.
• Strong tenant isolation.
• Flexible integration with embedded applications.
• Scalable multi-tenant architecture.

Recommendation

For multi-tenant environments where each customer has its own database within the same SQL Server instance, we recommend using Custom Attributes to dynamically resolve the database name at runtime.

For embedded deployments, the preferred approach is to pass the tenant-specific attribute values through the embed token, allowing the same reports and data source definitions to be reused across all tenants while maintaining proper tenant-level data isolation.