# Setup

`sqldash setup` connects a project to your warehouse. Run it inside the repo that should
hold the dashboards. It writes the connection details into `.sqldash/metrics.yaml`, which
you commit, and your credentials into a profile at `~/.config/sqldash/profiles.yaml`,
which stays on your machine with `chmod 600`. Then it tests the connection.

<div class="steps">

### Run it in the project

```bash
cd ~/work/analytics
sqldash setup
```

In a terminal it is an interactive wizard that asks which warehouse you use and the
details it needs.

### Or pass every answer as a flag

Scripts, CI, and coding agents can skip the questions.

```bash
sqldash setup --type snowflake \
  --account acme-prod --warehouse WH --database ANALYTICS \
  --username analyst@acme.com --auth externalbrowser
```

`--type` takes `duckdb`, `postgres`, `snowflake`, `bigquery`, `databricks`, `mysql`,
or `url` (any SQLAlchemy URL). Snowflake `--auth` takes `externalbrowser`,
`password`, `pat`, or `keypair`. `--password-env` and `--token-env` name the
environment variable a secret is read from, `--profile` names the profile,
`--skip-test` skips the connection probe, and `--register` also adds the project to
the repos you [serve together](/docs/workspaces/).

### Check the connection

```bash
sqldash source test
```

It connects to each source and reports how long it took.

</div>

## Keeping credentials out of the repo

Tracked YAML never holds a secret, and two mechanisms keep it that way.

- **Environment references.** Any source field can say `${env:SNOWFLAKE_PASSWORD}`,
  and the value is read from the environment at connect time.
- **Profiles.** A source can say `profile: acme-prod`, and the matching entry in
  `~/.config/sqldash/profiles.yaml` is merged in. Like AWS named profiles, the repo
  names the profile and each teammate defines it locally with their own credentials.

```yaml
# in the dashboard
source:
  type: snowflake
  account: acme-prod
  profile: acme-prod
```

```yaml
# in ~/.config/sqldash/profiles.yaml, per teammate, not committed
acme-prod:
  username: analyst@acme.com
  authentication: externalbrowser
```

Secrets resolve in memory at connect time and are never written back. Everything that
leaves the process, including `source list`, the served UI, MCP, `export context`, and
error messages, prints passwords, tokens, and connection options as `•••`. And
`sqldash lint` warns about a plaintext secret in a tracked file, which
`sqldash lint --strict` in CI turns into a failed pull request.