> ## Documentation Index
> Fetch the complete documentation index at: https://datagen.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# 1. Connect data

> Connect a database, choose its tables, and publish an analytic model that agents and apps can read

This tutorial follows one storyline from start to finish. You connect a database, add documents, build a knowledge base from the documents, put an agent to work on the data and the knowledge base, and share a dashboard with your team. Each part builds on the one before.

| Part | You build |
| - | - |
| **1. Connect data** (this page) | A database connection and a published analytic model |
| [2. Upload files](/tutorial/02-upload-files) | A folder of reference documents in Files |
| [3. Build a knowledge base](/tutorial/03-build-context) | A versioned knowledge base built from the documents |
| [4. Build an agent](/tutorial/04-build-agent) | An agent that uses the model and the knowledge base, answers questions, and posts a weekly report to Slack |
| [5. Ship an app](/tutorial/05-ship-an-app) | A marimo dashboard, shared with your team |

In this part you connect a PostgreSQL database, choose the tables to make available, and publish an **analytic model** -- a reusable, versioned dataset that agents and apps read.

## Before you start

* A DataGen workspace where you have the **Builder** or **Admin** role.
* Connection details for a PostgreSQL database, ideally a read-only role. 

<Note>
  DataGen reads sources through a database role you provide. Use a role that can only `SELECT` the tables you plan to use: queries see everything that role can read. Your administrator must also allow the database host on the analytics worker.
</Note>

## 1. Open Data

Click **More** on the left navigation rail, then **Data**. To keep Data on the rail, pin it from the same menu.

The Data page has three tabs: **Datasets**, **Connections** and **Settings**.

## 2. Add a connection

<Steps>
  <Step title="Start the connection">
    Open the **Connections** tab and click **Connect source**.
  </Step>

  <Step title="Choose PostgreSQL">
    Under **Source type**, keep **PostgreSQL** selected.
  </Step>

  <Step title="Fill in the form">
    | Field | Value |
    | - | - |
    | Connection name | A name your team will recognize. |
    | SQL alias | Lowercase letters, digits and underscores. This is how SQL refers to the connection, and it stays fixed if you rename the connection. |
    | Host | |
    | Port | `5432` unless your database uses another port |
    | Database | |
    | Username / Password | The read-only role. |
    | Schemas (comma-separated) | `public`, or the schemas that hold your tables. |
  </Step>

  <Step title="Choose a TLS mode">
    Under **TLS**, keep **Verify certificate and hostname** for a managed or public database. The other modes are for private networks and local development.
  </Step>

  <Step title="Save">
    Click **Save connection**. The connection card appears on the **Connections** tab.
  </Step>
</Steps>

## 3. Choose tables

A connection makes no tables available until you choose them.

1. On the connection card, click **Manage tables**.
2. Search or filter by schema, then select the tables you need.&#x20;
3. Click **Save table selection**.

Each selected table becomes a **source** in the **Datasets** tab. Open one to preview up to 500 rows.

## 4. Build an analytic model

A source is raw. An analytic model holds your logic -- joins, filters, business rules -- and its published snapshot is what agents and apps read.

<Steps>
  <Step title="Create the model">
    Open the **Datasets** tab, go to **Analytic models** and click **New analytic dataset**. Give it a name, keep **Mode** set to **Analytic SQL**, and click **Create analytic dataset**.&#x20;

    The **Data Builder** opens: chats and settings on the left, the AI chat in the middle, and the SQL, results, schema and guide on the right.
  </Step>

  <Step title="Describe what you want">
    In the chat, describe the dataset. The builder discovers the relevant sources and writes `model.sql` for you.

    ```text Example prompt theme={null}
    <describe the model: the tables to join, one row per ..., the measures to compute>
    ```
  </Step>

  <Step title="Check the results">
    Open the **Results** tab and click **Execute SQL** to preview the output. Ask the builder for changes until the rows look right.&#x20;
  </Step>

  <Step title="Document it">
    Ask the builder to write the guide (`model.md`), or write it on the **Guide** tab: the grain, keys, measures and caveats. Agents read this guide when they look up the model. Add column descriptions on the **Schema** tab.
  </Step>

  <Step title="Save the draft">
    Click **Save draft**.
  </Step>
</Steps>

## 5. Publish the model

1. In **Setup**, confirm the model is **Materialized** (the default for a new model). Agents can connect only materialized models.
2. Click **Publish dataset**, review the publication, and click **Publish dataset** again.

The model now has a published version **v1**. The **Versions** tab lists every published version, and you can roll back to any of them.

<Tip>
  To keep the model fresh, open **Setup** and click **Open automations**, then **New automation**. A scheduled refresh reruns the published SQL; it never changes the SQL or publishes a new version.
</Tip>

## What you built

* A PostgreSQL connection with selected tables as sources.
* A published, materialized analytic model with a guide that agents can read.

Learn more in [Connect a source](/data/connect), [Build models](/data/build-models) and [Use data](/data/use).

<CardGroup cols={2}>
  <Card title="Previous: Core concepts" icon="arrow-left" href="/overview/core-concepts">
    How the building blocks attach to each other.
  </Card>

  <Card title="Next: Upload files" icon="arrow-right" href="/tutorial/02-upload-files">
    Add the reference documents your knowledge base will use.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.