Alternate User Data Sources

Alternate User Data Sources let you point different users to different databases or schemas for the same app and the same report. Register your app once with a primary data source, add alternate data sources for each customer or environment, then assign each user to the alternate they should use. The user runs the same report and Yurbi swaps the connection at runtime.

This is the right tool for single-tenant database models — where each customer has their own physically separate database — and for any scenario where the same report needs to run against different connections for different users.

When This Applies

Use Alternate User Data Sources when:

Each customer's data lives in its own database (single-tenant database model)
You're running a demo or training environment that should look identical to production but pull from a different connection
Different regions have separate databases (US-East DB, EU-West DB) with identical schemas
You want to test new reports against staging without duplicating the app
An internal user needs to switch between development and production data without re-logging in

If your customers all share one database and are scoped by a column (like customer_id), you don't need this feature — Row-Level Security is the right tool.

How It Works

A note on Yurbi terminology before we dive in: an integration is the connection to a data source — a registered server with credentials. An app is the semantic layer built on top of that integration. Each app has exactly one integration, but you can register multiple integrations against the same datasource if you want separate semantic layers or want to split direct SQL access from semantic-layer access. Alternate User Data Sources are configured at the integration level within an app — same semantic layer, multiple physical connections behind it.

The three pieces:

App registration points to a primary data source. This is the connection used by anyone who doesn't have an alternate assigned.
Alternate data sources are additional connections attached to the same app, each with a label (e.g., "Acme Production", "Widget Inc Staging").
User assignment uses the Default dropdown on the user's App Assignments to pick which alternate that user should use. Yurbi swaps the connection when the user runs a report against this app.

Critical requirement: all alternate data sources must have the same schema as the primary. The same tables, the same columns, the same data types. Reports are built against the app's semantic layer, which assumes one schema shape. If the alternates diverge from that shape, reports will fail or return wrong results.

Prerequisites

Configuring alternate data sources requires Admin access to Yurbi and access to the Architect section.

You should have:

An app already registered in Architect with a working primary data source
Connection details (host, port, database name, credentials) for each alternate
Verified that each alternate's schema matches the primary

Setting Up Alternate Data Sources

Step 1: Open the App in Architect

Navigate to Architect → [your app]

[SCREENSHOT: Architect section showing the apps list with one app selected]

Open the app you want to add alternates to. You'll see the app's overview with sections for its data source, tables, joins, and so on.

Step 2: Add Alternate Data Sources

Find the Alternate Data Sources section in the app configuration.

[SCREENSHOT: Architect — App configuration showing Alternate Data Sources section with Add button]

Click Add Alternate Data Source. A form appears asking for:

Name A descriptive label for this connection — typically the customer name, environment, or region. Examples: "Acme Corp Production", "Widget Inc", "EU-West Region", "Training Environment". This name appears in the Default dropdown on user records.

Connection details Host, port, database name, schema, username, password — the same fields you filled in when you registered the app originally, but pointing at this alternate's database.

Description Optional, but recommended. Useful for noting what this connection is for and any special handling (e.g., "Read-only replica; do not write").

Click Save and Yurbi tests the connection.

Step 3: Test Each Alternate

Once saved, use the Test Connection button to verify Yurbi can reach the alternate database. A failed test here will mean failed reports later — fix the connection before assigning users.

A good additional smoke test: temporarily assign yourself to the new alternate (see step 4 below), run a known report, verify the data is what you expect, then switch yourself back to Default.

Repeat steps 2 and 3 for each customer, region, or environment you need to support.

Assigning Users to Alternate Data Sources

Once the app has alternates configured, you can route users to them on the user record.

Navigate to Settings → Security → Users → [edit user]

Scroll to App Assignments.

[SCREENSHOT: User Edit panel — App Assignments section showing Agent/Builder/Architect checkboxes and the Default dropdown]

For each app row, the Default dropdown on the right lists every alternate data source configured for that app, plus a Default option that uses the app's primary data source.

Pick the alternate this user should use. Save & Apply.

The user runs the same reports they always have — Yurbi handles the connection swap automatically. They don't see anything different in the interface; the data is just routed to their assigned connection.

Important: the Default dropdown is per-app, per-user. The same user can be on different alternates for different apps. Useful when a customer has separate databases for, say, CRM data and billing data.

Common Configuration Scenarios

