Connect your sources

Point Regixo at your real databases and SaaS. It reads the connection string from an environment variable you name — your secret never touches regixo.yml. This page covers every connector that’s actually built, the exact strings, and how to reach a locked-down database.

Connect one estate, end to end (the worked example)

A fintech with a Postgres app database, Stripe, a Snowflake warehouse, and dbt for lineage. Here is each source through all four steps — and, for each, where the secret lives:

Then regixo sources lists all four, and regixo start scans them into one map. Every estate is that same loop; the rest of the page is the exact steps per connector, then the branches.

Step 1 · List every source you need on the map

Before you connect anything, write the list: each production database (Postgres, MySQL, SQL Server, Redshift), each warehouse (Snowflake, BigQuery), each SaaS that holds people’s data (Stripe today; anything else through a BYOC connector), any dbt project for lineage, and any system you can’t reach live but still need mapped (add it from a CSV of its schema). A source you leave off the list is simply absent from the map — the coverage line reports only the sources you added. The list is what tells you when Step 4 is done.

How connecting works

Each source is one entry in regixo.yml. The entry holds the name of the env var that carries the secret (connectionRef), never the secret itself. At scan time Regixo resolves the value from your environment. Two ways to add a source:

• Auto-detected — if a known env var is set, regixo start offers to add it for you (see Auto-detect).
• By hand — regixo add <type>, a wizard on a terminal or flag-driven when scripted.

Anything the first scan missed — a database behind an env var Regixo doesn’t know, a CSV of a schema you can’t reach, or a dbt manifest for lineage — is added by hand below. File sources (CSV, dbt) are never auto-detected, so they are always a manual regixo add.

Step 2 · Connect each source

Work down your list one source at a time. Every connector is the same two moves: put the secret in .env (the value, and only the value, lives there — never in regixo.yml), then regixo add <type> to register it. Find your source below and follow its exact steps.

SQL databases (Postgres · MySQL · SQL Server · Redshift)

One connector serves four drivers. Each reads a standard connection string from an env var:

Set the env var, then add the source (this example is Postgres):

$ export DATABASE_URL='postgres://readonly:••••@db.internal:5432/app'
$ regixo add postgres --ref DATABASE_URL --label "App DB" --region eu-central-1

✓ added postgres source "app-db" (App DB)
  connection reads from $DATABASE_URL (never stored here)
  ↳ wrote a placeholder to .env (git-ignored, never in regixo.yml):
      DATABASE_URL=postgres://<user>:<PASTE-YOUR-TOKEN-HERE>@<host>:5432/<db>
  next:  regixo test app-db   (check it connects)   ·   regixo start   (scan it in)
  undo:  regixo sources remove app-db

The resulting regixo.yml entry:

version: 1
sources:
  - id: app-db
    kind: sql
    driver: postgres
    label: Application database
    connectionRef: DATABASE_URL     # the env-var NAME, never the secret
    region: eu-central-1            # feeds the "transfers outside the EU" suggestion
    role: controller

Rename a source — the label:

The label: is the human name Regixo shows for a source — you meet it on the Map’s source fold and its per-source trust card, and in regixo sources. The id stays stable (everything keys off it); the label is only the display name, so change it whenever you like — edit regixo.yml, or re-run regixo add … --label "New name". Set it to something a reader recognises (“Billing DB”, not app-db) before you share the map.

Snowflake

Snowflake is reached over the SQL REST API — there's no TCP driver — and it's metadata-only: Regixo reads information_schema for tables, columns and types, never row values. One env var carries the whole connection, with the token as its only secret:

$ export SNOWFLAKE_URL='snowflake://ab12345/ANALYTICS?warehouse=WH_XS&role=REGIXO_RO&token=••••'
$ regixo add snowflake --ref SNOWFLAKE_URL

