# Import SQL rows as workflow records

Use **SQL → derived records ETL** to read rows from a database and retain them as workflow-derived records. The prepared source uses cursor-based batching so it can progress through a result set instead of stopping at one fixed page.

## Configure the source

| Parameter | What to enter |
| --- | --- |
| `workflow_name` | A nonempty workflow name. |
| `dsn` | The approved SQL connection configuration required by this starter. |
| `query` | A nonempty read query returning the fields you need. |
| `cursor_column` | Column used for keyset progression; default `id`. |
| `record_type` | A nonempty type for the retained output rows. |

Handle connection configuration as sensitive data. Avoid pasting credentials into chat, sample rows, or descriptions. Prefer a managed saved connection when adapting this starter for a reusable team process.

## Test the import

1. Choose the template and supply the query and connection configuration.
2. Select a cursor column present in every selected row.
3. Create the workflow and inspect `extract → persist`.
4. Validate the query-related settings and record type.
5. Start a Manual run against a small, controlled dataset.
6. Compare source rows with retained output and inspect the last page.

The read connector uses `mode: read` and a 500-record chunk size. Batching is enabled with chunk size 500 and a checkpoint after each chunk. The destination writes records using the selected `record_type`.

## Choose a reliable cursor

Keyset progression needs a stable ordering key. Prefer a non-null, suitably unique field whose ordering does not change during the run. A cursor with duplicate or changing values can make a paging strategy miss or repeat records unless the provider explicitly supports that situation.

Keep the cursor column in the query result and check its type. A valid SELECT statement can still be unsuitable for paginated extraction if it hides or destabilizes the progression key.

## Check repeated and partial runs

Destination keys include the run and record sequence. These support controlled repeated attempts but do not make a separate new run update one universal row per source primary key. Adapt the identity strategy when you need that business behavior.

Checkpoints help resume completed extraction chunks; they do not make the entire import one cross-service transaction. Earlier retained records can remain after a later failure. Check counts and partial output before retrying.

See [Read via connector](/docs/steps/connector-read), [batching](/docs/workflows/batching-and-concurrency), and [data-source identity](/docs/workflows/data-sources).

## Prepared job settings

The starter is enabled and uses a Manual trigger. These settings are supplied by the recipe; review them in the editor before adapting the process. `${…}` values below refer to the corresponding template parameter or run variable.

| Setting | Prepared value |
| --- | --- |
| `extract.config.connector` | `"sql"` |
| `extract.config.config.dsn` | `"${dsn}"` |
| `extract.config.config.mode` | `"read"` |
| `extract.config.config.query` | `"${query}"` |
| `extract.config.config.cursor_column` | `"${cursor_column}"` |
| `extract.config.config.chunk_size` | `500` |
| `extract.batch.enabled` | `true` |
| `extract.batch.chunk_size` | `500` |
| `extract.batch.checkpoint_every` | `1` |
| `persist.config.record_type` | `"${record_type}"` |
| `persist.config.idempotency_key_template` | `"sql-etl:${run_id}:${record_seq}"` |