Scenario 1: Single-Tenant Database per Customer

Goal: Each customer has their own database; users should see only their customer's data

Register the app pointing to your primary database (could be a demo DB, a template, or your first customer)
For each customer, add an Alternate Data Source pointing to that customer's database
Create groups per customer (see Groups and Library Folder Permissions)
When creating each customer's users, set their App Assignment's Default dropdown to that customer's alternate

Result: same reports, same dashboards, different data per customer. Maintenance happens in one place (the primary app); every customer benefits from every fix and feature.

Scenario 2: Demo / Training Environment

Goal: New users learn against safe demo data before getting production access

Register the app pointing to production
Add an Alternate Data Source pointing to a demo database (same schema, anonymized data)
When onboarding a new user, set the Default dropdown to "Demo"
After training, edit the user and switch back to Default

Scenario 3: Multi-Region with Identical Schemas

Goal: Same app, different physical databases per region

Register the app pointing to one region's database (call it the canonical region)
Add Alternate Data Sources for each additional region
Set each user's Default dropdown to their region's alternate
Reports built once work everywhere

Scenario 4: Production / Staging Switching for Internal Users

Goal: Developers and QA need to flip between prod and staging without separate apps

Register the app pointing to production
Add a "Staging" alternate
For users who need to switch, you'll edit their Default dropdown when they want to switch environments

For frequent switching, some teams maintain two user accounts per internal person — one routed to production, one to staging — and switch by signing in as the right account.

Combining with Row-Level Security

Alternate Data Sources and Row-Level Security solve overlapping problems but at different layers. The right choice depends on your data model.

Use Alternate Data Sources when: Customer data is physically separated into different databases. RLS isn't needed because the data is already isolated at the connection level.

Use Row-Level Security when: Customer data shares a database and is identified by a column (customer_id, tenant_id, region). RLS filters rows at query time.

Use both when: Some apps have per-customer databases (use alternates) while other apps have shared schemas (use RLS). Yurbi doesn't force a single approach — pick the right tool per app.

For the RLS side of this, see Row-Level Security: Profile Tags, Data Tags, and Policies.

Best Practices

Keep schemas in lockstep. Reports assume one schema shape. If you add a column to the primary database, add it to every alternate. Skipping an alternate breaks every report that touches the new column for users on that alternate.

Use a deployment process for schema changes. Manual schema sync across customer databases gets out of step quickly. Version-controlled migrations or a deployment tool prevents drift.

Name alternates clearly. "Acme Corp" or "Customer 12345" — something a future admin can correlate to a customer without a lookup. The name appears in the dropdown.

Test before assigning real users. Temporarily route yourself to a new alternate, run a known report, and verify the data is correct. Catching a connection misconfiguration before a customer sees wrong data is much cheaper than after.

Document which user goes where. A simple spreadsheet (Customer → Group → Alternate Data Source) saves time later when you're auditing or onboarding new admins.

Keep credentials managed. Connection passwords are stored in Yurbi's app configuration. Rotate them on the schedule your security policy requires, and update Yurbi when source credentials change.

When Changes Take Effect

New alternate data source: available immediately to assign on user records.

User dropdown change: takes effect on the user's next request. No logout required.

Connection credential update: in-flight queries finish on the old credentials; the next query uses the new ones.

Common Issues

Report works for some users but fails for others on the same app. Their alternate data source connection is broken or has different credentials. Open the app in Architect, find the failing alternate, test the connection.

Report returns no data for an alternate-assigned user but works on Default. Either (1) the alternate database has different (or no) data matching the report's filters, or (2) the alternate's schema is missing a column the report uses. Verify the alternate has the same schema and representative data.

Wrong data showing up for a user. Check the user's Default dropdown — they may be on the wrong alternate. Easy to typo when onboarding a customer.

"Connection failed" when adding an alternate. Typical causes: wrong host or port, firewall blocking Yurbi's outbound connection, credentials don't have access to the database, schema name typo. Test the connection from the same machine Yurbi runs on to confirm reachability.

Report editor can only see the primary's data. Reports are built against the app's semantic layer, which connects to the primary. When you build a report, you'll see the primary's data. When users run it, they see their alternate's data. This is by design — schemas are assumed identical.

Remember: All alternates must share the same schema as the primary. Schema drift across alternates is the most common cause of broken reports in this setup.