Skip to content
Back to search

omnisql-mcp

omnisql-mcp

Safety scan

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

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/srthkdev/omnisql-mcp with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/srthkdev/omnisql-mcp'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/srthkdev--omnisql-mcp/badge.svg)](/listings/srthkdev--omnisql-mcp)

HTML

<a href="/listings/srthkdev--omnisql-mcp"><img src="/api/listings/srthkdev--omnisql-mcp/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.

These steps run a script from the network that findsafeskills does not scan.

Run the guided installer, choose Claude Code, Codex, or OpenCode, and OmniSQL adds itself to that client's MCP configuration:

npx -y omnisql-mcp@latest install

The installer detects installed clients, asks for your DBeaver workspace, lets you choose read-only access and a connection allowlist, then registers the server. Database and SSH credentials come from your saved workspace; no OmniSQL API key is needed. Start a new client session after setup.

To add it to a specific client directly:

npx -y omnisql-mcp@latest install claude
npx -y omnisql-mcp@latest install codex
npx -y omnisql-mcp@latest install opencode

Add `--read-only` to register with writes disabled, or `--dry-run` to print the registration command. Direct setup uses the default workspace and the server's normal read/write settings unless you pass `--read-only`.

Native client commands

You can also register the server using your client's own CLI:

# Claude Code — available across projects
claude mcp add --transport stdio --scope user omnisql -- npx -y omnisql-mcp@latest

# Codex
codex mcp add omnisql -- npx -y omnisql-mcp@latest

# OpenCode v2 — available across projects
opencode mcp add omnisql --global -- npx -y omnisql-mcp@latest

