Skip to content
Back to search

squix

SkillWorks with Claude CodeGitHub

Run SQL queries across databases (Postgres, MySQL, SQLite, etc.) via the squix CLI. Use for running named queries, exploring schema, or parameterized queries. Always use -f for non-interactive output.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/eduardofuncao--squix/badge.svg)](/listings/eduardofuncao--squix)

HTML

<a href="/listings/eduardofuncao--squix"><img src="/api/listings/eduardofuncao--squix/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Go to [the releases page](https://github.com/eduardofuncao/squix/releases) and find the correct version for your system. Download it and make sure the file is executable and moved to a directory in your $PATH. Alternatively, use one of the methods below:

<details> <summary>Go install</summary>

Use go to install `squix` directly

go install github.com/eduardofuncao/squix/cmd/squix@latest

this will put the binary `squix` in your $GOBIN path (usually `~/go/bin`) </details>

<details> <summary>Build Manually</summary>

Follow these instructions to build the project locally

git clone https://github.com/eduardofuncao/squix

go build -o squix ./cmd/squix

The squix binary will be available in the root project directory

See [Build variants](docs/features.md#build-variants) for the full/lite/minimal builds and which drivers each one includes. </details>

<details> <summary>Nixpkgs</summary>

Squix is available in [nixpkgs](https://search.nixos.org/packages?query=squix) (v0.4.0-beta+).

# Try it
nix-shell -p squix

# Or with flakes
nix run nixpkgs#squix

</details>

<details> <summary>Nix / NixOS (Flake)</summary>

Squix is available as a Nix flake for easy installation on NixOS and systems with Nix.

Run directly without installing

nix run github:eduardofuncao/squix

Install to user profile

nix profile install github:eduardofuncao/squix

Enter development shell

nix develop github:eduardofuncao/squix

NixOS System-wide

Add to your flake-based configuration.nix or flake.nix:

{
description = "My NixOS config";

inputs = {
  nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
  squix.url = "github:eduardofuncao/squix";
};

outputs = { self, nixpkgs, squix, ... }: {
  nixosConfigurations.myHostname = nixpkgs.lib.nixosSystem {
    system = "x86_64-linux";
    modules = [
      {
        environment.systemPackages = [
          squix.packages.x86_64-linux.default
        ];
      }
    ];
  };
};
}

Then rebuild: sudo nixos-rebuild switch

Home Manager

Add to your home.nix or flake config:

{
inputs = {
  nixpkgs.url = "github:NixOS/nixpkgs/nix-unstable";
  squix.url = "github:eduardofuncao/squix";
};

outputs = { self, nixpkgs, squix, ... }: {
  homeConfigurations."username" = {
    pkgs = nixpkgs.legacyPackages.x86_64-linux;
    modules = [
      {
        home.packages = [
          squix.packages.x86_64-linux.default
        ];
      }
    ];
  };
};
}

Then apply: home-manager switch </details>

<details> <summary>Homebrew</summary>

brew tap eduardofuncao/squix
brew install squix

</details>

<details> <summary>Arch (AUR) - Unofficial</summary>

There's also an unofficial AUR package for squix available at: [squix-bin](https://aur.archlinux.org/packages/squix-bin)

</details>

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 88 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. ---
  2. name: squix
  3. description: Run SQL queries across databases (Postgres, MySQL, SQLite, etc.) via the squix CLI. Use for running named queries, exploring schema, or parameterized queries. Always use -f for non-interactive output.
  4. ---
  5. # Squix Skill for AI Coding Agents
  6. ## What is Squix
  7. Squix is a CLI tool for managing and executing SQL queries across multiple
  8. databases (PostgreSQL, MySQL, SQLite, Oracle, SQL Server, ClickHouse, Firebird).
  9. It stores named queries in `~/.config/squix/config.yaml`.
  10. ## Critical Rules
  11. 1. **Always use `-f` with `squix run` for SELECT queries** — without it, SELECT results open an interactive TUI; non-SELECT queries print a status message either way
  12. 2. **No inline connection flag** — must `squix switch <name>` before queries
  13. 3. **Check connection first** — run `squix status` to verify reachability
  14. ## Non-Interactive Output
  15. ```bash
  16. squix run <query> -f json # JSON array of objects
  17. squix run <query> -f csv # CSV with header row
  18. squix run <query> -f tsv # Tab-separated values
  19. squix run <query> -f markdown # Markdown table
  20. squix run <query> -f html # HTML table with styling
  21. squix run <query> -f sql # INSERT statements
  22. squix run "SELECT 1" -f json # Inline SQL works too
  23. squix run --last -f csv # Re-run last query
  24. ```
  25. Output goes to stdout, errors to stderr. Exit code 1 on failure.
  26. Pipe cleanly: `squix run list_users -f json > users.json`
  27. Empty results: "No results found" on stderr, nothing on stdout.
  28. ## Setup Workflow
  29. ```bash
  30. squix init mydb "postgresql://user:pass@localhost:5432/mydb" # auto-infers DB type
  31. squix switch mydb # or: squix use mydb
  32. squix add list_users "SELECT * FROM users" # SQL must be inline
  33. squix run list_users -f json # always use -f
  34. ```
  35. ## Explore Schema
  36. ```bash
  37. squix explore # List all tables (non-interactive, prints to stdout)
  38. squix explain orders -d 2 # Show FK relationships as ASCII tree
  39. ```
  40. ## List Queries
  41. ```bash
  42. squix list queries # Format: ◆ <id>/<name> (<table>)
  43. squix list queries --oneline # Compact: <id> <name> <table>
  44. squix list connections # List all configured connections
  45. ```
  46. ## Parameterized Queries
  47. Named params use `:name` syntax. Optional defaults with `:name|default`:
  48. ```bash
  49. squix add user_by_id "SELECT * FROM users WHERE id = :user_id"
  50. squix run user_by_id --user_id 42 -f csv # named
  51. squix run user_by_id 42 -f csv # positional
  52. ```
  53. ## Status & Cleanup
  54. ```bash
  55. squix status # Shows: ● postgres/mydb (schema: public) — reachable
  56. squix remove list_users # Delete query (no confirmation needed)
  57. echo y | squix remove -c mydb # Delete connection (needs confirmation)
  58. ```
  59. ## Commands to Avoid (Interactive)
  60. - `squix run <query>` without `-f` on a SELECT — opens TUI
  61. - `squix shell` — interactive REPL
  62. - `squix edit` — opens `$EDITOR`
  63. - `squix explore <table>` — opens TUI
  64. - `squix info` — opens TUI
  65. - `squix add <name>` without SQL — opens `$EDITOR`
  66. - `squix run` with no args — opens `$EDITOR`
README.md · README · 407 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <div align="center">
  2. <h1>
  3. <img width="auto" height="45" alt="image" src="https://github.com/user-attachments/assets/f82ceec8-9fc7-4253-9ec0-f5548c646996" />
  4. Squix's SQL Stash
  5. <img width="auto" height="36" alt="image" src="https://github.com/user-attachments/assets/c128f28f-dd10-4213-9915-dedafe7ae831" />
  6. </h1>
  7. <img width="360" height="131" alt="image" src="https://github.com/user-attachments/assets/9428a75b-ffa4-4961-919b-e5ccf192ef26" />
  8. ### **SQL Query Stashing for Terminal Squirrels**
  9. ---
  10. [![MIT License](https://img.shields.io/badge/license-MIT-white.svg)](LICENSE)
  11. ![go badge](https://img.shields.io/badge/g=Go-1.25+-00ADD8?%20logo=go&logoColor=white&label=go)
  12. [![Matrix](https://img.shields.io/matrix/squix:matrix.org?server_fqdn=matrix.org&label=chat&color=green)](https://matrix.to/#/#squix-sql:matrix.org)
  13. [![Sponsor](https://img.shields.io/badge/sponsor-%E2%9D%A4-pink.svg)](https://github.com/sponsors/eduardofuncao)
  14. **A CLI tool for managing and executing SQL queries across multiple databases. Written in Go, made beautiful with BubbleTea**
  15. [Quick Start](#--------quick-start) • [Configuration](docs/configuration.md) • [Commands](docs/commands.md) • [Keybindings](docs/keybindings.md) • [Features](docs/features.md) • [Completion](docs/completion.md) • [Databases](docs/databases.md) • [Roadmap](#--------roadmap) • [Contributing](CONTRIBUTING.md)
  16. > This project is currently in beta, please report unexpected behavior through the issues tab
  17. </div>
  18. ---
  19. <h2>
  20. <img width="auto" height="24" alt="image" style="vertical-align:middle;" src="https://github.com/user-attachments/assets/464275ac-085e-451f-b783-c991d24d3635" />
  21. Demo
  22. </h2>
  23. ![squixdemo2](https://github.com/user-attachments/assets/ee9653cf-6aaa-4be9-a898-37153ab0c898)
  24. > Try out the [live demo](https://squix.live.eduardofuncao.com) (desktop only, no install required!)
  25. ### Highlights
  26. - **Query Library** - Save and organize your most-used queries, with parameterized support
  27. - **Multi-Database** - Works with PostgreSQL, MySQL, SQLite, Oracle, SQL Server, ClickHouse, Firebird and DuckDB
  28. - **Table view TUI** - Keyboard focused navigation and search with configurable vim-style bindings
  29. - **In-Place Editing** - Update cells, delete rows and edit your SQL directly from the results table
  30. - **Export your data** - Export your data as CSV, JSON, SQL, Markdown or HTML tables
  31. - **Connection Switching** - Manage multiple databases and switch whenever you want
  32. - **Database Exploration** - Browse schema, visualize foreign key relationships
  33. - **Interactive Shell** - REPL with history, multi-line, and meta-commands
  34. See [Features](docs/features.md) for details and examples
  35. ---
  36. <h2>
  37. <img width="auto" height="24" alt="image" style="vertical-align:middle;" src="https://github.com/user-attachments/assets/30765e98-13b3-4c18-81e7-faf224b60e0b" />
  38. Quick Start
  39. </h2>
  40. ### Installation
  41. Go to [the releases page](https://github.com/eduardofuncao/squix/releases) and find the correct version for your system. Download it and make sure the file is executable and moved to a directory in your $PATH. Alternatively, use one of the methods below:
  42. <details>
  43. <summary>Go install</summary>
  44. Use go to install `squix` directly
  45. ```bash
  46. go install github.com/eduardofuncao/squix/cmd/squix@latest
  47. ```
  48. this will put the binary `squix` in your $GOBIN path (usually `~/go/bin`)
  49. </details>
  50. <details>
  51. <summary>Build Manually</summary>
  52. Follow these instructions to build the project locally
  53. ```bash
  54. git clone https://github.com/eduardofuncao/squix
  55. go build -o squix ./cmd/squix
  56. ```
  57. The squix binary will be available in the root project directory
  58. See [Build variants](docs/features.md#build-variants) for the full/lite/minimal builds and which drivers each one includes.
  59. </details>
  60. <details>
  61. <summary>Nixpkgs</summary>
  62. Squix is available in [nixpkgs](https://search.nixos.org/packages?query=squix) (v0.4.0-beta+).
  63. ```bash
  64. # Try it
  65. nix-shell -p squix
  66. # Or with flakes
  67. nix run nixpkgs#squix
  68. ```
  69. </details>
  70. <details>
  71. <summary>Nix / NixOS (Flake)</summary>
  72. Squix is available as a Nix flake for easy installation on NixOS and systems with
  73. Nix.
  74. #### Run directly without installing
  75. ```bash
  76. nix run github:eduardofuncao/squix
  77. ```
  78. #### Install to user profile
  79. ```bash
  80. nix profile install github:eduardofuncao/squix
  81. ```
  82. #### Enter development shell
  83. ```bash
  84. nix develop github:eduardofuncao/squix
  85. ```
  86. #### NixOS System-wide
  87. Add to your flake-based configuration.nix or flake.nix:
  88. ```nix
  89. {
  90. description = "My NixOS config";
  91. inputs = {
  92. nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
  93. squix.url = "github:eduardofuncao/squix";
  94. };
  95. outputs = { self, nixpkgs, squix, ... }: {
  96. nixosConfigurations.myHostname = nixpkgs.lib.nixosSystem {
  97. system = "x86_64-linux";
  98. modules = [
  99. {
  100. environment.systemPackages = [
  101. squix.packages.x86_64-linux.default
  102. ];
  103. }
  104. ];
  105. };
  106. };
  107. }
  108. ```
  109. Then rebuild: sudo nixos-rebuild switch
  110. #### Home Manager
  111. Add to your home.nix or flake config:
  112. ```nix
  113. {
  114. inputs = {
  115. nixpkgs.url = "github:NixOS/nixpkgs/nix-unstable";
  116. squix.url = "github:eduardofuncao/squix";
  117. };
  118. outputs = { self, nixpkgs, squix, ... }: {
  119. homeConfigurations."username" = {
  120. pkgs = nixpkgs.legacyPackages.x86_64-linux;
  121. modules = [
  122. {
  123. home.packages = [
  124. squix.packages.x86_64-linux.default
  125. ];
  126. }
  127. ];
  128. };
  129. };
  130. }
  131. ```
  132. Then apply: home-manager switch
  133. </details>
  134. <details>
  135. <summary>Homebrew</summary>
  136. ```bash
  137. brew tap eduardofuncao/squix
  138. brew install squix
  139. ```
  140. </details>
  141. <details>
  142. <summary>Arch (AUR) - Unofficial</summary>
  143. There's also an unofficial AUR package for squix available at: [squix-bin](https://aur.archlinux.org/packages/squix-bin)
  144. </details>
  145. ### Basic Usage
  146. ```bash
  147. # Create your first connection (PostgreSQL example)
  148. squix init mydb postgres "postgresql://user:pass@localhost:5432/mydb"
  149. # Add a saved query
  150. squix add list_users "SELECT * FROM users"
  151. # List your saved queries
  152. squix list queries
  153. # Run it, this opens the interactive table viewer
  154. squix run list_users
  155. # Or run inline SQL
  156. squix run "SELECT * FROM products WHERE price > 100"
  157. ```
  158. No database handy? Spin up a sample one to explore right away:
  159. ```bash
  160. # Create an Office-themed SQLite database in the current directory
  161. squix example
  162. squix init --name example --type sqlite --conn example.db
  163. squix explore
  164. squix run "select * from employees"
  165. ```
  166. ### Navigating the Table
  167. Once your query results appear, you can navigate and interact with the data:
  168. ```bash
  169. # Use vim-style navigation or arrow-keys
  170. j/k # Move down/up
  171. h/l # Move left/right
  172. g/G # Jump to first/last row
  173. # Copy data
  174. y # Yank (copy) current cell
  175. v # Enter visual mode to select multiple cells and copy with y
  176. x # Export selected data as csv, tsv, json, sql, markdown or html
  177. # Edit data directly
  178. u # Update current cell (opens your $EDITOR)
  179. D # Delete current row
  180. # Modify and re-run
  181. e # Edit the query and re-run it
  182. # Search around
  183. / # Search cell's contents (n/N to cycle through results)
  184. f # Search column names (,/; to cycle through results)
  185. # Help
  186. H # Show keyboard shortcuts overlay
  187. ? # Toggle footer keybinds
  188. # Exit
  189. q # Quit back to terminal
  190. ```
  191. ---
  192. <h2>
  193. <img width="auto" height="24" alt="image" style="vertical-align:middle;" src="https://github.com/user-attachments/assets/c46a2565-a58c-472c-9393-96724d9716da" />
  194. Database Support
  195. </h2>
  196. PostgreSQL, MySQL, MariaDB, SQL Server, SQLite, Oracle, ClickHouse, Firebird, DuckDB
  197. See connection init examples in [Database Support](docs/databases.md)
  198. ---
  199. <h2>
  200. <img width="auto" height="24" alt="image" src="https://github.com/user-attachments/assets/be97c01c-9140-4503-92df-e1b6f2d7c31a" />
  201. Shell Completion
  202. </h2>
  203. Dynamic tab completion for bash, zsh, and fish that includes your saved queries and connections.
  204. See [Shell Completion](docs/completion.md)
  205. ---
  206. <h2>
  207. <img width="auto" height="24" alt="image" style="vertical-align:middle" src="https://github.com/user-attachments/assets/8f5037c9-e616-4065-adfc-cd598621c887" />
  208. Configuration
  209. </h2>
  210. Row limits, column widths, color schemes (`dracula`, `gruvbox`, `catppuccin-mocha`, etc.) and UI visibility options can be set through the config file at `~/.config/squix/config.yaml`.
  211. See [Configuration](docs/configuration.md)
  212. ---
  213. <h2>
  214. <img width="auto" height="24" alt="image" style="vertical-align:middle;" src="https://github.com/user-attachments/assets/4b1425ae-7918-4a3f-b37c-41c3e443929e" />
  215. All Commands
  216. </h2>
  217. See [Commands](docs/commands.md) for the full command reference and database init examples
  218. ---
  219. <h2>
  220. <img width="auto" height="24" alt="image" style="vertical-align:middle;" src="https://github.com/user-attachments/assets/504a8488-69bf-43b4-860b-0659a6db3c69" />
  221. TUI Table Navigation
  222. </h2>
  223. See [Keybindings](docs/keybindings.md) for all navigation, editing, search, and visual mode keybindings on the results table view
  224. ---
  225. <h2>
  226. <img width="auto" height="24" alt="image" src="https://github.com/user-attachments/assets/ebbabd15-87c4-47e5-b881-968b03e1d85d" />
  227. For Robots
  228. </h2>
  229. Squix ships a `SKILL.md` file in the repo root, a simple reference for AI
  230. coding agents (Claude Code, Copilot, etc.) to use squix non-interactively. It
  231. covers safe commands, format flags, parameterized queries, and which commands
  232. to avoid (TUI/editor). Point your agent at it if you want it to run SQL queries
  233. as part of your workflow.
  234. ---
  235. <h2>
  236. <img width="auto" height="24" alt="image" style="vertical-align:middle;" src="https://github.com/user-attachments/assets/432c6b41-b2e0-4326-a3cc-7b349a987bb0" />
  237. Roadmap
  238. </h2>
  239. > This project is currently in beta, please report unexpected behavior through the issues tab
  240. ### v0.5.0 - Scrat 🧊
  241. - [x] Configurable keybinds
  242. - [x] Migrate to bubbletea v2
  243. - [x] Return more info on exec statements (insert, update, delete, etc.)
  244. - [x] Homebrew custom tap
  245. - [x] nixpkgs entry
  246. - [x] Handle windows env vars seamlessly
  247. ### v1.0.0 - Scrat 🧊
  248. - [x] Move saved configs from top level yaml file to per-connection sql files
  249. - [x] Display counters for selected lines and search results
  250. - [x] Allow different connections to share query collection (eg. dev, stg, prod)
  251. - [ ] Rework database exploration commands
  252. - [ ] Option to encrypt sensitive data in the config file
  253. ---
  254. <h2>
  255. <img width="auto" height="24" alt="image" src="https://github.com/user-attachments/assets/cd243b3c-c39f-4e3f-9003-14ef6d713169" />
  256. Sponsor
  257. </h2>
  258. If Squix saves you time, consider supporting its development through [GitHub
  259. Sponsors](https://github.com/sponsors/eduardofuncao). I work on Squix in my
  260. spare time and your support helps me dedicate more hours to it, keep the [live
  261. demo](https://squix.live.eduardofuncao.com) running, build a proper
  262. docs/landing site, and cover GitHub Actions minutes for cross-platform builds,
  263. instead of relying on local builds.
  264. Any amount is greatly appreciated ❤
  265. ---
  266. <h2>
  267. <img width="auto" height="24" alt="image" src="https://github.com/user-attachments/assets/20aad60b-adc7-4a4d-971b-cb37f8a0cbbf" />
  268. Contributing & acknowledgements
  269. </h2>
  270. We welcome contributions! Get started with detailed instructions from [CONTRIBUTING.md](CONTRIBUTING.md)
  271. Thanks a lot to all the contributors:
  272. <a href="https://github.com/DeprecatedLuar"><img src="https://github.com/DeprecatedLuar.png" width="40" /></a>
  273. <a href="https://github.com/caiolandgraf"><img src="https://github.com/caiolandgraf.png" width="40" /></a>
  274. <a href="https://github.com/g4brielklein"><img src="https://github.com/g4brielklein.png" width="40" /></a>
  275. <a href="https://github.com/eduardofuncao"><img src="https://github.com/eduardofuncao.png" width="40" /></a>
  276. <a href="https://github.com/udirona"><img src="https://github.com/udirona.png" width="40" /></a>
  277. <a href="https://github.com/Leosallin"><img src="https://github.com/Leosallin.png" width="40" /></a>
  278. <a href="https://github.com/chasinglogic"><img src="https://github.com/chasinglogic.png" width="40" /></a>
  279. <a href="https://github.com/akdev1l"><img src="https://github.com/akdev1l.png" width="40" /></a>
  280. <a href="https://github.com/KalebJS"><img src="https://github.com/KalebJS.png" width="40" /></a>
  281. <a href="https://github.com/Liferenko"><img src="https://github.com/Liferenko.png" width="40" /></a>
  282. Squix wouldn't exist without the inspiration and groundwork laid by these fantastic projects:
  283. - **[naggie/dstask](https://github.com/naggie/dstask)** - For the elegant CLI design patterns and file-based data storage approach
  284. - **[DeprecatedLuar/better-curl-saul](https://github.com/DeprecatedLuar/better-curl-saul)** - For demonstrating a simple and genius approach to making a CLI tool
  285. - **[dbeaver](https://github.com/dbeaver/dbeaver)** - The OG database management tool
  286. Built with:
  287. - [Bubble Tea](https://github.com/charmbracelet/bubbletea) - The TUI framework
  288. - Go standard library and various database drivers
  289. <div align="center">
  290. **Made with 🐿️ by [@eduardofuncao](https://github.com/eduardofuncao)**
  291. <img width="320" height="224" alt="Squix mascot" src="https://github.com/user-attachments/assets/f995ce07-3742-4e98-b737-bbdbf982012e" />
  292. Previously Pam's Database Drawer, thanks to [u/marrsd](https://www.reddit.com/user/marrsd/) for suggesting the new name!
  293. </div>

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.