Everything you need
to ship with QueryFlow.

What QueryFlow is

QueryFlow is a Mac app that does three things in one window:

1. Runs SQL queries against your databases
2. Lets you transform the results with Python or visual tools
3. Sends the output anywhere you want — a file, an email, S3, SFTP, another database — automatically, on a schedule

If you've been using one tool to write queries, another to clean the data, and a third to deliver the output, QueryFlow replaces all three.

Installing QueryFlow

1. Open the Mac App Store on your Mac.
2. Search for QueryFlow.
3. Click Get, then Install.
4. When the install finishes, click Open — or find QueryFlow in your Applications folder.

QueryFlow requires macOS 15 (Sequoia) or later.

Starting your free trial

Your first 14 days are free. No card up front, no asking permission.

1. Launch QueryFlow.
2. The trial starts automatically — the paywall shows 14 DAYS FREE at the top.
3. Use everything. Connect databases, run queries, build pipelines, schedule jobs.
4. On day 14, the paywall returns. Pick Monthly ($49.99/mo) or Annual ($299.99/yr).
5. Subscriptions are billed through the Mac App Store. Cancel anytime in System Settings → Apple ID → Subscriptions.

The main window — what you're looking at

When you launch QueryFlow you'll see:

• Left sidebar (narrow): icon strip with five tabs — Connections, Destinations, Pipelines, Schedules, Search.
• Left sidebar (wider, contextual): the contents of whichever tab is active. For example, if you're on Connections, this lists your databases.
• Center: the workspace. SQL editor on top, results table on the bottom, Claude chat panel on the right (toggleable).
• Toolbar across the top: Save, Run, Format, Explain, Schedule, Claude toggle, connection picker.
• Bottom (toggleable): the Logs panel showing recent query executions.

Adding a database — general steps

Before you can query anything, you need to add a connection. QueryFlow supports seven types of sources.

1. Click the Connections icon (cylinder) in the narrow left sidebar.
2. Click the + Add button at the top of the Connections list.
3. Pick your database type from the grid (Snowflake, Redshift, Postgres, MySQL, Google Sheets, Salesforce, or Spreadsheet).
4. Fill in the connection fields (covered below for each type).
5. Click Test Connection. Wait for the green check.
6. Click Save.

The new connection appears in your sidebar with a status dot — green when reachable, gray when offline.

Snowflake — connecting with a PAT

Snowflake is the most powerful connector in QueryFlow. The cleanest way to connect is with a Programmatic Access Token (PAT). A PAT is a long string that authenticates your user without your password.

Step 1 — Create a PAT in Snowsight

1. Sign in to Snowsight (app.snowflake.com).
2. Click your username in the bottom-left → My profile.
3. Scroll to Programmatic access tokens → click + Generate new token.
4. Name it something memorable like QUERYFLOW_PAT.
5. Set Expires in to 90 days (or longer if your org allows).
6. Set Role restriction to a role with the permissions you need — ACCOUNTADMIN for full access, or a more limited role for read-only.
7. Click Generate.
8. Copy the token immediately. Snowflake only shows it once.

Step 2 — Find your account identifier

1. In Snowsight, click your username (bottom-left) → hover over Account.
2. The string under your account name (something like gyjruxr-kp48838 or gu23443.us-east-1) is your account identifier.
3. Copy it.

Step 3 — Add the connection in QueryFlow

1. In QueryFlow, click Connections → + Add → Snowflake.
2. Name: anything you want, like Snowflake Prod.
3. Account: paste your account identifier from Step 2.
4. Username: your Snowflake username (the one you log into Snowsight with).
5. Password / PAT: paste the PAT you copied in Step 1.
6. Warehouse: the name of a warehouse you have access to (e.g. COMPUTE_WH). This is required.
7. Database: the database you want to query (e.g. ANALYTICS_PROD). This is required.
8. Schema: optional default schema (e.g. PUBLIC).
9. Click Test Connection. You should see a green Connected confirmation.
10. Click Save.

Snowflake errors you might see

• "Database does not exist or not authorized" — the database name in your connection doesn't exist on the account, or your PAT's role doesn't have USAGE on it. Sign into Snowsight, run SHOW DATABASES, confirm it's there, and grant USAGE if needed.
• "Warehouse is required" — you left the warehouse field blank. Edit the connection and add one.
• HTTP 401 or "authentication failed" — your PAT is expired or wrong. Generate a new one.

Amazon Redshift — connecting with the Redshift Data API

