# Connections

**TL;DR:** a connection makes an external hub's tracks available in the track
selector without configuring each track by hand. Admin-defined connections go in
the top-level `connections` array; connections a user adds at runtime live in
their session. This guide covers the config format; for in-app behavior see the
[Connections user guide](https://jbrowse.org/jb2-staging/docs/user_guides/connections).

## Where connections live

Connections come from two places, combined in the track selector:

- **`connections`**: a top-level array in your `config.json`, alongside
  `assemblies` and `tracks`. These are administrator-defined and available to
  everyone who loads the config.
- **Session connections**: connections a user adds at runtime. These live in the
  saved session, not the admin config.

Both render identically as categories in the track selector.

## Connection config format

Every connection shares the base fields from [](https://jbrowse.org/jb2-staging/docs/config/baseconnection):

- `type`: the connection type (e.g. `UCSCTrackHubConnection`)
- `connectionId`: a unique id for the connection
- `name`: a human-readable name, shown as the category label
- `assemblyNames`: optional list of assemblies the connection applies to, used
  to match hub tracks to the assemblies configured in your instance

Each type then adds its own location slot.

### UCSC track hub

Points at a hub's `hub.txt`. See [](https://jbrowse.org/jb2-staging/docs/config/ucsctrackhubconnection).

```json
{
  "type": "UCSCTrackHubConnection",
  "connectionId": "ucsc_example",
  "name": "UCSC example hub",
  "hubTxtLocation": {
    "uri": "https://example.com/hub.txt"
  }
}
```

### JB2 track hub

Points at another JBrowse 2 `config.json`, whose `tracks` array becomes the
connection's track list. See [](https://jbrowse.org/jb2-staging/docs/config/jb2trackhubconnection).

```json
{
  "type": "JB2TrackHubConnection",
  "connectionId": "jb2_example",
  "name": "JB2 example hub",
  "configJsonLocation": {
    "uri": "https://example.com/config.json"
  }
}
```

### JBrowse 1 data directory

Points at a legacy JBrowse 1 data directory — the one holding `trackList.json`
and `tracks.conf`, either of which may be absent. Its tracks are translated to
JBrowse 2 equivalents on connect. A JBrowse 1 connection serves one assembly, so
`assemblyNames` is required and holds a single entry. See
[](https://jbrowse.org/jb2-staging/docs/config/jbrowse1connection).

```json
{
  "type": "JBrowse1Connection",
  "connectionId": "jb1_example",
  "name": "JBrowse 1 data",
  "assemblyNames": ["hg19"],
  "dataDirLocation": {
    "uri": "https://example.com/jbrowse1/data/"
  }
}
```

#### Migrating a JBrowse 1 instance

A JBrowse 1 connection is also the shortest path off JBrowse 1, since it leaves
the data files where they are:

```bash
jbrowse add-connection https://mysite.com/jbrowse/data/ -a hg19
```

The connection reads `trackList.json` and `tracks.conf`, follows their
`include`s, and covers the alignment, variant, annotation, quantitative and
sequence stores a JBrowse 1 instance usually holds; the exact set is one table
in
[`jb1ToJb2.ts`](https://github.com/GMOD/jbrowse-components/blob/main/plugins/legacy-jbrowse/src/JBrowse1Connection/jb1ToJb2.ts).
A `storeClass` it does not recognize is matched on the filename instead, and the
few stores with no JBrowse 2 equivalent arrive as placeholder tracks naming the
format.

A connection keeps reading the JBrowse 1 directory, which suits a site running
both. Writing the tracks into `config.json` cuts that tie, and
[this gist](https://gist.github.com/cmdcolin/2ef875fc19c5f164aad41bd330f1bb37)
is a standalone script along the same lines to adapt. Check either result with
`jbrowse validate config.json`.

## Adding a connection with the CLI

```bash
jbrowse add-connection https://example.com/hub.txt \
  --type UCSCTrackHubConnection \
  --name "My Hub"
```

This appends a connection to the target `config.json`. See
[`jbrowse add-connection`](https://jbrowse.org/jb2-staging/docs/cli#jbrowse-add-connection) for all options.

## How connections are stored in a session

<!-- GOTCHA BaseConnection START -->

:::caution Gotcha

A connection config is only a pointer: the hub's track list is fetched when the
connection loads and held in memory, and is **not** written into a saved or
shared session. Only a track you actually open is stored (under
`connectionTrackConfigs`, keyed by `trackId`), which is what keeps a shared
session small even against a very large hub.

:::

<!-- GOTCHA BaseConnection END -->

In the app the list is fetched when the connection's category is expanded. An
opened track reopens on reload without re-fetching the whole hub, and editing it
saves the change to the session.

## See also

- [Connections user guide](https://jbrowse.org/jb2-staging/docs/user_guides/connections)
- [](https://jbrowse.org/jb2-staging/docs/config/baseconnection)
- [Configuring tracks](https://jbrowse.org/jb2-staging/docs/config_guides/tracks)
- [](https://jbrowse.org/jb2-staging/docs/config_guides/track_selector)