These follow the [Claude Code](https://code.claude.com/docs/en/mcp), [Codex](https://developers.openai.com/codex/mcp), and [OpenCode v2](https://opencode.ai/v2/docs/mcp-servers) registration commands. OpenCode v1 users can add a local server through their MCP settings.

Claude Desktop and Cursor

Add the following MCP entry to Claude Desktop's `claude_desktop_config.json`, or Cursor's `mcp.json`:

{
  "mcpServers": {
    "omnisql": {
      "command": "npx",
      "args": ["-y", "omnisql-mcp@latest"]
    }
  }
}

On Windows, use `"command": "cmd"` and `"args": ["/c", "npx", "-y", "omnisql-mcp@latest"]` when your client cannot launch `npx` directly.

Standalone install (macOS / Linux)

For a local executable, including machines without Node.js:

curl -fsSL https://srthkdev.github.io/omnisql-mcp/install.sh | bash

Installs under `~/.local/share/omnisql-mcp` with a launcher at `~/.local/bin/omnisql-mcp`, without sudo. If Bun 1.4.3+ is unavailable, it downloads a private Bun runtime and verifies its SHA-256 checksum. Use the printed absolute launcher path as your MCP client's command. Run the installer again to upgrade; append `bash -s -- 2.2.0` in place of `bash` to pin a version. `OMNISQL_INSTALL_DIR` and `OMNISQL_BIN_DIR` choose other directories.

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.

README.md · README · 423 lines

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

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <p align="center">
  2. <img src="assets/wordmark.svg" alt="OmniSQL MCP" width="620">
  3. </p>
  4. <p align="center">
  5. Give Claude Code, Codex, and OpenCode access to the databases you already use.<br>
  6. Reuse saved DBeaver connections, query with native drivers, and keep control over access.
  7. </p>
  8. <p align="center">
  9. <a href="https://www.npmjs.com/package/omnisql-mcp"><img src="https://img.shields.io/npm/v/omnisql-mcp?color=913f32&amp;label=npm" alt="npm version"></a>
  10. <a href="https://github.com/srthkdev/omnisql-mcp/actions/workflows/ci.yml"><img src="https://github.com/srthkdev/omnisql-mcp/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
  11. <a href="https://github.com/srthkdev/omnisql-mcp/stargazers"><img src="https://img.shields.io/github/stars/srthkdev/omnisql-mcp?style=flat&amp;color=913f32" alt="GitHub stars"></a>
  12. <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-716e65" alt="MIT license"></a>
  13. </p>
  14. <p align="center">
  15. <a href="#quick-setup">quick setup</a> ·
  16. <a href="#what-you-can-do">features</a> ·
  17. <a href="#try-the-demo">demo</a> ·
  18. <a href="https://omnisql.srthkdev.com/">docs</a> ·
  19. <a href="CHANGELOG.md">releases</a>
  20. </p>
  21. <p align="center"><a href="assets/codex-session.mp4"><img src="assets/mcp-instance-calls.webp" alt="Real Codex CLI window: one OmniSQL server compares sales and warehouse" width="100%"></a></p>
  22. <p align="center">Captured from the real Codex CLI window against synthetic SQLite instances. <a href="assets/codex-session.mp4">Watch the recording</a> · <a href="assets/codex-session.gif">GIF preview</a>.</p>
  23. ## What you can do
  24. | Capability | How it helps |
  25. |---|---|
  26. | **Reuse saved connections** | Read database and SSH settings from DBeaver-compatible workspaces, including custom projects. |
  27. | **Query across engines** | PostgreSQL, MySQL/MariaDB, SQLite, SQL Server, Oracle, DuckDB, and ClickHouse. |
  28. | **Choose another database** | Discover databases and select one at call time, using the same saved server credentials. |
  29. | **Understand your data** | Browse tables, inspect columns, explain queries, export CSV/JSON, and compare schemas. |
  30. | **Control access** | Choose read-only mode, restrict connections, or disable tools. |
  31. | **Set up your client** | One guided command for Claude Code, Codex, and OpenCode. |
  32. ## Database Support
  33. **Supported execution paths**:
  34. - PostgreSQL (via `pg`)
  35. - MySQL / MariaDB (via `mysql2`)
  36. - SQL Server / MSSQL (via `mssql`)
  37. - SQLite (via `sqlite3` CLI)
  38. - ClickHouse (HTTP/HTTPS with keep-alive and zstd/gzip; no external client)
  39. - DuckDB (via DuckDB CLI 1.5.6+; existing local files, locked safe mode, exact numeric output)
  40. - Oracle (via `oracledb`)
  41. **Postgres-compatible** (routed through `pg` driver automatically):
  42. - CockroachDB, TimescaleDB, Amazon Redshift, YugabyteDB, AlloyDB, Supabase, Neon, Citus
  43. **Other databases**: Unsupported drivers return an explicit error. External GUI/CLI query fallback has been removed so access and output policies remain enforceable.
  44. DuckDB uses an installed CLI so its native binary stays out of the npm package. Install it with `brew install duckdb` on macOS, or use the [official downloads](https://duckdb.org/install/). Set `OMNISQL_DUCKDB_CLI` if the executable is outside your MCP client's PATH. See [database support](https://omnisql.srthkdev.com/docs/guides/databases/) for configuration and limits.
  45. **Custom drivers** wrapping any of the above are detected automatically — see [Custom and IAM-Authenticated Drivers](#custom-and-iam-authenticated-drivers).
  46. ## Requirements
  47. - Bun 1.4.3+, Node.js 22.15+ within 22.x, or Node.js 24+
  48. - A database connection or an existing DBeaver-compatible workspace
  49. ## Quick setup
  50. Run the guided installer, choose Claude Code, Codex, or OpenCode, and OmniSQL adds itself to that client's MCP configuration:
  51. ```bash
  52. npx -y omnisql-mcp@latest install
  53. ```
  54. The installer detects clients and offers direct database setup, an existing OmniSQL config, or selected DBeaver connections. Add multiple instances to one MCP server, each with its own read-only setting and table rules. Direct setup uses verified TLS by default; passwords are masked and saved only in a private local config (0600 on Unix), or referenced through environment variable names. No OmniSQL API key is needed. An agent with unrestricted file access can still read local config files. Start a new client session after setup.
  55. To add it to a specific client directly:
  56. ```bash
  57. npx -y omnisql-mcp@latest install claude
  58. npx -y omnisql-mcp@latest install codex
  59. npx -y omnisql-mcp@latest install opencode
  60. ```
  61. Registrations default to read-only. `install <client>` opens guided setup in a terminal. For noninteractive setup, provide `--config /path/to/connections.json`, or `--workspace /path/to/workspace --allow dev,analytics` for selected saved connections. Explicit config excludes workspace discovery. `--dry-run` previews registration; setup refuses to overwrite an existing entry or use symlink destinations.
  62. `--allow-writes` enables write tools. Direct JSON connections also need `readOnly: false`; imported connections retain their saved flag. Database grants and operator policy still apply. SSH requires a verified `known_hosts` entry by default; `OMNISQL_SSH_STRICT_HOST_KEY=false` explicitly allows unknown hosts for legacy setups.
  63. ### Native client commands
  64. You can also register the server using your client's own CLI:
  65. ```bash
  66. # Claude Code — available across projects
  67. claude mcp add --transport stdio --scope user omnisql --env OMNISQL_CONFIG_FILE=/absolute/path/connections.json -- npx -y omnisql-mcp@latest
  68. # Codex
  69. codex mcp add omnisql --env OMNISQL_CONFIG_FILE=/absolute/path/connections.json -- npx -y omnisql-mcp@latest
  70. # OpenCode v2 — available across projects
  71. opencode mcp add omnisql --global -- npx -y omnisql-mcp@latest
  72. ```
  73. These follow the [Claude Code](https://code.claude.com/docs/en/mcp), [Codex](https://developers.openai.com/codex/mcp), and [OpenCode v2](https://opencode.ai/v2/docs/mcp-servers) registration commands. OpenCode v1 users can add a local server through their MCP settings.
  74. ### Claude Desktop and Cursor
  75. Add the following MCP entry to Claude Desktop's `claude_desktop_config.json`, or Cursor's `mcp.json`:
  76. ```json
  77. {
  78. "mcpServers": {
  79. "omnisql": {
  80. "command": "npx",
  81. "args": ["-y", "omnisql-mcp@latest"],
  82. "env": { "OMNISQL_CONFIG_FILE": "/absolute/path/connections.json" }
  83. }
  84. }
  85. }
  86. ```
  87. On Windows, use `"command": "cmd"` and `"args": ["/c", "npx", "-y", "omnisql-mcp@latest"]` when your client cannot launch `npx` directly.
  88. ### Standalone install (macOS / Linux)
  89. For a local executable, including machines without Node.js:
  90. ```bash
  91. curl -fsSL https://omnisql.srthkdev.com/install.sh | bash
  92. ```
  93. Installs under `~/.local/share/omnisql-mcp` with a launcher at `~/.local/bin/omnisql-mcp`, without sudo. If Bun 1.4.3+ is unavailable, it downloads a private Bun runtime and verifies its SHA-256 checksum. Use the printed absolute launcher path as your MCP client's command. Run the installer again to upgrade; append `bash -s -- 3.0.0` in place of `bash` to pin a version. `OMNISQL_INSTALL_DIR` and `OMNISQL_BIN_DIR` choose other directories.
  94. ## One server, many instances
  95. Register OmniSQL once. Select `connectionId` in each tool call; select `database` to switch databases on PostgreSQL, MySQL/MariaDB, SQL Server, or ClickHouse. Each instance can have its own read-only setting, table policy, credentials, timeout, row/byte limits, and pool size.
  96. Set `OMNISQL_CONFIG_FILE` to your JSON configuration, or reuse discovered workspace connections. Explicit connections default to read-only. See the [multi-instance configuration guide](https://omnisql.srthkdev.com/docs/getting-started/configuration/) and [access policies](https://omnisql.srthkdev.com/docs/guides/access/).
  97. Large results use private, expiring handles with row and column pagination. Long cells and large exports can be read in bounded chunks. See [result paging](https://omnisql.srthkdev.com/docs/guides/usage-examples/#read-a-large-result-in-pages).
  98. ## Configuration
  99. ### Environment Variables
  100. | Variable | Description | Default |
  101. |----------|-------------|---------|
  102. | `OMNISQL_DISCOVER_WORKSPACE` | Include saved workspace connections | `false` with a config file; `true` otherwise |
  103. | `OMNISQL_CONFIG_FILE` | JSON configuration for multiple database instances and their settings | Unset |
  104. | `OMNISQL_POLICY_FILE` | Additional schema, table, function, and database access rules | Unset |
  105. | `OMNISQL_WORKSPACE` | Path to local DB client workspace directory | OS default |
  106. | `OMNISQL_PROJECT` | Restrict discovery to one DB client project/workspace folder | All projects |
  107. | `OMNISQL_TIMEOUT` | Query timeout (ms) | `30000` |
  108. | `OMNISQL_DEBUG` | Enable debug logging | `false` |
  109. | `OMNISQL_UPDATE_NOTIFIER` | Check npm for updates and show notices on stderr | `true` |
  110. | `OMNISQL_READ_ONLY` | Disable all write operations | `true` |
  111. | `OMNISQL_ALLOWED_CONNECTIONS` | Comma-separated whitelist of connection IDs or names | All |
  112. | `OMNISQL_DISABLED_TOOLS` | Comma-separated tools to disable | None |
  113. | `OMNISQL_POOL_MIN` | Minimum connections per pool | `0` |
  114. | `OMNISQL_POOL_MAX` | Maximum connections per pool | `4` |
  115. | `OMNISQL_POOL_IDLE_TIMEOUT` | Idle connection timeout (ms) | `30000` |
  116. | `OMNISQL_POOL_ACQUIRE_TIMEOUT` | Connection acquire timeout (ms) | `10000` |
  117. | `OMNISQL_AWS_CLI_PATH` | Path to the AWS CLI (used for RDS IAM authentication) | `aws` |
  118. | `OMNISQL_IAM_TOKEN_TIMEOUT` | Timeout for minting an RDS IAM auth token (ms) | `20000` |
  119. | `OMNISQL_SSH_KNOWN_HOSTS` | known_hosts file used to verify SSH tunnel hosts | `~/.ssh/known_hosts` |
  120. | `OMNISQL_SSH_STRICT_HOST_KEY` | Refuse SSH tunnel hosts with no `known_hosts` entry | `true` |
  121. ### Read-Only Mode
  122. Enabled by default and blocks all write operations. The `execute_query` tool only allows SELECT, EXPLAIN, SHOW, and DESCRIBE statements. Transaction tools are disabled entirely.
  123. ```json
  124. {
  125. "mcpServers": {
  126. "omnisql": {
  127. "command": "npx",
  128. "args": ["-y", "omnisql-mcp@latest"],
  129. "env": {
  130. "OMNISQL_READ_ONLY": "true"
  131. }
  132. }
  133. }
  134. }
  135. ```
  136. ### Connection Whitelist
  137. Restrict which workspace connections are visible. Accepts connection IDs or display names, comma-separated:
  138. ```json
  139. {
  140. "mcpServers": {
  141. "omnisql": {
  142. "command": "npx",
  143. "args": ["-y", "omnisql-mcp@latest"],
  144. "env": {
  145. "OMNISQL_ALLOWED_CONNECTIONS": "dev-postgres,staging-mysql"
  146. }
  147. }
  148. }
  149. }
  150. ```
  151. ### Disable Specific Tools
  152. ```json
  153. {
  154. "mcpServers": {
  155. "omnisql": {
  156. "command": "npx",
  157. "args": ["-y", "omnisql-mcp@latest"],
  158. "env": {
  159. "OMNISQL_DISABLED_TOOLS": "drop_table,alter_table,write_query"
  160. }
  161. }
  162. }
  163. }
  164. ```
  165. ## Available Tools
  166. ### Connection Management
  167. - `list_connections` - List all database connections
  168. - `list_databases` - Discover accessible databases on PostgreSQL, MySQL/MariaDB, SQL Server, and ClickHouse
  169. - `get_connection_info` - Get connection details
  170. - `test_connection` - Test connectivity
  171. ### Data Operations
  172. - `execute_query` - Run read-only queries (SELECT, EXPLAIN, SHOW, DESCRIBE only)
  173. - `write_query` - Run INSERT/UPDATE/DELETE
  174. - `export_data` - Export to CSV/JSON, with optional gzip, Brotli, or zstd
  175. - `read_result` - Read a page of stored rows and columns
  176. - `read_result_cell` - Read a long cell in chunks
  177. - `read_export` - Read a stored export in bounded base64 chunks
  178. Exports support optional gzip, Brotli, and zstd downloads through `export_data.compression`. Ordinary queries remain paginated JSON. [Measured compression and media changes](docs/benchmarks/2026-10-18-compression.md).
  179. ### Schema Management
  180. - `list_tables` - List tables and views
  181. - `get_table_schema` - Get columns, indexes, and constraints
  182. - `get_table_stats` - Get catalog row estimates and data/index storage
  183. - `create_table` - Create tables
  184. - `alter_table` - Modify tables
  185. - `drop_table` - Drop tables (requires confirmation)
  186. ### Transactions
  187. PostgreSQL, MySQL/MariaDB, and SQL Server support explicit transactions. Results obey the same row/byte limits and pagination as ordinary queries. Each transaction accepts one operation at a time; a failed query or changed connection/access policy rolls it back. Schema operations are excluded because some engines commit DDL implicitly. At most 32 transactions may be active or starting; idle transactions expire after one hour.
  188. - `begin_transaction` - Start a new transaction
  189. - `execute_in_transaction` - Execute query within a transaction
  190. - `commit_transaction` - Commit a transaction
  191. - `rollback_transaction` - Roll back a transaction
  192. ### Query Analysis
  193. - `explain_query` - Analyze query execution plan
  194. - `compare_schemas` - Compare schemas between two connections
  195. - `get_pool_stats` - Get connection pool statistics
  196. ### Other
  197. - `get_database_stats` - Database statistics
  198. - `append_insight` - Store analysis notes
  199. - `list_insights` - Retrieve stored notes
  200. ## Security
  201. - **Database permissions**: use a database account with read-only grants when you require a database-level permission boundary. The SQL checks are safeguards, not a full SQL sandbox.
  202. - **Read-only enforcement**: `execute_query` only accepts read-only statements (SELECT, EXPLAIN, SHOW, DESCRIBE, PRAGMA). Write operations must use `write_query`.
  203. - **Query validation**: Blocks DROP DATABASE, DROP SCHEMA, TRUNCATE, DELETE/UPDATE without WHERE, GRANT, REVOKE, and user management statements.
  204. - **Connection whitelist**: Restrict which connections are exposed via `OMNISQL_ALLOWED_CONNECTIONS`.
  205. - **Tool filtering**: Disable any tool via `OMNISQL_DISABLED_TOOLS`.
  206. - **Input sanitization**: Connection IDs and SQL identifiers are sanitized to prevent injection.
  207. - **Recommendation**: For production use, also use a database-level read-only user for defense in depth.
  208. ## Workspace Format Support
  209. Supports both configuration formats written by DBeaver-compatible DB clients:
  210. - Legacy: XML config in `.metadata/.plugins/org.jkiss.dbeaver.core/`
  211. - Modern: JSON config in `General/.dbeaver/`
  212. The project/workspace folder name (`General` by default) is configurable via `OMNISQL_PROJECT`,
  213. so workspaces using a custom or renamed DBeaver project (e.g. `DataPlatform`) are discovered
  214. without needing to rename the project or symlink the folder.
  215. ### Connection modes
  216. DBeaver connections are configured either **manually** (host, port, database fields) or by
  217. **URL** (a JDBC URL). Both work. In URL mode DBeaver leaves the host/port fields at placeholder
  218. values — usually `localhost` — and reads only the URL, so the URL is what is used here too.
  219. ### SSH tunnels
  220. Connections that DBeaver reaches through an SSH tunnel are tunneled here as well. The tunnel is
  221. opened on first use and reused for the lifetime of the server, with a loopback-only local
  222. forward, and the connection's host/port are treated the way DBeaver treats them: as the database
  223. *as seen from the SSH server*.
  224. - Agent, password and public-key authentication are supported, taken from the connection's SSH
  225. tab. Credentials saved in the workspace (including the tunnel's own, stored separately from
  226. the database credentials) are decrypted and used.
  227. - Agent authentication needs `SSH_AUTH_SOCK` set **in the MCP server's environment**. MCP clients
  228. usually do not inherit your shell, so set it explicitly in the client's server config if you
  229. use an agent.
  230. - SSH host keys must match a trusted entry in `known_hosts`; unknown hosts are refused by default.
  231. Verify the host fingerprint through a trusted channel before adding it.
  232. `OMNISQL_SSH_STRICT_HOST_KEY=false` allows unknown hosts explicitly; known-host mismatches still fail.
  233. - If a tunnel cannot be opened the connection fails with that reason. It never falls back to
  234. connecting directly to the recorded host, which would reach an unrelated local database.
  235. Table policies resolve real catalog names before checking access, including engine-specific case rules. Qualified denies also cover unqualified SQL; paged results and exports recheck permissions on every read. Restricted queries stay inside the selected database. See [access rules](https://omnisql.srthkdev.com/docs/guides/access/) for configuration and limits.
  236. ### Querying another database on the same server
  237. Use `list_databases` with a saved `connectionId` to discover databases accessible on a PostgreSQL, MySQL/MariaDB, SQL Server, or ClickHouse instance. Pass an optional `database` to `execute_query`, `export_data`, `explain_query`, `list_tables`, `get_table_schema`, `get_database_stats`, `test_connection`, or `get_pool_stats`:
  238. ```json
  239. {"connectionId": "my-pg-server", "database": "app_logs", "query": "SELECT count(*) FROM log"}
  240. ```
  241. The saved host, credentials, IAM, TLS, and SSH settings are reused. The saved connection is unchanged and pools remain separate for each database. The existing `connectionId: "my-pg-server/app_logs"` shorthand also works. File-backed engines such as SQLite require a separate saved connection for each file. Read-only checks and connection whitelists still apply; list a connection ID to allow its databases, or `connectionId/database` entries to restrict access to specific databases.
  242. ### Oracle
  243. Oracle runs through `oracledb` in Thin mode, so no Oracle Client is needed. Service names, SIDs,
  244. TNS aliases and connect descriptors are read from the connection. Rows are capped by the driver,
  245. using a bounded ResultSet fetch. Ordinary queries reuse an isolated, bounded pool; privileged sessions remain standalone. Explicit multi-call Oracle transactions are not available.
  246. ## Custom and IAM-Authenticated Drivers
  247. ### Custom drivers
  248. Native routing normally keys off the driver id (`postgres-jdbc`, `mysql8`). Custom drivers often use an
  249. opaque id instead — a UUID, say — which names no engine. Those connections are resolved by falling back
  250. to the connection's `provider` (`postgresql`, `mysql`, …) and then to the JDBC URL's sub-protocol,
  251. including wrapped ones such as `jdbc:aws-wrapper:postgresql://…`. A custom driver wrapping a supported
  252. engine therefore works with no extra configuration.
  253. If an engine still cannot be identified, the resulting error names both the driver id and the provider
  254. so you can see what was missing.
  255. ### AWS RDS IAM authentication
  256. Connections that authenticate with an RDS IAM token instead of a stored password are detected and
  257. handled automatically. Both shapes are recognised:
  258. - **AWS Advanced JDBC Wrapper** drivers, which record `wrapperPlugins: "iam"` alongside `awsProfile`
  259. and `iamRegion`.
  260. - The DB client's own **AWS IAM auth models**.
  261. For these connections OmniSQL:
  262. 1. Mints a token with `aws rds generate-db-auth-token` (via the AWS CLI, so SSO and role-chained
  263. profiles work as configured) and uses it as the password.
  264. 2. Caches each token for 13 minutes, under its 15-minute lifetime, and re-mints per physical
  265. connection so long-lived pools keep working.
  266. 3. Forces TLS, which RDS requires for IAM tokens.
  267. 4. Resolves the database username from the connection when present. Where it is absent, the username is
  268. derived from your AWS identity: either the per-developer role name (`<profile>-<user>`) or the
  269. assumed SSO session name.
  270. **Requirements**: the AWS CLI on `PATH` (or `OMNISQL_AWS_CLI_PATH`), a valid session for the
  271. connection's profile (`aws sso login --profile <profile>`), and network reachability to the endpoint.
  272. An expired SSO session produces an error naming the profile to re-authenticate.
  273. ## Try the demo
  274. The recording above captures a real Codex CLI session calling OmniSQL tools. It uses synthetic customers and orders from the isolated `.demo/` workspace. The integration script below creates the SQLite fixtures, then checks discovery, schema inspection, queries, exports, query plans, schema comparison, and blocked writes.
  275. ```bash
  276. bun install --frozen-lockfile
  277. bun run build
  278. bun run demo
  279. ```
  280. To also test PostgreSQL database discovery, database selection, and pool identities against a temporary local cluster:
  281. ```bash
  282. OMNISQL_DEMO_PG_BIN=/path/to/postgres/bin bun run demo -- --postgres
  283. ```
  284. The PostgreSQL cluster binds to loopback on a temporary port, uses a random password, and is stopped and deleted after the run. The SQLite examples stay under `.demo/` so you can connect a client to them. Existing workspaces are untouched. [Watch the Codex CLI session](assets/codex-session.mp4). See [recording details](assets/README.md).
  285. ## Updates
  286. Node setup registers `npx -y omnisql-mcp@latest`; Bun setup registers the current Bun executable with `x --bun --yes omnisql-mcp@latest`; restart the MCP client to pick up a new version. Running servers keep their current version until restarted. OmniSQL checks npm at most once a day and writes a short update notice to stderr when a newer version is available. The check sends no database settings or credentials. Set `OMNISQL_UPDATE_NOTIFIER=false` to disable it. Standalone installs update by rerunning the curl installer.
  287. ## Development
  288. Bun 1.4.3 is the development runtime and package manager. `bun.lock` covers the server and website workspace. Builds transpile with Bun; `bun run typecheck` remains required because transpilation does not check types. The published JavaScript also runs on Node 22+ for existing npm clients.
  289. ```bash
  290. git clone https://github.com/srthkdev/omnisql-mcp.git
  291. cd omnisql-mcp
  292. bun install --frozen-lockfile
  293. bun run build
  294. bun run test
  295. bun run lint
  296. ```
  297. ## Releases
  298. CI builds with Bun 1.4.3, runs native Bun tests, verifies the packed MCP server on Bun and Node.js 22/24/26, and checks dependencies. Seeded database and TLS fixtures run on both Bun and Node. It does not publish to npm.
  299. Maintainers release from a clean checkout after CI passes:
  300. ```bash
  301. bun install --frozen-lockfile
  302. bun run lint
  303. bun run typecheck
  304. bun run test
  305. bun run build
  306. bun run test:package
  307. bun audit --audit-level=high
  308. npm login
  309. npm publish --access public
  310. git tag vX.Y.Z
  311. git push origin vX.Y.Z
  312. ```
  313. Update the package version and changelog before publishing. Pushing the version tag creates the GitHub release; attach the release notes from the changelog. `npm pack` rebuilds `dist/` before packaging.
  314. ## License
  315. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

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