Forge FSQL CLI

Interactive CLI for querying Atlassian Forge SQL databases via web triggers.

Demo

Features

• 🎨 Table formatting with colors
• ⚡ Special commands (.tables, .describe, .schema)
• ⌨️ Command history (↑/↓ arrows)
• 💾 Persistent history across sessions
• ⏱️ Query timing
• 📝 Multi-line SQL support

Built in Commands

fsql> .help

Special Commands:
  .schema         Show database schema
  .tables         List all tables
  .describe       Describe a table (.describe table_name)
  .indexes        Show all indexes
  .migrations     List all migrations
  .database       Show the database name
  .help           Show available commands

Other:
  exit, quit      Exit the CLI
  Ctrl+C          Cancel current query
  Ctrl+D          Exit the CLI
  ↑/↓             Navigate command history

Security

• Disabled in Production - returns a 403 error if you attempt to call it

Installation

In Your Forge Project

npm install -g forge-fsql

fsql-setup

Notes:

• creates a webtrigger in your manifest.yml
• creates a module at src/fsql.ts for the webtrigger function
• deploys the project with the new manifest
• creates the webtrigger with forge webtrigger create (default environment which is DEVELOPMENT in a standard setup)
• adds the webtrigger URL to a FORGE_SQL_WEBTRIGGER environment variable in .env

Run

fsql

Export

Export your Forge SQL database schema and data to a local SQL file.

fsql-export

Options:

• --schema-only: Export schema only (skip data)
• --output <file>: Output file path (default: ./fsql-dumps/fsql-export-<timestamp>.sql)
• --live-schema: Fetch DDL from live database instead of migration.ts

Notes:

• uses FORGE_SQL_WEBTRIGGER from your .env file
• exports schema and data to ./fsql-dumps/ by default
• automatically looks for migration.ts to preserve your exact table definitions

Upgrade

# upgrade the CLI
> npm install -g forge-fsql@latest

# run the setup from the root of your project to pick up the new version
# it will install fsql.ts again and redeploy again
myforgeproject> fsql-setup