Skip to main content
Share / Export

SQL Bridge FAQ

This FAQ is written for customer admins, IT contacts, and implementation teams who want a clear explanation of what SQL Bridge is, what it does, and what is required to set it up safely.

What is SQL Bridge?

SQL Bridge is a lightweight service that runs in the customer environment near the customer's SQL Server. It allows TUDS to securely access approved SQL capabilities over HTTPS without exposing the SQL Server directly to the internet.

In practical terms, SQL Bridge acts as a controlled connection layer between TUDS and the customer's SQL environment.

Why does TUDS use SQL Bridge?

TUDS uses SQL Bridge when a customer wants TUDS to work with customer-hosted Vista-related SQL data.

The bridge exists so that:

  • TUDS does not need direct public access to SQL Server

  • database access can be routed through a controlled service

  • permissions can be enforced at the bridge layer

  • customer IT can validate, monitor, and troubleshoot the connection more easily

Does SQL Bridge expose our SQL Server directly to the internet?

No. The intended model is that TUDS connects to the bridge, and the bridge connects to SQL Server inside the customer environment.

The database itself is not the public integration point. SQL Bridge is the controlled integration point.

What exactly does the bridge do?

At a high level, the bridge:

  • runs on a customer-controlled machine

  • receives authenticated HTTPS requests from TUDS

  • validates authorization before allowing access

  • connects to SQL Server using configured SQL credentials

  • allows approved read and write operations based on the enabled bridge capabilities

Is SQL Bridge just a generic open SQL tunnel?

No. The bridge is not intended to be an unrestricted SQL passthrough.

The current bridge model separates read and write access into controlled lanes. Read-only SQL is restricted to approved read behavior, and more sensitive write actions require explicit permissions and narrower execution paths.

How is access secured?

Bridge access uses HTTPS plus token-based authorization.

The bridge validates short-lived JWTs and enforces route-level permissions. This means requests must be both authenticated and authorized for the specific type of action being requested.

Can access be restricted so only TUDS traffic can reach the bridge?

Yes. For customers who want tighter network controls, bridge traffic can be restricted to the two static public IP addresses used by TUDS bridge ingress today.

That means customer IT can allow only those known TUDS source IPs rather than opening access broadly. This is separate from the bridge's HTTPS and JWT-based authorization controls, and gives customers an additional network-layer restriction.

On the TUDS side, those bridge ingress servers are also hardened so that:

  • administrative access is restricted through Tailscale rather than public SSH

  • origin TLS is protected with Cloudflare origin certificates

  • public ingress is limited to bridge routing traffic on standard web ports

Taken together, that gives customers a layered story: restricted source IPs, encrypted transport, token-based authorization, and hardened TUDS-managed ingress.

This is a defense-in-depth model rather than a single control. Customers can combine network allowlisting with application-layer authorization and hardened TUDS-managed ingress to keep bridge traffic tightly scoped to TUDS.

How are SQL credentials handled?

SQL credentials are entered during bridge setup on the customer machine.

The current setup model stores SQL passwords in Windows-protected local storage. Non-secret bridge settings are written tobridge-config.json, but SQL passwords are not intended to remain in that file.

Can we use a least-privilege SQL account?

Yes. That is the recommended approach.

For most customers, the simplest setup is a single shared least-privilege SQL login with access only to the specific database capabilities required for the agreed workflows.

Can we map bridge usage to individual SQL accounts?

Yes. The bridge supports both:

  • a single shared SQL account

  • individual mapped SQL accounts for per-user identity models

If there is no strong reason to start with per-user SQL identities, the simpler shared-account model is the recommended starting point.

Where does SQL Bridge run?

The bridge runs on a Windows machine in the customer environment that can reach the target SQL Server.

That machine should be treated as the local runtime host for the bridge service and its tray application.

What does customer IT need before setup starts?

Before setup, customer IT should have:

  • the SQL Server host

  • the SQL Server port

  • the database name

  • the SQL username and password

  • a Windows machine that can run the bridge

  • network connectivity from that machine to SQL Server

  • outbound HTTPS connectivity for the bridge

What is the basic setup process?

The normal setup flow is:

  1. Create or review the bridge in TUDS.

  2. Download the bridge package and configuration from TUDS.

  3. Install theTUDS SQL Bridge Trayapplication on the target Windows machine.

  4. Enter the bridge settings and SQL connection information.

  5. Start the bridge.

  6. Validate local health.

  7. Validate the bridge from TUDS.

  8. Run a bridge-dependent workflow successfully.

How do we know setup is complete?

Setup should not be considered complete until all of the following are true:

  • the bridge starts successfully

  • the health endpoint responds successfully

  • the TUDS bridge test succeeds

  • a real bridge-dependent workflow succeeds

  • logs do not show blocking errors

How do we validate the bridge after installation?

There are two important validation layers:

Local validation

Confirm the bridge is running and that the health endpoint responds successfully from the machine or approved network path.

TUDS validation

After local health succeeds, return toOrganization > Billing and Security > Bridgesand run the bridge test in TUDS. Then confirm that a real bridge-backed workflow succeeds.

What kinds of workflows depend on the bridge?

Examples can include:

  • refreshing company or metadata information

  • bridge-backed reporting

  • financial workflows that depend on SQL connectivity

The exact workflows depend on the customer's enabled TUDS features.

What if the bridge is healthy locally but TUDS still cannot connect?

That usually points to a configuration or network-path issue between TUDS and the bridge URL rather than a local bridge runtime failure.

The main things to check are:

  • the configured bridge URL

  • HTTPS or proxy configuration

  • whether the correct bridge is selected or marked as default

  • whether customer networking is allowing the expected request path

What if the bridge starts but SQL access fails?

That usually means the bridge runtime is healthy but the SQL connection settings or SQL permissions still need attention.

Typical checks include:

  • SQL Server host

  • port

  • database name

  • SQL authentication mode

  • firewall rules

  • SQL credentials

What logs are available if something goes wrong?

There are two main places to look:

TUDS Bridge Logs

In TUDS, useOrganization > Billing and Security > Bridge Logsto review bridge-side request history, including endpoint, status, response time, and related request details.

Local bridge log

On the bridge machine, review:

%LOCALAPPDATA%\tuds-ai\bridge.out.log

This is especially useful for startup failures, local credential issues, and runtime errors on the bridge host.

Who usually owns bridge issues?

Bridge issues are often shared between the TUDS team and the customer's IT team.

In general:

  • TUDS typically owns bridge token or application integration logic issues

  • customer IT typically owns local machine restrictions, SQL Server access, firewall rules, proxy rules, and endpoint security software behavior

  • some bridge deployment and routing issues require joint troubleshooting

Is SQL Bridge appropriate for security-conscious customers?

Yes, that is the intent of the design.

The customer-comfort position is:

  • SQL Server is not the directly exposed integration point

  • bridge access is protected with HTTPS and authorization

  • bridge activity can be validated and logged

  • SQL passwords are stored locally in protected Windows storage

  • write behavior is more restricted than a generic open SQL connection model

What is the simplest way to explain SQL Bridge to a customer?

Use this:

SQL Bridge is a small service installed in the customer environment that gives TUDS controlled, secure access to approved SQL capabilities without directly exposing the customer's SQL Server to the internet.