QueryFlow uses the Redshift Data API (not direct TCP), so you don't need to manage VPC tunnels or whitelist IPs. You authenticate with AWS credentials.

Step 1 — Create an IAM user

1. Sign in to the AWS Console → IAM.
2. Click Users → Create user.
3. Give the user a name like queryflow-user.
4. Attach the policy AmazonRedshiftDataFullAccess (or a narrower custom policy).
5. After creation, go to Security credentials → Create access key.
6. Select Application running outside AWS → Next → Create.
7. Copy the Access Key ID and Secret Access Key. AWS only shows the secret once.

Step 2 — Add the connection in QueryFlow

1. Click Connections → + Add → Redshift.
2. Name: like Redshift Analytics.
3. Cluster Identifier: the name of your Redshift cluster (e.g. prod-analytics-cluster).
4. Database: the Redshift database name (e.g. dev).
5. Database User: the database username (e.g. awsuser).
6. Region: your cluster's AWS region (e.g. us-east-1).
7. AWS Access Key ID: paste from Step 1.
8. AWS Secret Access Key: paste from Step 1.
9. Click Test Connection → wait for green.
10. Click Save.

PostgreSQL — direct connection

1. Click Connections → + Add → PostgreSQL.
2. Name: like Postgres Local.
3. Host: the server address (e.g. localhost, db.example.com, or an IP).
4. Port: usually 5432.
5. Database: the database name.
6. Username and Password.
7. SSL Mode: choose require for production servers, disable for local.
8. Click Test Connection → Save.

MySQL — direct connection

Same steps as Postgres, with port 3306 by default.

1. Click Connections → + Add → MySQL.
2. Fill in Host, Port, Database, Username, Password.
3. Test Connection → Save.

Google Sheets — connecting with OAuth

QueryFlow can read from and write to Google Sheets. You authenticate once with Google, and QueryFlow remembers you.

1. Click Connections → + Add → Google Sheets.
2. Name: like Marketing Sheet.
3. Click Sign in with Google.
4. Your browser opens. Sign in with the Google account that owns or has access to the sheet.
5. Grant QueryFlow permission to access your Sheets.
6. The browser redirects back to QueryFlow.
7. Spreadsheet URL: paste the full URL of your sheet.
8. Worksheet name: the name of the tab inside the sheet (e.g. Sheet1, Leads).
9. Header row: usually 1 — the row that contains your column names.
10. Test Connection → Save.

Salesforce — connecting via OAuth

Salesforce uses an OAuth flow through an External Client App. The first time can be fiddly, but you only do it once per org.

Step 1 — Create an External Client App in Salesforce

1. In Salesforce, click the gear icon (top right) → Setup.
2. In the left sidebar search, type App Manager → click it.
3. Click New External Client App (top right).
4. External Client App Name: QueryFlow.
5. Contact Email: your email.
6. Distribution State: Local.
7. Click Create.
8. On the next screen, click API (Enable OAuth Settings).
9. Check Enable OAuth.
10. Callback URL: queryflow://oauth/callback
11. OAuth Scopes: add full and refresh_token, offline_access.
12. Save.
13. Wait 2–10 minutes for the app to propagate.
14. Go to App Manager → find your app → View.
15. Copy the Consumer Key (this is your Client ID).
16. Copy the Consumer Secret (click "Click to reveal").

Step 2 — Add the connection in QueryFlow

1. Click Connections → + Add → Salesforce.
2. Name: like My Salesforce.
3. Client ID: paste your Consumer Key.
4. Client Secret: paste your Consumer Secret.
5. Instance URL: your Salesforce URL. For Developer Editions, use https://login.salesforce.com.
6. Click Sign in with Salesforce.
7. Your browser opens. Log in with your Salesforce username and password.
8. Approve the app's permissions.
9. The browser redirects back to QueryFlow.
10. Click Test Connection → Save.

Spreadsheet (CSV / TSV) — local file

For ad-hoc analysis of a CSV or TSV on your Mac.

1. Click Connections → + Add → Spreadsheet.
2. Name: like Customer Export.
3. Click Choose File → pick your CSV or TSV file.
4. Delimiter: usually auto-detected (, for CSV, \t for TSV).
5. Has header row: check this if the first row contains column names.
6. Click Test Connection to preview the data.
7. Click Save.

QueryFlow infers column types from the first few rows — numbers, dates, and text.

Opening the workspace

