> For the complete documentation index, see [llms.txt](https://docs.blitzware.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.blitzware.xyz/identity/database-connections.md).

# Database Connections

Choose where BlitzWare validates username and password identities.

Database Connections control where BlitzWare validates username and password identities for an Application.

BlitzWare remains the authentication authority. It still issues Tokens, applies MFA, checks licenses and Application security settings, records logs, and controls access. A Database Connection only changes where the User's credentials are checked.

## Connection modes

| Mode                        | What it does                                                                                                                                                          | Use it when                                                               |
| --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
| Hosted                      | Uses the normal BlitzWare User store.                                                                                                                                 | You want BlitzWare to store and validate Users.                           |
| Custom Database             | Calls your external system on every login. BlitzWare does not import the User into the hosted User store.                                                             | You already have a user database and want it to stay the source of truth. |
| Custom Database with Import | Checks BlitzWare first. If the User is missing, BlitzWare validates against your external system, imports the User, and uses the hosted User store for future logins. | You are migrating Users into BlitzWare gradually.                         |

{% hint style="info" %}
Only one enabled Database Connection is used for username/password login in each Application.
{% endhint %}

## Plan availability

| Tier | Database Connection access                                         |
| ---- | ------------------------------------------------------------------ |
| Free | Hosted User Store only                                             |
| Lite | API connection with Custom Database with Import                    |
| Plus | API connection with Custom Database or Custom Database with Import |
| Pro  | API, Direct MySQL, or SQL Server connection with all modes         |

Paid tiers allow one saved external Database Connection per Application. This is a saved configuration limit, not a simultaneous network connection limit.

## External strategies

Custom connections can use one of these strategies:

| Strategy     | Recommended for                                                | Details                                                                                                            |
| ------------ | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| API endpoint | Most production integrations                                   | [API Database Connections](/identity/database-connections/api-database-connections.md)                             |
| Direct MySQL | Advanced controlled environments                               | [Direct MySQL Database Connections](/identity/database-connections/direct-mysql-database-connections.md)           |
| SQL Server   | Advanced controlled environments using SQL Server or Azure SQL | [Direct SQL Server Database Connections](/identity/database-connections/direct-sql-server-database-connections.md) |

Use [Custom Database with Import](/identity/database-connections/custom-database-with-import.md) when you want a gradual migration into the hosted BlitzWare User Store.

## Configure a connection

For a Basic Application, open the Basic Application settings in the dashboard and find **Database Connections**.

For an OAuth Application, open the OAuth Application settings in the dashboard and find **Database Connections**.

Choose the mode, fill in the external configuration if needed, save the connection, then use **Test Connection** before enabling it for production logins.

## How it fits into authentication

```
User submits credentials
-> BlitzWare applies Application settings
-> Database Connection validates credentials
-> BlitzWare issues Tokens and records auth events
```

External systems cannot issue BlitzWare Tokens, create BlitzWare Sessions, or bypass BlitzWare Application security checks.

## Security behavior

* Connection secrets are encrypted at rest and redacted in dashboard responses.
* Stored secrets and operations are not displayed again after save.
* JavaScript scripts are disabled. Database Connections use declarative API or direct SQL operations.
* API connections require HTTPS and publicly reachable hosts.
* Direct SQL operations must use parameter bindings.

Related pages: [Hosted User Store](/identity/hosted-user-store.md), [User Import and Migration](/identity/user-import-and-migration.md), and [Testing Authentication Flows](/developers/testing-authentication-flows.md).