# Database Application

{% hint style="info" %}
**Early Access**: This integration is available in Early Access. Contact Veza support to request access for your organization.
{% endhint %}

### Overview

Use the Database Application integration to incorporate identity and authorization metadata from sources that do not have built-in Veza connectors but can export or provide data as the result of a SQL query.

You can create a Database Application integration in Veza to:

* Import user and authorization data from legacy or custom applications
* Integrate with SaaS applications backed by a database
* Model employee access to bespoke or specialized systems

The integration uses the Open Authorization API (OAA) to map database query results to the OAA Application template.

The **Application** template models users, groups, roles, and resources across applications for a wide variety of authorization use cases. An introduction to the Application Template [can be found here](/4yItIzMvkpAvMVFAamTf/developers/api/oaa/best-practices/using-oaa-templates.md).

### When to use the Database Application integration

The Database Application integration is ideal for systems that do not provide REST API access to authorization metadata but store that data in a SQL database.

* Legacy applications with user and role tables
* Custom business applications built in-house
* Other specialized industry tools without native APIs that are backed by a SQL database

The Database Application integration enables modeling identity and permissions metadata for any application not natively supported by Veza with flexible column mapping, custom properties, and support for popular SQL servers.

### Adding a Database Application integration

#### Prerequisites

To create a Database Application integration, you will need:

* The connection details for the SQL host (including server type, hostname, port, and credentials)
  * **Ensure that the credentials used for database connection provide the least-privilege necessary to execute the query**
  * If not using Lifecycle Management functionality, the account should only have `SELECT` permissions on the necessary tables
  * If using the Lifecycle Management capabilities to manage the application, ensure that the account can only call the necessary stored procedures (in addition to the necessary read permissions).
* A read-only SQL query that returns the information to be included in the integration
  * This query can be as simple as `SELECT * from <table_name>` or a complex query that includes multiple joins and named columns.
* Sufficient permissions to execute the query with the collected credentials
* Sufficient permissions in Veza to create an integration
* Understanding of the data model for the source application
* A plan for mapping between columns in the query result and Veza attributes

> For more information about Veza user roles and permissions, see [Roles](/4yItIzMvkpAvMVFAamTf/administration/administration/users/roles.md).

#### Supported SQL server types

The Database Application integration supports connecting to the following SQL server types:

* Microsoft SQL Server
* MySQL / MariaDB
* Oracle Database
* PostgreSQL

#### Create a Database Application integration

To create a new Database Application integration:

1. Navigate to **Integrations** > **Add Integration**
2. Choose **Database Application** from the options
3. Enter an integration name
   * Use a title that uniquely identifies this integration source
   * Avoid generic terms such as "application" or "database"
   * If you have more than one environment, consider including the environment name
4. Complete the following fields:
   * **Database Type**: Select the type of database from the dropdown list
   * **Host**: Enter the IP address or fully qualified domain name (FQDN) of the database host
   * **Port**: Enter the port on which the SQL instance is running
   * **Username**: Enter the username with which to connect to the SQL server
   * **Password**: Enter the password with which to connect to the SQL server
   * **SSL Mode**: Select the SSL connection mode:
     * `disable` - No SSL encryption
     * `require` - Require SSL connection (no certificate verification)
     * `verify-ca` - Require SSL and verify CA certificate
     * `verify-full` - Require SSL and verify full certificate chain including hostname
   * **SQL Query**: Enter the text of the SQL query that will return information to be parsed into an application on the Veza platform
   * **Batch Size**: (Optional) Enter the number of records to be fetched during batched retrieval (default: 1000)
   * **CA Certificate**: (Optional) If using an SSL mode that requires host certificate verification, provide it here
   * **Application Name**: A unique identifying name for this application instance (e.g., "Marketing CRM - Prod", "HR Portal - Dev")
   * **Application Type**: The general category or system type (e.g., "CRM", "DevOps Tool"). In Veza, this is displayed as a prefix on entity names, e.g., *CRM User*, *DevOps Tool Role*.
   * **Resource Type**: (Optional) The type categorization for resources in this application (e.g., "Database", "Project", "Location"). Required if you plan to map columns to resource entities.
   * **Column Mapping Configuration**: See Column Mapping section for details
5. Click **Create Integration** to trigger extraction and parsing

### Column mapping

The Database Application integration allows you to map columns in your SQL query result to specific Veza attributes.

For each column provided by the result, you should:

1. Click **Add Column Definition**
2. Provide the name of the column from the SQL query result
3. Select the target entity type for mapping (available entities depend on the selected template)
4. Select the specific entity attribute to map to (only attributes applicable to the selected entity type will be shown)
5. For custom properties, specify a name and data type

#### Supported entity types and attributes

> For all entities, an ID or Name is required. If ID is not provided, Name is automatically used as the unique identifier for the entity. Both are also supported.

The available entity types and attributes depend on the template you select. Each template supports different entity types.

**Application Template Entities**

**User Attributes**

| Attribute                | Description                                            |
| ------------------------ | ------------------------------------------------------ |
| ID                       | Unique identifier for the user                         |
| Name                     | Display name for the user                              |
| Is Active                | Boolean indicating if the user is active               |
| Created At               | Timestamp when the user was created                    |
| Last Login At            | Timestamp of the user's last login                     |
| Deactivated At           | Timestamp when the user was deactivated                |
| Password Last Changed At | Timestamp of the last password change                  |
| Email                    | User's email address                                   |
| Custom Properties        | Map any column to a custom user property (type varies) |
| Owner ID                 | Entity Owner ID to assign                              |
| Owner Type               | User node type for Entity Owner(s)                     |