1. Click any connection in the Connections sidebar.
2. Click the Open Workspace button (or double-click the connection).
3. The SQL editor opens in the center, with the connection name shown in the top-right toolbar.

Writing your first query

1. Click in the editor area.
2. Type a SQL query, for example:

   SELECT * FROM customers LIMIT 100;

   Copy
3. Press ⌘R (or click Run) to execute.
4. Results appear in the table below.

Running specific statements

You don't have to run the whole script. QueryFlow runs whatever your cursor is on, or whatever you've selected.

• Run at cursor (⌘R): runs the single SQL statement containing the cursor.
• Run selection (⌘R with text highlighted): runs only the highlighted text.
• Run all statements (⌘⇧R): runs the entire script, statement by statement.

Multiple tabs

1. Click the + button next to your tab to open a new query tab.
2. Double-click a tab name to rename it.
3. Right-click a tab for Rename / Save / Close options.
4. Tabs are restored automatically the next time you launch QueryFlow.

Saving queries to files

1. Click Save… or press ⌘S.
2. Choose a location and filename. The file is saved as .sql.
3. Saved queries appear in the Queries tab in the left sidebar.
4. Click any saved query to reopen it.

Formatting SQL

1. Press ⌘⇧F (or click Format in the toolbar).
2. Your SQL is reformatted with proper indentation, capitalized keywords, and clean line breaks.

Seeing query history

1. Press ⌘E (or click the clock icon in the toolbar).
2. The History panel shows your last 500 queries with timestamps, connection, row count, and duration.
3. Search the list with the search bar.
4. Click any past query to load it into the active tab.

Canceling a running query

If a query is taking too long, press ⌘. (Command + period) or click Cancel in the loading overlay.

Explain Plan

1. Write a query you want to analyze.
2. Click Explain in the toolbar.
3. QueryFlow runs EXPLAIN against your database and shows the execution plan.
4. The original query is restored after the plan loads.

Browsing schemas

1. Open the workspace for any connection.
2. The Explorer tab on the left shows all your schemas as folders.
3. Click a schema to expand it and see its tables.
4. Click a table to expand it and see its columns with type chips.

Inserting names into your query

• Click a table to insert schema.table_name at your cursor.
• Click a column to insert just the column name.
• Right-click a table for SELECT * FROM table LIMIT 100 — instant exploration query.

Filtering and refreshing

Type in the search bar at the top of the Explorer to filter the tree by name. Useful when you have hundreds of tables.

If your database schema changed (a teammate added a table), click the refresh arrow at the top of the Explorer to reload.

Adding your Anthropic API key

To use Claude, you need an Anthropic API key. You only do this once.

Step 1 — Get an API key from Anthropic

1. Go to console.anthropic.com.
2. Sign up or sign in.
3. Click API Keys in the left sidebar.
4. Click Create Key.
5. Name it QueryFlow.
6. Click Create Key.
7. Copy the key immediately. It starts with sk-ant-. Anthropic only shows it once.

Step 2 — Add the key to QueryFlow

1. In QueryFlow, click the gear icon at the bottom-left → Settings.
2. Find the Anthropic API Key field.
3. Paste your key.
4. Click Save.

The key is stored securely in your Mac's Keychain. It never leaves your machine except when QueryFlow calls Anthropic's API directly.

Opening the Claude panel

1. In any SQL workspace, click the Claude button in the toolbar (small dot + the word "Claude").
2. The chat panel slides in from the right.
3. Click the button again to hide it.

What Claude can see

At the bottom of the chat panel you'll see context chips that show exactly what Claude has access to right now:

• SQL — your current query
• Python — your current Python code (if you have any)
• Markdown — your current notes
• Rows — the latest query results (first 50 rows)
• Schema — every table and column in your database
• Errors — the last 5 execution errors (red chip)

Claude uses all of these to answer your questions, so you don't need to paste anything in.

Asking Claude things

Just type a question and press Enter, or click the arrow button.

Good things to ask:

• "Write me a query that finds customers who haven't ordered in 90 days."
• "Why is this query slow?"
• "What does this error mean?"
• "Summarize these results."
• "Help me debug — the customers_raw table — what's in it?"
• "Convert this query to use a CTE instead of a subquery."

Inserting Claude's code into your editor

When Claude responds with SQL or Python in a fenced code block:

