> For the complete documentation index, see [llms.txt](https://docs.elimity.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.elimity.com/import-agents-sql/step-by-step-deployment-guide.md).

# Step-by-step deployment guide

{% hint style="warning" %}
We highly recommend using [our SQL gateway](/gateways-sql/step-by-step-deployment-guide.md) instead of this import agent.
{% endhint %}

## 1. Configuring the agent

To configure your import agent, mount a JSON configuration file at `/app/config/config.hjson` with the properties listed below. Refer to the following attachments for a starting point:

{% tabs %}
{% tab title="Microsoft SQL Server" %}
{% file src="/files/dljSJRopZFpbn7zJDQHY" %}
{% endtab %}

{% tab title="MySQL" %}
{% file src="/files/8WRhPyiJzlmY5KFlWOzn" %}
{% endtab %}

{% tab title="Oracle Database" %}
{% file src="/files/sCmlYn0d9GO71P7kpwMe" %}
{% endtab %}
{% endtabs %}

These example configurations will simply import some dummy data from different databases. Edit the following properties in your file to configure the import agent to your needs:

<table data-full-width="true"><thead><tr><th>Property</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td><code>cronPattern</code></td><td><code>string</code></td><td>Optional CRON pattern describing when the import agent should run (refer to <a href="https://crontab.guru">https://crontab.guru</a> for example patterns); omit if you just want to run the agent once</td></tr><tr><td><code>entityTypes</code></td><td><code>list[object]</code></td><td>Describes how to import entities of a specific type into Elimity Insights</td></tr><tr><td><code>entityTypes[].attributes</code></td><td><code>list[object]</code></td><td>Describes how to import attributes of this entity type's entities</td></tr><tr><td><code>entityTypes[].attributes[].description</code><sup>*</sup></td><td><code>string</code></td><td>Description of the attribute type for which the agent should import assignments</td></tr><tr><td><code>entityTypes[].attributes[].id</code></td><td><code>string</code></td><td>Unique identifier of the attribute type for which the agent should import assignments</td></tr><tr><td><code>entityTypes[].attributes[].name</code><sup>*</sup></td><td><code>string</code></td><td>Human-readable name of the attribute type</td></tr><tr><td><code>entityTypes[].attributes[].type</code></td><td><code>string</code></td><td>Data type of the attribute type, one of <code>"boolean"</code>, <code>"date"</code>, <code>"dateTime"</code>, <code>"number"</code>, <code>"string"</code> or <code>"time"</code></td></tr><tr><td><code>entityTypes[].icon</code><sup>*</sup></td><td><code>string</code></td><td>Icon of the entity type</td></tr><tr><td><code>entityTypes[].id</code></td><td><code>string</code></td><td>Unique identifier of the entity type for which the agent should import entities</td></tr><tr><td><code>entityTypes[].plural</code><sup>*</sup></td><td><code>string</code></td><td>Plural form of the entity type's name</td></tr><tr><td><code>entityTypes[].query</code></td><td><code>string</code></td><td>Query that the import agent should send to the configured SQL instances, each resulting row corresponds to an entity of this type; refer to <a href="/import-agents-sql/query-format.md">our documentation about the query format</a> for additional information</td></tr><tr><td><code>entityTypes[].singular</code><sup>*</sup></td><td><code>string</code></td><td>Singular form of the entity type's name</td></tr><tr><td><code>insightsSourceId</code></td><td><code>number</code></td><td>Elimity Insights source identifier; we'll create one in step 2</td></tr><tr><td><code>insightsSourceToken</code></td><td><code>string</code></td><td>Elimity Insights source token; we'll generate one in step 2</td></tr><tr><td><code>insightsUrl</code></td><td><code>string</code></td><td>URL of your Elimity Insights server</td></tr><tr><td><code>db2Dsns</code><sup>**</sup></td><td><code>list[string]</code></td><td>List of connection strings that the import agent should use to connect with your IBM Db2 instances; we recommend connecting with a dedicated read-only user</td></tr><tr><td><code>mssqlDns</code><sup>**</sup></td><td><code>list[string]</code></td><td>List of connection strings that the import agent should use to connect with your Microsoft SQL Server instances (we use Microsoft's official Go MSSQL driver behind the scenes, refer to <a href="https://github.com/microsoft/go-mssqldb?tab=readme-ov-file#connection-parameters-and-dsn">its documentation on supported connection string formats</a>); we recommend connecting with a dedicated read-only user (e.g. by only assigning the <code>db_datareader</code> role)</td></tr><tr><td><code>mySqlDsns</code><sup>**</sup></td><td><code>list[string]</code></td><td>List of connection strings that the import agent should use to connect with your MySQL instances (we use the de facto standard MySQL driver for Go behind the scenes, refer to <a href="https://github.com/go-sql-driver/mysql?tab=readme-ov-file#dsn-data-source-name">its documentation on supported connection string formats</a>); we recommend connecting with a dedicated read-only user</td></tr><tr><td><code>oracleDsns</code><sup>**</sup></td><td><code>list[string]</code></td><td>List of connection strings that the import agent should use to connect with your Oracle Database instances (we use the de facto standard Oracle Database driver for Go behind the scenes, refer to <a href="https://pkg.go.dev/github.com/sijms/go-ora/v2@v2.8.19/configurations#ParseConfig">the implementation of their connection string parser</a>); we recommend connecting with a dedicated read-only user</td></tr><tr><td><code>relationshipTypes</code></td><td><code>list[object]</code></td><td>Describes how to import relationships between entities of two specific types into Elimity Insights</td></tr><tr><td><code>relationshipTypes[].attributes</code></td><td><code>list[object]</code></td><td>Describes how to import attributes of this relationship type's relationships</td></tr><tr><td><code>relationshipTypes[].attributes[].description</code><sup>*</sup></td><td><code>string</code></td><td>Description of the attribute type for which the agent should import assignments</td></tr><tr><td><code>relationshipTypes[].attributes[].id</code></td><td><code>string</code></td><td>Unique identifier of the attribute type for which the agent should import assignments</td></tr><tr><td><code>relationshipTypes[].attributes[].name</code><sup>*</sup></td><td><code>string</code></td><td>Human-readable name of the attribute type</td></tr><tr><td><code>relationshipTypes[].attributes[].type</code></td><td><code>string</code></td><td>Data type of the attribute type, one of <code>"boolean"</code>, <code>"date"</code>, <code>"dateTime"</code>, <code>"number"</code>, <code>"string"</code> or <code>"time"</code></td></tr><tr><td><code>relationshipTypes[].from</code></td><td><code>string</code></td><td>Unique identifier of the entity type from which the relationships start</td></tr><tr><td><code>relationshipTypes[].query</code></td><td><code>string</code></td><td>Query that the import agent should send to the configured SQL instances, each resulting row corresponds to a relationship between two entities of the configured types; refer to <a href="/import-agents-sql/query-format.md">our documentation about the query format</a> for additional information</td></tr><tr><td><code>relationshipTypes[].to</code></td><td><code>string</code></td><td>Unique identifier of the entity type where the relationships end</td></tr><tr><td><code>transactionIsolationLevel</code></td><td><code>number</code></td><td>Represents which isolation level the agent should use for the transaction in which it combines all queries; refer to <a href="/import-agents-sql/transaction-isolation-levels.md">our documentation about transaction isolation levels</a> for additional information</td></tr></tbody></table>

<sup>\*</sup>These properties do not affect the importing functionality, they are only necessary to generate a data model export file when running the import agent with the `-print-data-model-export` flag.

<sup>\*\*</sup>The import agent processes each connection string independently and simply concatenates the results to form a single domain graph.

## 2. Creating a source in Elimity Insights

The import agent also includes some functionality to help you with creating a source in Elimity Insights. Assuming you correctly configured the agent as explained in the previous step, the following command will write a data model export file to `data-model-export.json`:

```shell-session
$ docker run -v ./config:/app/config --rm europe-west1-docker.pkg.dev/elimity-general/docker/sql-import-agent:<tag> -print-data-model-export > data-model-export.json
```

You can now upload this file to Elimity Insights when creating a new custom source. Copy the resulting source's identifier and token to the `insightsSourceId` and `insightsSourceToken` properties in the agent's configuration file.

## 3. Deploying the agent

Having configured the agent and having created a source in Elimity Insights, you can now deploy the agent to regularly import data from your SQL databases and upload it to Elimity Insights. Since we distribute the agent as a Docker image, our recommendation for deployment is to use a CaaS solution like Google Cloud Run or Azure Container Apps. If that's not an option, you can also manually deploy the image on e.g. Windows Server. Refer to [our documentation about gateways and import agents](/technical-guides/gateways-and-import-agents.md) for additional details.

## 4. Following up on the import

The import agent outputs logs to indicate its progress, for a manual Windows Server deployment you can check these with `docker-compose logs`.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

```
GET https://docs.elimity.com/import-agents-sql/step-by-step-deployment-guide.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.