Atlan Integration
This article covers what is specific to Atlan. How connections, mappings, Push, Pull, Status and the run report work is described in Data Governance Integrations — read that first.
What you need from Atlan
| Requirement | Where to set it |
|---|---|
| The Atlan add-on enabled for your account | Contact your account manager |
| An Atlan OAuth client (client id and client secret) | Atlan, by an Atlan admin |
| A persona granting the client metadata read and custom-metadata update on your connections, linked to the client | Atlan, by an Atlan admin |
| The custom metadata attributes you want to populate already exist in Atlan | Your Atlan tenant |
Your Atlan tenant address (https://<tenant>.atlan.com) |
Your Atlan tenant |
Use an OAuth client created for SqlDBM, not a person's token. SqlDBM never stores an Atlan user's password.
Preparing Atlan
These steps are done in Atlan by an Atlan admin.
1. Create an OAuth client. Create an API token / OAuth client for SqlDBM and record the client id and the client secret. The secret is shown once.
2. Create a persona and grant it two permissions over the connections SqlDBM should read and write:
- Read metadata — assets, custom metadata definitions and values.
- Update custom metadata values.
3. Link the persona to the OAuth client, so the client inherits its visibility. A client with no persona sees no connections, and SqlDBM's connection check reports exactly that: The Atlan OAuth client sees no connections — either none exist yet, or no persona granting metadata read and custom-metadata update is linked to the client.
4. Check your custom metadata sets. SqlDBM reads and writes values on existing sets. If you want SqlDBM to keep a set's attributes available on the connections it pushes to, mark the set as SqlDBM-owned:
- set its display name to SqlDBM;
- include the marker
[managed-by:sqldbm]in its description.
Only a set marked this way is ever changed by SqlDBM — to add a connection to an attribute's scope, or an option to a dropdown. Sets that belong to other tools are never modified. If an attribute in another tool's set is not scoped to your connection, pushes to it still write the values, and the run report notes that the scope could not be updated.
5. Network. If your tenant sits behind an egress allowlist, allow SqlDBM's requests to your tenant host over HTTPS. Every request carries the header x-atlan-agent-id: sqldbm for your audit log.
Connecting
On the Atlan card at Dashboard → Integrations → Data Governance, the connection form asks for:
- Client ID
- Client secret
- The https address of your Atlan tenant
Mapping container: Connection and Database
An Atlan mapping targets a Database inside a Connection.
On the mapping's Settings tab, select a Connection — the list is the connections your OAuth client can see — then a Database.
An Atlan mapping covers a whole database. All of its schemas, tables, views and columns are matched inside the mapping. A project that spans several schemas of one database needs one mapping, not one per schema. Schemas are matched as objects on the Objects tab, not chosen as the container.
Attributes
The Atlan column of the Attribute mapping tab offers the custom metadata attributes that Atlan allows on tables and columns of the selected connection. Attributes are listed as Set name.Attribute name (for example SqlDBM.Sensitivity).
Types have to match:
| SqlDBM field | Atlan attribute |
|---|---|
| Text | Text (string); also number and date attributes — the value is sent as text and converted |
| URL | URL, or text |
| Checkbox | Boolean |
| Dropdown | Single-select option (an attribute backed by an enum) |
| Multiselect | Multi-select option |
Two things to know about attributes:
- Attributes from other tools' sets can appear in the list when their set does not restrict the connections it applies to. Atlan reports them as applicable, so SqlDBM offers them. Map only the ones your governance team owns.
- Dropdown options are added only on SqlDBM-owned sets. When you push a dropdown value the attribute does not offer yet, SqlDBM adds it to the option list if the set is SqlDBM-owned. On a set owned by another tool the value is skipped and the report reads "Value" in Field has no matching option in Atlan — add the option in Atlan and push again.
Push to Atlan
A push writes each object's mapped values as custom metadata on its Atlan asset, merging with what is already there. Empty Text and URL fields clear the attribute in Atlan; an unchecked checkbox and an empty dropdown are sent as no value.
Pushes above 400 objects run in the background in batches. The Status popup shows the run in progress; you can keep working.
Pull from Atlan
A pull reads the whole database in one pass. Assets deleted in Atlan since the last discovery appear in the run report as not returned, and their values in SqlDBM are left untouched.
Limits and behaviour
| Topic | Behaviour |
|---|---|
| Request rate | SqlDBM paces its calls to your tenant (about 180 per minute across an operation) and backs off on Atlan's rate-limit responses. A large database push or pull takes minutes, not seconds. |
| Push size | Up to 400 objects per request; larger pushes run in the background in batches. |
| Database size | A database walk reads schemas, tables and columns in pages of 1000. Very large databases can exceed the pull ceiling; the message names the database and asks you to reduce scope or contact support. |
| Number values | Sent as text and converted. A value that is not a valid number for the attribute is skipped with value not convertible. Dates are epoch milliseconds. |
| Special characters | Angle brackets and ampersands in text are escaped on the wire; they arrive intact in Atlan. |
| Attribute scope | On SqlDBM-owned sets, SqlDBM adds your connection to an attribute's scope on first push; Atlan takes 30 to 60 seconds to show it. On other sets the values land, but the report notes the scope was not updated. |
| Connections and custom metadata | SqlDBM never creates connections, custom metadata sets or attributes. |
Troubleshooting
| You see | It means | What to do |
|---|---|---|
| The Atlan credentials were rejected. | Wrong client id or secret, or the client was deleted | Re-enter the credentials via Manage → Edit connection |
| The Atlan credentials lack the permissions this probe needs. | The persona does not grant metadata read or custom-metadata update | Fix the persona in Atlan |
| The Atlan OAuth client sees no connections — either none exist yet, or no persona … is linked to the client. | No persona linked, or an empty tenant | Link the persona; confirm the tenant has connections |
| Atlan could not be reached. | Wrong address, network egress blocked, or Atlan down | Check the address and allowlist |
| Atlan mappings now use a database as the mapping container. This mapping points to schema 'X' — delete it and create a new mapping for the database that contains it. | A mapping saved before the database-level change | Delete the mapping and create it again on the database |
| This mapping holds more values than one push to the external system can carry, so nothing was sent. | The push cannot run in one request and the background path is not available in this environment | Push fewer objects or fields at a time |
| Some mapped objects no longer exist in the external system. Re-map them and push again. | Assets were deleted or re-crawled in Atlan, so their ids changed | Refresh and re-map on the Objects tab |
| Another project is pushing to the external container 'X'. / A preview of the external container 'X' is running | Another push or pull is using the same database | Wait for it to finish |
| Atlan is busy with another operation on this container. | Same as above, from the pull side | Try again in a moment |
| Values pushed, but not visible on the asset page in Atlan | The attribute is not scoped to your connection (set owned by another tool) | Ask your Atlan admin to add the connection to the attribute's applicable connections |