Skip to main content
Community Hub

Set up SqlDBM

TL;DR

Prepare an OAuth client, persona, and custom metadata in Atlan, then connect Atlan from the SqlDBM dashboard to sync Model Governance fields.

Your AI can read this via Docs MCPcurl -fsSL "https://docs.atlan.com/install-docs-mcp" | bashConnect

The SqlDBM integration is configured in SqlDBM, not in Atlan. SqlDBM pushes the values of its Model Governance fields onto your warehouse schemas, tables, views, and columns as custom metadata, and pulls custom metadata values back into SqlDBM on request. Atlan doesn't run a workflow for this integration, and nothing is installed from the Atlan Marketplace.

SqlDBM never creates connections, custom metadata structures, or properties in Atlan. Everything it writes to must already exist. The steps below prepare Atlan first, then connect SqlDBM.

Prerequisites​

Before you begin, make sure you have:

  • A SqlDBM account with Model Governance and the Atlan add-on enabled. Contact your SqlDBM account manager to enable either.
  • A user with the Governance role in SqlDBM, to create mappings, push, and pull.
  • Admin access to your Atlan workspace, to create the OAuth client, persona, and custom metadata.
  • The database your SqlDBM project models already cataloged in Atlan. SqlDBM writes onto existing assets, so crawl the warehouse connection first. See Supported databases.

Prepare Atlan​

These steps are done in Atlan by an admin.

Create custom metadata​

SqlDBM maps each of its Model Governance fields to a custom metadata property in Atlan. Create the structure and properties you want SqlDBM to populate before you connect. See Manage custom metadata structures.

  1. Create a custom metadata structure for the values SqlDBM manages.

  2. To let SqlDBM maintain the structure, mark it as SqlDBM-owned:

    • Set the structure's Name to SqlDBM.
    • Include the marker [managed-by:sqldbm] in the Description.

    On a SqlDBM-owned structure, SqlDBM adds your warehouse connection to a property's Connections on first push, and adds a new option to a dropdown property when a pushed value has no match. SqlDBM never changes a structure owned by another tool, and never removes an option.

  3. Add one property per SqlDBM field you plan to sync. The property type must pair with the SqlDBM field type. See Field and property types.

  4. On each property, set Applicable asset types to include schemas, tables, views, or columns as needed, and set Connections to include the warehouse connection SqlDBM maps to. Leaving Connections empty applies the property to every connection. A value written to a property that isn't applicable to the asset's connection persists but doesn't display on the asset page.

Create persona​

Create a persona that scopes what SqlDBM can read and write. See Create a persona.

  1. Create a persona for SqlDBM.

  2. Add a metadata policy on each warehouse connection SqlDBM reads and writes. Under Configure permissions, select Edit and clear every permission except:

    • Assets > Read, so SqlDBM can list databases, schemas, tables, views, and columns and read custom metadata values.
    • Update custom metadata values, so SqlDBM can write values on push.

    All permissions are granted by default, so clearing the rest is what keeps the persona least-privileged.

  3. Don't add a data policy. The integration reads and writes metadata only. It never queries or previews data.

The connection list in SqlDBM shows the connections the OAuth client can see through its persona. A client with no persona sees no connections.

Create OAuth client​

SqlDBM authenticates with an OAuth client, not a personal API token. Creating one needs admin access. See OAuth clients.

  1. In Atlan, open Admin, select API access, and open the OAuth tab.

  2. Select Generate new, then Generate OAuth Client.

  3. In Name, enter an identifier for SqlDBM, and add a Description for future admins.

  4. In Role, choose a base role. Pushing and pulling values needs no administrative permissions. If you use a SqlDBM-owned structure, choose a role that can manage custom metadata structures, because SqlDBM edits the structure's definition to add connections and dropdown options. With a lesser role, values still land, and the run report notes that the scope or option couldn't be updated.

  5. In Personas, select the persona you created in the previous step. The persona grants the client its permissions on the connections it names.

  6. Select Save, then copy the Client ID and the Client Secret and store them securely. The secret is shown once. If you lose it, delete the client and create a new one.

Configure network access​

SqlDBM calls your Atlan workspace URL over HTTPS. If your organization controls inbound traffic to the workspace, permit SqlDBM's requests according to your network policy. Ask SqlDBM support for the addresses its requests come from.

In Atlan's activity log, every value SqlDBM writes is attributed to the OAuth client's service account, so you can tell SqlDBM's changes apart from edits people make in Atlan. SqlDBM also sends the header x-atlan-agent-id: sqldbm on every request.

Connect Atlan​

  1. In the SqlDBM Dashboard, open Integrations and select Data Governance.

  2. On the Atlan card, select Connect.

  3. Enter:

    • The Client ID of the OAuth client.
    • The Client secret of the OAuth client.
    • Your Atlan workspace URL, for example https://my-company.atlan.com.

  4. Select Save. The connection is account-wide. Everyone with the Governance role in your SqlDBM account can now create mappings, push, and pull.

Map projects to Atlan​

Mappings are created inside a SqlDBM project. An Atlan mapping targets one database inside one connection, and covers every schema, table, view, and column in that database.

  1. In the project, open Settings and conventions and select Atlan settings. Alternatively, open the Atlan integration menu in the Database Documentation toolbar and select Settings and mappings.

  2. On the Settings tab, enter a name, then select a Connection and a Database.

  3. On the Attribute mapping tab, pair each SqlDBM field with its Atlan property. Properties are listed as Structure.Property, for example SqlDBM.Sensitivity.

  4. On the Objects tab, review the automatic name matching and resolve any unmatched objects.

  5. Select Push to Atlan to save the mapping and push in one action. To pull, save the mapping first, then open the Atlan integration menu and select Pull from Atlan.

In projects with concurrent working enabled, push runs on the main branch and pull runs on a secondary branch.

For the full walkthrough of mappings, push, pull, status, and the run report, see Data Governance Integrations and Atlan Integration on SqlDBM's support site.

See also​