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	A folder of reference documents in Files
3. Build a knowledge base	A versioned knowledge base built from the documents
4. Build an agent	An agent that uses the model and the knowledge base, answers questions, and posts a weekly report to Slack
5. 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.

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.

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

1. Start the connection

   Open the Connections tab and click Connect source.

2. Choose PostgreSQL

   Under Source type, keep PostgreSQL selected.

3. 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.

4. 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.

5. Save

   Click Save connection. The connection card appears on the Connections tab.

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.
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.

1. 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.

   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.

2. Describe what you want

   In the chat, describe the dataset. The builder discovers the relevant sources and writes model.sql for you.

   Example prompt

   <describe the model: the tables to join, one row per ..., the measures to compute>
   
3. 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.

4. 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.

5. Save the draft

   Click Save draft.

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.

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.

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, Build models and Use data.

Previous: Core concepts

How the building blocks attach to each other.

Next: Upload files

Add the reference documents your knowledge base will use.