**Group Attributes**

| Attribute         | Description                                             |
| ----------------- | ------------------------------------------------------- |
| ID                | Unique identifier for the group                         |
| Name              | Name of the group (supports list format)                |
| Created At        | Timestamp when the group was created                    |
| Custom Properties | Map any column to a custom group property (type varies) |
| Owner ID          | Entity Owner ID to assign                               |
| Owner Type        | User node type for Entity Owner(s)                      |

**Role Attributes**

| Attribute         | Description                                             |
| ----------------- | ------------------------------------------------------- |
| ID                | Unique identifier for the role                          |
| Name              | Name of the role (supports list format)                 |
| Permissions       | Permissions assigned to the role (supports list format) |
| Custom Properties | Map any column to a custom role property (type varies)  |
| Owner ID          | Entity Owner ID to assign                               |
| Owner Type        | User node type for Entity Owner(s)                      |

**Resource Attributes**

| Attribute         | Description                                                |
| ----------------- | ---------------------------------------------------------- |
| ID                | Unique identifier for the resource                         |
| Name              | Name of the resource                                       |
| Custom Properties | Map any column to a custom resource property (type varies) |
| Owner ID          | Entity Owner ID to assign                                  |
| Owner Type        | User node type for Entity Owner(s)                         |

> **Note:** Resource Type is configured at the Application template level (not per-column mapping) and applies to all resources created by this integration.

### Data type handling

#### Boolean values

The following values are treated as `TRUE` (case-insensitive):

* `true`, `t`
* `yes`, `y`
* `1`
* `active`
* `enabled`

Any other value is treated as `FALSE`.

#### Timestamp formats

Veza supports standard timestamp formats:

* `2023-04-12T15:34:56.123456789Z` (RFC3339 with nanoseconds)
* `2006-01-02T15:04:05Z07:00` (RFC3339)
* `20060102150405` (Active Directory format)
* `2006-01-30 15:04:05Z07:00`
* `2006-01-30 15:04:05`
* `2006-01-30`
* `2006-01-30T`
* `2006-01-30T15:04:05`
* `2006-01-30T15:04:05Z`
* `1/2/2006` (MM/DD/YYYY format)

Timestamps are considered unset when the value is `never`, `null`, `none`, `false`, `0` or empty. Invalid timestamps will result in a processing error.

#### String lists

For attributes that support lists (such as Role Name List, and Group Name List), values should be comma-separated within the cell and the list enclosed by quotes `"`.

### Updating a Database Application integration

Incremental updates are not supported; you must submit the complete data set for each update.

{% hint style="danger" %}
**⚠️ Warning: Configuration Updates**

When updating the configuration fields or mappings for an existing Database Application integration, changes are not reflected until after the next SQL query extraction is processed. For example when updating the Application Type field, changing this field alone and saving the integration will not immediately change the type in the Veza system. The new type will not be available in graph or in other features such as Lifecycle Management (LCM) until after the next upload is processed.

**Required Process for changing configurations:**

1. Update the configuration fields in the integration settings
2. Allow the Veza platform to complete the extraction and parse process
3. Verify that entity names are consistent across all Veza components
   {% endhint %}

#### Update mappings for an integration

1. Find the Database Application integration on the Veza **Integrations** page
2. Click the integration name to view details
3. Click **Edit**
4. In the integration configuration, click **Edit** above the table of current mappings
5. Modify your column mappings as needed
6. Click **Save Configuration** to apply the changes

### Processing rules

* **Multiple Rows per Entity**: If the same entity (user, group, or role) exists in multiple rows, Veza processes them as follows:
  * Properties are set based on the first row where the entity ID (or Name if it is being used as the unique ID) occurs
  * For subsequent rows with the same identifier, only relationship assignments are processed (for example user to group, or user to role)
  * Role permissions are the only properties that are additive across all rows
* **Ignored Columns**: Columns that are not mapped (unchecked) are ignored during processing
* **Additional Columns**: SQL query results can contain more columns than are mapped - extra columns are ignored
* **Entity Identifiers**: Every entity type (user, group, role) requires an ID or Name (or both). If only one is provided, the same value is used for both fields and must be unique.
* **Identity Mapping**: The Application template allows you to specify which column(s) contain identity values (such as email addresses or usernames) for matching application users to identity provider users. Configure this in the Application template settings by entering comma-separated column names (e.g., `email` or `email,username`). These values enable Veza to correlate application users with corresponding users in connected identity providers like Okta or Azure AD.

### Related documentation

* [Open Authorization API (OAA) Templates](/4yItIzMvkpAvMVFAamTf/developers/api/oaa/templates.md)
* [Managing Teams and Permissions](/4yItIzMvkpAvMVFAamTf/administration/administration/users/teams.md)
* [Creating Custom Dashboards](/4yItIzMvkpAvMVFAamTf/features/insights/dashboards.md)
* [Understanding the Veza Access Graph](/4yItIzMvkpAvMVFAamTf/features/search.md)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.veza.com/4yItIzMvkpAvMVFAamTf/integrations/integrations/database-application.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.