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

# DuckDB destination

> Configure an organization-managed DuckDB artifact as an Available Now destination.

DuckDB is an Available Now destination for lightweight analytical workflows.
The connection uses an organization-managed `.duckdb` artifact identified by
an opaque file reference rather than a host, port, username, password, or
browser-supplied filesystem path.

<Warning>
  The current UI accepts an existing managed `file_...` reference; browser
  upload and download are not provided. Your administrator must provision the
  artifact and its destination tables before a pipeline can write to it.
</Warning>

## Connection fields

| Field                         | Notes                                                                     |
| ----------------------------- | ------------------------------------------------------------------------- |
| Connection Name               | Descriptive workspace name, such as `Analytics DuckDB Output`             |
| Managed DuckDB File Reference | Existing organization-scoped destination reference beginning with `file_` |
| Default Schema                | Destination schema; defaults to `main`                                    |

The destination reference must differ from any DuckDB source reference used
by the same pipeline. MantrixFlow rejects same-artifact source and destination
configurations before dispatch.

## Create the destination connection

1. Open **Connections** and click **+ New Connection**.
2. Set the role to **Destination**.
3. Choose **DuckDB**.
4. Enter a connection name and an existing managed destination reference.
5. Keep **Default Schema** as `main` unless the destination contract specifies another schema.
6. Click **Test Connection**.
7. Save only after the test succeeds.

The app does not accept `/tmp/...`, `../...`, `file://...`, or a SQLAlchemy
connection URL. Only trusted runtime services may materialize an artifact to a
worker-local path.

## Destination behavior

The ELT runtime resolves the opaque reference under a persistent server-owned
artifact root and never falls back to an in-memory database. Public delivery
uses direct DuckDB `ON CONFLICT` Upsert into a pre-existing table with a primary
key. It does not create or alter destination tables and does not add `_dlt_*`
tables or columns.

## Concurrency and version safety

The runtime holds one non-blocking, process-safe writer lease per artifact.
Concurrent writers are rejected, each run checks the expected artifact version,
and a successful delivery atomically advances a sidecar version. Interrupted
version temp files are recoverable without deleting the `.duckdb` artifact.

This is optimistic version tracking for the managed mutable artifact, not an
immutable backup or rollback service.

## Troubleshooting

| Error                                               | Resolution                                                                                       |
| --------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| Invalid DuckDB connection configuration             | Enter an existing managed reference beginning with `file_`.                                      |
| Source and destination must use different artifacts | Choose a distinct destination `file_...` reference.                                              |
| Managed artifact unavailable                        | Confirm the reference exists and belongs to the current organization.                            |
| Destination runtime unavailable                     | Confirm the persistent artifact root is mounted and writable by the ELT service.                 |
| Disk capacity failure                               | Free worker/artifact capacity before retrying; the previous good artifact must remain unchanged. |

See [DuckDB source](/connections/sources/database/duckdb) for read-only source,
discovery, preview, and sync-mode guidance.