1. Hover over the response bubble.
2. Click Copy Code to copy just the code (without Claude's explanation).
3. Paste into your editor.

Or click Copy to get the full response with explanation.

Click the circular arrow icon at the top of the chat panel to start fresh. Claude won't remember the previous conversation.

Creating a pipeline

1. Click the Pipelines icon in the narrow left sidebar.
2. Click + New Pipeline.
3. Name it (e.g. Daily Customer Sync).
4. Drag a Source card onto the canvas — pick any of your connections.
5. Drag a Destination card onto the canvas — pick any of your destinations.
6. Click the source card → write a SQL query (or pick a saved one).
7. Click the connecting line between source and destination → the Field Mapper opens.

Using the Field Mapper

The Field Mapper shows your source columns on the left and your destination columns on the right.

1. Drag a source column to a destination column to map them.
2. Or use the dropdown next to each destination column to pick the source.
3. Click AI Map in the top-right to auto-match similar column names (e.g. FirstName → first_name, C_EMAIL_ADDRESS → email).
4. Review the suggestions. The AI handles 25+ common synonyms automatically.
5. Click Save Mapping.

Running a pipeline

• Click Run Now in the pipeline editor to execute once.
• Click Schedule to set it up to run automatically.
• Click Run History to see past executions with row counts and any errors.

Adding a destination

A destination is where your query results end up. You can have multiple destinations on one job — send the same data to a file and an email and an S3 bucket, all at once.

1. Click the Destinations icon in the narrow left sidebar.
2. Click + Add.
3. Pick a destination type.

Amazon S3

1. Pick Amazon S3.
2. Name: like S3 Output.
3. Bucket: your S3 bucket name.
4. Region: e.g. us-east-1.
5. Prefix / Folder: optional, like queryflow/exports/.
6. AWS Access Key ID and Secret Access Key (same as Redshift — see the IAM setup above).
7. Test Destination → Save.

SFTP

1. Pick SFTP.
2. Host, Port (usually 22), Username, Password (or SSH key).
3. Remote path: where files land, like /uploads/queryflow/.
4. Filename pattern: e.g. customers_{date}.csv (the {date} placeholder gets replaced at run time).
5. Test → Save.

Local File

1. Pick Local File.
2. Folder: click Choose Folder to pick where files save.
3. Format: CSV, JSON, Parquet, or Excel.
4. Filename pattern: e.g. report_{date}.csv.
5. Save.

Email (Gmail / SMTP)

1. Pick Email.
2. Provider: Gmail (OAuth) or SMTP.
3. For Gmail, sign in with Google. For SMTP, enter your SMTP host, port, username, and password.
4. To: comma-separated email addresses.
5. Subject: the email subject.
6. Attach file: check to attach the query result as a CSV.
7. Inline table: check to embed the table directly in the email body.
8. Save.

Database destination — Snowflake / Redshift / Postgres / MySQL / Google Sheets

You can write results back to any database connection you've added.

1. Pick the database type.
2. Choose the connection from the dropdown.
3. Pick the target table (or type a new table name — QueryFlow can create it).
4. Choose Append (add new rows) or Replace (delete existing rows first).
5. Map your columns in the Field Mapper.
6. Save.

Scheduling a query

The whole point of QueryFlow is that things run without you. Every query, pipeline, or Python script can be scheduled.

1. From any SQL workspace, click Schedule in the toolbar.
2. The Schedule sheet opens.
3. Name: what to call this job, like Daily Customer Export.
4. Trigger: pick how often it runs.
5. Destination: pick where the results go.
6. Click Save Schedule.

Trigger types

• Manual — only runs when you click Run Now.
• Interval — every N minutes / hours / days.
• Daily — every day at a specific time (e.g. 9:00 AM).
• Weekly — specific day(s) of the week at a specific time.
• Monthly — specific day of the month.
• Cron — paste a cron expression for full control (e.g. 0 9 * * 1-5 for weekdays at 9 AM).

Viewing and managing jobs

1. Click the Schedules icon in the narrow left sidebar.
2. You'll see a list of every scheduled job with status (Enabled / Disabled), next run, and last run.

Pausing, editing, or deleting:

• Toggle the switch on a job card to enable or disable it.
• Click the job to open it and edit any setting.
• Right-click → Delete to remove it permanently.

Running a job manually: click Run Now on any job card.

Viewing run history:

1. Click any scheduled job.
2. Click the Runs tab.
3. You'll see every execution with timestamp, duration, row count, and any errors.
4. Click a run to see the full logs.

Running Python

Every workspace has a Python cell underneath the SQL editor. The SQL results are automatically available to Python as a pandas DataFrame called df — you don't have to load anything.

1. After running a SQL query, click the Python tab below the editor.
2. Type Python code. For example:

   print(df.head())
   print(df.describe())

   Copy
3. Press ⌘R to run.
4. Output streams to the panel below.

Available libraries (pre-installed)

• pandas — DataFrames
• numpy — numerical
• matplotlib and plotly — charts
• requests — HTTP
• openpyxl — Excel
• pyarrow — Parquet
• paramiko — SFTP
• boto3 — AWS S3

Generating charts

import plotly.express as px
fig = px.bar(df, x='region', y='revenue')
fig.show()

The chart renders inline in the output panel.

Charts (without Python)

If you'd rather not write Python, QueryFlow has a built-in chart view.

1. Run any SQL query.
2. Click the Chart tab in the results panel.
3. Pick an X axis column and a Y axis column.
4. Pick a chart type: Bar, Line, or Scatter.
5. The chart renders instantly.

Exporting Results

After running a query, click the Export tab in the results panel:

• Copy CSV — copies CSV-formatted data to your clipboard.
• Export CSV — saves a .csv file to your Mac.
• Copy JSON — copies JSON-formatted data to your clipboard.
• Export Excel — coming soon.

Errors — reading and copying

When something goes wrong, QueryFlow shows the actual error message, not a generic code.

From the schema explorer

If the explorer can't load (bad connection, missing database, etc.):

1. The error appears in red in the left panel.
2. Click Copy Error to copy the full message to your clipboard.
3. Click Retry to try loading again.
4. Right-click the error for Copy and Retry in one step.

From the logs panel

1. Click the terminal icon in the toolbar to show the Logs panel.
2. Failed queries appear in red with the full Snowflake / Postgres / MySQL error message.
3. Click any log entry to select the text.
4. Hover and click the copy icon to copy that single entry.
5. Click Copy All in the panel header to copy everything.

Asking Claude about an error

1. After an error appears in the logs, open the Claude panel.
2. The red Errors context chip lights up — Claude can see the error.
3. Ask Claude: "What does the latest error mean?" or "How do I fix this?"

Keyboard Shortcuts

Press ⌘⇧/ anytime to see the full shortcuts panel.

Settings & Preferences

Click the gear icon at the bottom-left of the app.

• Anthropic API Key — paste your key here to enable Claude.
• Theme — Auto / Light / Dark.
• Editor Density — Comfortable / Compact.
• Telemetry — toggle anonymous usage events. No personal data, no query text.
• Background Scheduler — enable to keep jobs running when QueryFlow is closed.

Updating QueryFlow

QueryFlow updates automatically through the Mac App Store. To check manually:

1. Open the App Store on your Mac.
2. Click your profile icon (bottom-left).
3. Scroll to Available Updates — if QueryFlow is listed, click Update.

"Connection failed" / "Could not connect"

1. Check your internet connection.
2. Verify the host, port, username, and password.
3. For cloud databases, check that your IP is whitelisted (if your security team uses IP allowlists).
4. Click Test Connection — the error message will tell you exactly what's wrong.

"Database does not exist or not authorized" (Snowflake)

1. The database name is wrong, or your PAT's role doesn't have access.
2. In Snowsight, run SHOW DATABASES;. Make sure your database is in the list.
3. If it is, grant USAGE: GRANT USAGE ON DATABASE <db> TO ROLE <your_role>;

Claude says "Add your Anthropic API key in Settings"

You haven't pasted your API key yet. Go to Settings → paste your key from console.anthropic.com.

A scheduled job didn't run

1. Was your Mac awake at the scheduled time? Jobs only run when your Mac is awake.
2. Was the job enabled? Check the Schedules tab.
3. Click the job → Runs tab → look for an error.

Query is running forever

Press ⌘. to cancel, then check:

1. Is your warehouse / cluster running? (Snowflake auto-resumes; Redshift may need to be started manually.)
2. Is the query genuinely big? Add LIMIT 1000 to test.
3. Open the Logs panel for more detail.

QueryFlow won't launch

1. Try Force Quit (⌘⌥Esc) → relaunch.
2. If that fails, delete and reinstall from the Mac App Store. Your data is preserved in your user folder.

Getting Help

• Discord community: discord.gg/j36cFY8FdA
• Email: support@getqueryflow.com
• YouTube channel: QueryFlow on YouTube
• Privacy policy: getqueryflow.com/privacy