The token is a Programmatic Access Token by default; for an OAuth token add &token_type=OAUTH. A read-only role with USAGE on the database and warehouse is enough. As with every source, regixo.yml stores only the variable name — the token lives in your environment, never in the file (Hard Rule #6).

BigQuery

BigQuery is a metadata-only REST source: Regixo lists datasets and tables and reads each table's schema (nested RECORD fields are flattened), never row values. The env var holds a bigquery:// URL with your project id and one of two credentials:

$ export BIGQUERY_URL="bigquery://my-project?token=$(gcloud auth print-access-token)"
$ regixo add bigquery --ref BIGQUERY_URL

A short-lived OAuth token (token=) is easiest for a one-off scan; a service-account key file (key_file=) is durable, so it suits a scheduled regixo watch. A key-file path is not a secret, so it may sit in the URL — the token is, so it stays in the env var only, never in regixo.yml.

Stripe

Stripe is metadata-only: Regixo pings /v1/balance to check the key works, then maps a curated object schema (customer, charge, invoice, payment_method, subscription) so the classifier can flag fields like email and card_last4. It never fetches customer objects. Use a test-mode key.

$ export STRIPE_API_KEY='sk_test_••••'
$ regixo add stripe --ref STRIPE_API_KEY

Stripe is added with role: processor by default — it processes on your behalf.

dbt (lineage)

dbt isn’t a data source — it’s a lineage provider. Point Regixo at your compiled manifest.json and the warehouse source its models map onto, and Regixo adds the model-to-model ref graph as lineage. It reads no warehouse rows.

First, produce the manifest. dbt writes target/manifest.json when it compiles. If you don’t have one yet, run dbt compile (or any dbt run/dbt build) in your dbt project — that creates target/manifest.json, the file you point Regixo at below.

$ regixo add dbt --from target/manifest.json --target app-db

Describe a source by hand (CSV)

Can’t reach a system, or want to document one Regixo can’t connect to yet? Describe its schema in a CSV — no live system, no secret. This is the “never a dead end” path.

dataset,column,type,nullable
legacy_crm.contacts,email,varchar,false
legacy_crm.contacts,full_name,varchar,true
legacy_crm.orders,amount,decimal,false

$ regixo add manual --from schema.csv

Bring your own connector (any SaaS or internal API)

Don’t see your tool in the list? For any SaaS, or your organisation’s own internal API, you can stand up a connector with a coding agent. Unlike the CSV above it’s live:

• Re-scanned by regixo start / watch.
• Checkable with regixo test.
• Flags drift when the schema moves.

Open your agent (e.g. Claude Code) in the project and say “add <your tool> to Regixo”; it reads the playbook and wires it up:

$ regixo connectors --skill

The playbook’s core is an interview: a private/internal API has no public docs the model knows, so the agent asks you how it authenticates and what its objects/fields are (or reads an internal OpenAPI spec / a sample response) — then authors the connector. Everything runs out-of-process: Regixo never imports or runs the authored code inside itself. How it works:

A generator script (script) — works for any source

The agent writes a small script in regixo-connectors/ that prints your schema (the same CSV/JSON as above). Regixo runs it as a subprocess each scan and ingests only the printed schema — never row values. Name the token env var after the tool (HUBSPOT_TOKEN), not a generic name.

say

“Write a Regixo connector for our orders API and register it.”

Copy

🔑Your agent fills in everything except the token — you put that in .env yourself.

Show the commandHide the commandShow the sentenceHide the sentence

run

$ regixo connectors new orders-api     # scaffold regixo-connectors/orders-api.mjs
$ regixo add script --generator regixo-connectors/orders-api.mjs --id orders-api --ref ORDERS_API_TOKEN

regixo add — the flags

On a terminal, regixo add with no type opens a picker (Databases · SaaS · Import from a file). Headless, pass the type and flags. It writes config only — the headless path never scans; run regixo start after.

Remove a source

Two built-in ways, depending on whether you want to drop one source or wipe everything. Both are Regixo’s own commands. Neither touches your database — the scan only ever read metadata — and neither deletes your secret.

Remove one source

regixo sources remove <id> is the exact undo of an add: it drops the source from regixo.yml and clears its datasets, personal-data flags and lineage from the map, so the map stays honest. Because that erases mapped data, it asks first — confirm with --yes:

$ regixo sources remove myfintech1 --yes

✓ removed source "myfintech1"
  cleared its datasets from the map
  the map refreshes on the next regixo start

Without --yes it prints what would happen and stops — a scanned source warns that its mapped tables + personal-data flags will be erased; a never-scanned source says it’s safe (nothing is mapped yet).

• Don’t know the id? regixo sources lists them (it works before any scan too).
• Removing your last source is fine — the next regixo start simply offers to connect one again, like a fresh folder.
• To undo a removal, re-add the source and run regixo start; nothing about your database changed.

Start over — wipe everything

To remove every source, the whole map and the draft record in one motion, delete the local folder Regixo wrote in this project:

$ rm -rf .regixo

.regixo/ holds the catalog (index.db), the drafts, and the auto-generated regixo.yml. Deleting it is a clean slate: the next regixo start is a brand-new first run.

Your .env sits outside .regixo/, so it survives — delete it by hand if you want the connection string gone. Same for a regixo.yml you keep at the project root yourself: that one is outside .regixo/ too, so remove it separately.

Auto-detect — and a source the scan missed

On a first run with no regixo.yml, regixo start looks for these env vars and offers to add what it finds: DATABASE_URL, MYSQL_URL, REDSHIFT_URL, SQLSERVER_URL, STRIPE_API_KEY. It also reads the variable names (never the values) from a local .env, so a source shows up even if the value is only exported at runtime. File sources (CSV, dbt) are never auto-detected — add those by hand.

A source didn’t show up on the first run? It is one of two cases, and both fix the same way. Either its secret lives in an env var Regixo doesn’t auto-detect (a non-standard name, or a warehouse like Snowflake/BigQuery) — so add it by hand, regixo add <type> --ref YOUR_ENV_VAR (Step 2) — or it is a file source (CSV, dbt), which is never auto-detected. Nothing was lost; the source was simply never on your list. Add it, then re-run regixo start to fold it into the map.

How secrets are resolved

At scan time Regixo resolves each source’s connectionRef in order:

1. The env var named exactly by connectionRef (e.g. DATABASE_URL).
2. REGIXO_SECRET_<REF> as a fallback.
3. Otherwise a SECRET_UNRESOLVED error naming the variable to set.

Local-only, or paired with the portal

Connecting a source changes nothing about where your catalog lives. By default your install is local-only: it talks to nothing on the internet, and a Refresh just re-scans your sources on this machine — nothing is uploaded. For most people that is the whole product.

Once you forward a draft (regixo invite, or the portal’s hand-off), the install is paired with the hosted portal: a metadata-only snapshot lives there too, and a Refresh can also send an updated snapshot up so the two stay in step. There is an honest in-between — the portal’s copy is only ever as fresh as the last snapshot you sent, so it can lag your local map until you Refresh again; the free portal’s hand-off card tells you when it has changed since. The portal it pairs with is app.regixo.com by default, or whatever you set REGIXO_PORTAL_URL to.

What each Refresh actually sends, and how to keep a paired snapshot current from CI: Keep it current →.

Branch · a database behind a VPN or firewall

A partial scan is fine — an unreachable source is marked and coverage stays honest (“4 of 6 reachable”). When a database sits on a private network Regixo can’t reach from here, there are three real routes, and no --tunnel flag pretends otherwise:

• Bring the key — set up your own VPN or SSH tunnel, then give Regixo a connection string that reaches through it in the normal DATABASE_URL. There is no --tunnel flag — Regixo just needs a reachable host.
• Bring Regixo inside — run regixo start on a machine inside the network and merge the maps.
• Describe it — import a CSV of the schema.

Step 3 · Verify each connection (and fix a source that won’t connect)

Dry-run every connection — this checks credentials and reachability and scans nothing. Run it after each regixo add, and any time a source looks off:

$ regixo test

✓ app-db — connected
✗ stripe — STRIPE_API_KEY in .env still holds the placeholder — no real API key yet
✗ snowflake-dwh — Snowflake rejected the token (401) → fix: regixo doctor
2/3 source(s) failed — see fixes above.

Turn any problem into a fix:

$ regixo doctor

It resolves each env var and actually probes the connection (the same probe as regixo test, so they never disagree), then prints a specific fix.

Full list: Errors & fixes.

Step 4 · Confirm you have them all

List every source and whether Regixo could reach it. Check it against your Step-1 list — nothing on the list should be missing, and nothing reachable should read unreachable:

$ regixo sources

✓ app-db  [sql/postgres]  reachable · last scan 9m ago
✓ dbt  [dbt/dbt]  reachable · last scan 9m ago
✗ snowflake-dwh  [sql/snowflake]  couldn't connect · Regixo does not record when it was last read
✗ stripe  [saas/stripe]  couldn't connect · Regixo does not record when it was last read
  remove one:  regixo sources remove <id> --yes

A source you just added but haven’t scanned reads not scanned yet until the next regixo start — that is expected, not a failure. A ✗ unreachable is the one to act on: run Step 3 to see the reason and the fix.

How you know you’ve connected everything

You are done with this page when all three hold:

• Every source on your Step-1 list appears in regixo sources — reachable ones with a ✓, and any you can’t reach live added deliberately as a CSV.
• regixo test is all ✓ (or the only ✗ is a source you deliberately left as a CSV).
• After a scan, the coverage line reads ✓ all N source(s) reached — never ⚠ … EXCLUDES ….

Then scan them into one map and read it — the next page.