Docs/Getting Started

Connect your data

Hermes connects to your existing systems read-only — SQL databases, Firestore, PostHog, Stripe, or a CSV upload. It inspects your schema to understand your data model. It never writes to your data.

Hermes supports seven data source types. Every one of them is read-only — SQL queries run in read-only transactions and must be single SELECT statements, API sources use read-scoped keys, and all credentials are encrypted with AES-256 the moment you add them. An organization can hold multiple connections, and each trigger points at one of them.

Source	Query language	Typical use
PostgreSQL	SQL	Your production app database.
MySQL	SQL	Your production app database.
SQL Server / Azure SQL	T-SQL	Your production app database.
Firestore	Structured query	Firebase-backed products.
PostHog	HogQL	Behavioral events and product analytics.
Stripe	Structured query	Customers, subscriptions, invoices, payments.
CSV upload	SQL	One-off lists, exports from other tools.

SQL databases

Create a read-only user

Create a dedicated user with read-only access. This ensures Hermes can never modify your data.

psql

CREATE USER hermes_readonly WITH PASSWORD 'your-password';
GRANT CONNECT ON DATABASE your_db TO hermes_readonly;
GRANT USAGE ON SCHEMA public TO hermes_readonly;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO hermes_readonly;

Allow Hermes to connect

If your database is publicly accessible, no additional setup is needed. If your database restricts inbound connections by IP, allowlist the following address:

76.76.21.21

This applies to RDS security groups, Supabase network restrictions, Azure SQL firewall rules, and any firewall on self-hosted databases.

Find your connection string

Any standard connection string works. Here is where to find it for common providers:

Find your connection string under Project Settings → Database → Connection string. Use the URI format and select Transaction mode if you are on a shared plan.

postgresql://postgres.[project-ref]:[password]@aws-0-[region].pooler.supabase.com:6543/postgres

Add it to Hermes

Go to Settings → Connections in the Hermes dashboard and click Add connection. Paste your connection string — it is encrypted immediately with AES-256. Hermes then runs a schema analysis in the background and builds a snapshot of your data model.

Firestore

Connect with a Google service account that has read-only access (the datastore.viewer role is enough). Paste the service-account JSON when creating the connection — it's encrypted at rest like every other credential.

Because Firestore has no fixed schema, Hermes samples documents from each collection to infer one: field names, types, and how consistently each field appears. Triggers against Firestore use a structured query (collection, filters, ordering, limit) instead of SQL, and Hermes caps reads per query and per run so a scan can never blow up your Firestore bill.

PostHog

Connect with your PostHog host, project ID, and a personal API key with query-read access. Hermes captures your event landscape — which events exist and how often they fire — and triggers query the events table directly in HogQL:

Example: HogQL detection query

SELECT distinct_id AS id, properties.email AS email
FROM events
WHERE event = 'checkout_started'
  AND timestamp > now() - INTERVAL 3 DAY

This is the easiest way to trigger on behavior — rage clicks, abandoned flows, feature adoption — without touching your production database.

Stripe

Connect with a restricted API key (rk_...) that has read access to the resources you care about. Hermes can query customers, subscriptions, charges, invoices, payment intents, products, and prices through a structured query — filters, search, and field selection, no code.

Billing states make excellent triggers: trials ending, failed payments, subscription downgrades, customers approaching renewal.

CSV upload

Upload a CSV from Settings → Connections and Hermes ingests it into a managed, isolated table you can query with regular SQL — the same as any database connection. Column types are inferred from the data. Useful for one-off lists, exports from a CRM, or data that doesn't live anywhere queryable yet.

What Hermes reads

Data	Why
Table and column names	Schema structure only — names and types, not values.
Foreign key relationships	How your tables connect, so Hermes understands your data model.
Row counts	Rough table sizes to optimize query generation.
User-specific row data	When sending an email, Hermes reads data for that specific user so it can reference their actual activity, behavior, and context in the email.

The schema snapshot is taken when you connect and can be refreshed anytime from the connection's settings (or via hermes connections inspect-schema in the CLI) — Hermes doesn't rediscover your schema on every run.