Connections and sources

Connections and sources deliberately answer different questions: how can LeapView reach data? and which logical input should the project graph consume? Keeping those answers separate prevents credentials and physical locations from leaking into analytical models.

Connections

A connection describes a physical access method and its defaults. Supported connection kinds are defined by the generated schema and currently include managed data, object storage, HTTP, relational databases, SQLite, and DuckLake.

apiVersion: leapview.dev/v1
kind: Connection
metadata:
  id: connection:olist
  name: olist
  displayName: Olist CSV files
spec:
  type: managed
  defaults:
    csv:
      header: true

Connection options are connector-specific. Put options shared by its sources under defaults; keep per-source format, path, object, or reader options on each source. The generated Connection configuration page lists the accepted top-level fields, while the connector implementation defines the meaning of connector-specific options.

Do not store secret values or physical production endpoints in project YAML. Published projects identify logical connections. Each target owns the corresponding endpoint, connector settings, and credential reference.

Production targets resolve an atomic credential bundle from their configured read-only Infisical backend during candidate preparation. A provider version is prepared and health checked before it can become release evidence; failed versions leave the active serving generation unchanged. Publication pins the validated Infisical secret ID/version, binding revision, connector kind, and endpoint hash. Activation, restart, and rollback resolve that exact provider version. Provider values are never copied into project artifacts, binding persistence, release provenance, or deployment evidence.

Environment-backed credentials remain available only through an explicitly selected development/evaluation resolver. They are useful for a local leapview dev workflow, but production composition rejects that resolver and never falls back to it after an Infisical denial or outage.

For a locally running development target, target-managed connection bundles use dedicated process variables named LEAPVIEW_DEV_CONNECTION_<NAME>. The binding credential reference uses the local target instance ID as its project, the target environment, / as its path, and the variable name as its key. Values are JSON credential bundles such as {"password":"..."}. Only variables with this dedicated prefix are eligible; arbitrary process variables cannot be selected through the binding API. If Infisical is configured on a development target, it remains authoritative and the environment resolver is not used as a fallback.

Object storage is the recommended external-file boundary. LeapView supports these v1 credential modes:

Ambient S3 credentials may declare a non-secret region and endpoint. Ambient Azure credentials require the storage accountName. LeapView compiles these declarations into temporary, path-scoped DuckDB secrets; resolved credentials are not written to deployment artifacts.

The v1 object-storage contract is:

Sources

A source gives one accessible object a stable project identity:

apiVersion: leapview.dev/v1
kind: Source
metadata:
  id: source:olist.orders
  name: olist.orders
  displayName: Orders
spec:
  connection: olist
  location:
    type: path
    path: olist_orders_dataset.csv
    format: csv
  schema:
    mode: compatible
    fields:
      order_id:
        datatype: String
        description: Raw order identifier.

The source identifies a typed path or relation location, format options, and declared schema. Use a name that reflects the governed dataset rather than a temporary filename. Models and project-resource permissions depend on that stable name.

Field declarations document expected input shape and improve validation and discovery. They do not replace defensive transformations: Model SQL should still cast or reject malformed physical values where necessary.

Project dependency and access

A model's governed SQL definition names project sources through the source namespace. The compiler derives the dependency; it does not copy source credentials into the model.

spec:
  definition:
    type: sql
    sql: SELECT * FROM source."olist.orders"

Validation should fail when a Model references an undiscovered source. This keeps repository layout from becoming an accidental authorization mechanism.

Managed and external data

Managed connections participate in the plan, stage, revision, and activation lifecycle. The file content is identified by immutable revision state before deployment activates it. External connectors are direct reads: discovery or refresh observes whatever the configured object path exposes at that time. LeapView does not copy, pin, or version those objects in v1.

Use managed data when LeapView should own the uploaded object revision. Use an external connection when an existing system remains the source of truth and LeapView should read it in place.

For reproducible external refreshes, publish immutable object keys or versioned prefixes and change the source path through a reviewed project deployment. A mutable glob or overwritten key remains the source owner's consistency responsibility. A failed refresh does not replace the last successful serving snapshot.

Change safely

Changing a connection endpoint or source path can affect every dependent project resource. Before deployment:

1. Search the dependency graph for consumers.
2. Validate the whole project.
3. Plan against the target instance.
4. Refresh affected Models in a non-production environment.
5. Compare row counts, null behavior, types, and key uniqueness.

Continue with Connect a data source for an authoring procedure and Managed data ingestion for immutable managed files.