How the reports read your data. Nine connectors in three groups, and the keys each one needs in app/.env.
A connector is how the reports read your data. Silvi has nine, in three groups. Your app has the ones you picked in Create (see Quickstart); adding or removing one later is one request to Claude.
| Group | Connector | Reads |
|---|---|---|
| Data files | excel |
.xlsx files in app/data/excel/, a table per sheet |
| Data files | csv |
.csv files in app/data/csv/, a table per file |
| Data files | json |
.json files in app/data/json/, a table per file |
| Local database | sqlite |
A SQLite database file, read-only |
| Hosted database | sqlserver |
Microsoft SQL Server |
| Hosted database | postgres |
Postgres |
| Hosted database | mysql |
MySQL |
| Hosted database | bigquery |
Google BigQuery |
| Hosted database | redshift |
Amazon Redshift, with a verified TLS connection |
Setting one up#
The keys go in app/.env, the app’s private settings file. It stays on your computer and is never saved to git. Tell Claude where your data is:
“Connect my Postgres database. Open app/.env for me and I will paste the connection string in myself.”
Claude creates app/.env from app/.env.example if it is not there yet, shows you which lines to fill in, and checks the result. You can give Claude the values in the chat, but you do not have to: pasting secrets into the file yourself keeps them out of the conversation.
The app starts without any keys. A report whose connector is not set up shows Not connected and names the keys to set. It runs nothing until they are there.
The reports only read, and the app refuses any SQL that writes. Even so, give the app a database user that can only read the tables your reports need.
Data files#
The data-file connectors load the files in a folder of app/data/ into a small SQLite database in memory. Each file is a table named after it: orders.csv is orders. Names and headers are made lowercase, with anything but letters, digits and _ turned into _: the header Order Date is the column order_date. A column of only numbers is numbers. When a file changes, the next report you open reads it again. Their SQL is SQLite’s.
Each brings sample files, copied in only where the app has no file of that name: csv the example reports’ events.csv, members.csv and website_visits.csv; excel sales.xlsx, whose sheet Regions is the table sales_regions; json sales.json. The last two hold four regions with their sales and orders.
Excel files#
Drop .xlsx files in app/data/excel/. Every sheet is a table named <file>_<sheet>: the sheet Regions of sales.xlsx is sales_regions. A sheet’s first row is its header; a formula reads as its last value.
| Key | What it is | Default |
|---|---|---|
EXCEL_DIR |
The folder, from app/ |
data/excel |
CSV files#
Drop .csv files in app/data/csv/. The first line is the header; commas, semicolons and tabs all work. It needs no setup at all. The three example reports (Events, Members and Website visitors) read their sample files from it, and each names csv itself, so they work as soon as the app starts, whichever connector is the app’s default.
| Key | What it is | Default |
|---|---|---|
CSV_DIR |
The folder, from app/ |
data/csv |
JSON files#
Drop .json files in app/data/json/. A file is a list of objects, or an object with that list under "rows". The columns are every key any object has.
| Key | What it is | Default |
|---|---|---|
JSON_DIR |
The folder, from app/ |
data/json |
Local database#
SQLite#
A SQLite database file on your computer, opened read-only.
| Key | What it is | Default |
|---|---|---|
SQLITE_PATH |
The database file, from app/ |
data/app.sqlite |
Hosted database#
SQL Server#
| Key | What it is | Default |
|---|---|---|
SQLSERVER_HOST |
The server’s address | |
SQLSERVER_PORT |
The port | 1433 |
SQLSERVER_DB |
The database name | |
SQLSERVER_USER |
Your database user | |
SQLSERVER_PASSWORD |
Its password | |
SQLSERVER_ENCRYPT |
Whether the connection is encrypted | true |
Postgres#
Postgres and MySQL take a connection string: one line holding the kind of database, the user and password, the server’s address, the port and the database name.
| Key | What it is |
|---|---|
POSTGRES_URL |
The connection string, postgres://user:password@host:5432/database |
MySQL#
| Key | What it is |
|---|---|
MYSQL_URL |
The connection string, mysql://user:password@host:3306/database |
BigQuery#
BigQuery signs in with a service account: a Google Cloud user made for a program rather than a person, with a key file (a .json file) that lets the app sign in as it. Ask whoever runs your Google Cloud project for one with read access to BigQuery, save the key file on your computer, and give Claude its path.
| Key | What it is | Default |
|---|---|---|
BIGQUERY_PROJECT |
The Google Cloud project the queries run (and are billed) in | |
GOOGLE_APPLICATION_CREDENTIALS |
The path to the service account key file | |
BIGQUERY_LOCATION |
The region your data is kept in, such as EU or US |
none |
Redshift#
The connection is encrypted and the server’s certificate is checked.
| Key | What it is | Default |
|---|---|---|
REDSHIFT_HOST |
The cluster’s endpoint, without the port | |
REDSHIFT_PORT |
The port | 5439 |
REDSHIFT_DB |
The database name | |
REDSHIFT_USER |
Your database user | |
REDSHIFT_PASSWORD |
Its password |
More than one#
The app’s default connector is the first one picked: in Create, the first one ticked, top to bottom; on the command line, the first after --connectors. It is written as SILVI_CONNECTOR in app/.env. With Create’s defaults, Excel and CSV files, it is excel.
A report reads the connector its meta names (connector: "redshift"); one that names none reads SILVI_CONNECTOR, else the only connector installed, else csv. A report reads one connector; two reports can read two databases.
“Make Redshift the default, and have the Orders report read Postgres.”
Adding and removing#
Each connector is a folder of app/src/connectors/: a connector.json (its id, label, group, packages and keys) and the code. The app finds them by their folders, so adding or removing one is adding or removing a folder.
“Add the SQL Server connector.”
Claude runs silvi add sqlserver: it copies the folder, adds its packages, and adds its keys to app/.env.example. silvi remove deletes the folder, unless you changed a file in it, and lists the reports that still name it. See CLI.
One shape of rows#
Every connector returns rows the same way: numbers as numbers, dates as YYYY-MM-DD text, timestamps as YYYY-MM-DD HH:MM:SS. Queries are read-only and cached for ten minutes. So a component reads a report the same way on every database.