Skip to main content
How DataFerry works under the hood.

​
Connections

A connection is your database credentials. DataFerry uses read-only access to query data for exports.
  • You can have multiple connections (e.g., different regions, different customers)
  • One connection is marked as default — used when none is specified
  • Credentials are encrypted at rest
Single-tenant apps: One connection per customer database. Multi-tenant apps: Usually one connection, with data filtered by scope ID.

​
Schema

After connecting, DataFerry scans your database to discover tables and relationships. We read schema metadata only — table data is not accessed during scans. You then configure:
  • Labels — Human-readable names (“Conversations” not “tbl_conv_v2”)
  • Included tables — What users can export
  • Excluded columns — Hide sensitive fields (tokens, internal IDs)
  • Scope column — How we filter data per user or account (multi-tenant only)
Schema config is shared across all connections. Configure once, works everywhere.

​
Tenancy Mode

Multi-tenant: One database, many users. Data is filtered by a scope column. 
users table
├── user_id = 123 → gets their rows
├── user_id = 456 → gets their rows
└── ...
You specify which column identifies the export scope (e.g., user_id, organization_id, account_id). Single-tenant: Each customer has their own database. No filtering needed — the whole database belongs to them.

​
Portal Sessions

A portal session is a secure, time-limited URL where your user can download their data. 
const session = await ferry.createPortalSession({
  scopeId: 'user_123', // the user, organization, or account to export data for
  returnUrl: 'https://yourapp.com/settings',
});

// session.url → https://portal.dataferry.dev/s/abc123
// session.expiresAt → 1 hour from now
The portal shows:
  • What data is included
  • Record counts
  • Download button
Portal sessions are read-only and do not grant API access. After download (or session expiry), the user is redirected to your returnUrl.

​
Exports

When a user clicks “Download my data”, an export job runs:
  1. Queued — Job created, waiting for worker
  2. Processing — Querying database, generating CSVs
  3. Completed — ZIP file ready, download URL available
  4. Failed — Something went wrong (details in dashboard export log)
Exports are:
  • Scoped to the provided scope (multi-tenant) or full database (single-tenant)
  • Packaged as a ZIP of clean CSVs
  • Stored temporarily, then automatically deleted
  • Downloadable via signed URL (24-hour expiry)

​
Portal Branding

The portal can be customized to match your product:
  • Logo — Shown at the top
  • Product name — “Export your data from ”
  • Primary color — Button color (optional)
  • Favicon — Browser tab icon
Configure in Dashboard → Settings → Portal. If no branding is set, the portal uses neutral defaults.

​
API Keys

API keys authenticate your server with DataFerry.
  • Create keys in Dashboard → Settings → API Keys
  • Keys start with sk_live_ (production) or sk_test_ (sandbox)
  • Store them in environment variables, never in code
  • Rotate keys if compromised

​
Webhooks (coming soon)

Webhooks will notify your system when exports complete. Not yet implemented.