# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

## [3.0.0] - 2026-10-22

### Breaking changes and migration
- Read-only mode is now the default. To enable write tools, set `OMNISQL_READ_ONLY=false`; explicitly configured writable instances also need `readOnly: false`. Database permissions still provide the final authorization boundary.
- Unknown SSH host keys are rejected by default. Verify the server fingerprint and add its key to your private `known_hosts` before connecting. `OMNISQL_SSH_STRICT_HOST_KEY=false` is an explicit legacy opt-out.
- An explicit `OMNISQL_CONFIG_FILE` no longer imports unrelated DBeaver workspace connections. Set `OMNISQL_DISCOVER_WORKSPACE=true` only when you deliberately want both sources.
- Node support requires `^22.15.0 || >=24.0.0`; Bun 1.4.3+ supports builds, development and standalone installs.
- Connection metadata exposes logical IDs and safe labels instead of endpoint/user/file configuration. Unsafe discovered IDs receive opaque aliases; use the IDs returned by `list_connections`.
- Oracle and SQL Server timestamps above millisecond precision fail explicitly when the JavaScript driver cannot preserve them. Select exact text with Oracle `TO_CHAR` or SQL Server `CONVERT`/`CAST` as described in the database guide.

### Installer and security fixes
- Guided direct setup supports multiple instances and per-instance policies without DBeaver. Existing-config and optional DBeaver setup register Claude Code, Codex or OpenCode, retain credentials in private configuration/environment references, and refuse to overwrite existing client registration.
- Keep endpoints, usernames, credential properties and local connection paths out of public metadata, native errors and debug logs; authorized query values are returned unchanged.
- Bind private notes and cached results to effective connection/config/workspace/access identity. Bound private file reads through checked regular-file descriptors and reject symlinks and special files.
- Accept valid quoted catalog names, including hyphens, spaces, apostrophes and quoted dots (#79). Quote qualified DROP targets per dialect, and scan PostgreSQL array/subscript expressions without weakening SQL Server identifier handling.
- Add verified direct Oracle TCPS configuration and fail closed for unsupported TCPS/TNS/SSH combinations.

### Added
- ClickHouse HTTP/HTTPS queries, native read-only modes, verified TLS/client certificates, zstd/gzip transport, bounded results, catalogs, skipping indexes, physical keys, and estimated plans.
- DuckDB local-file queries, metadata, plans, exact nested numeric values, coordinated file access, and locked external-access controls. The installed DuckDB CLI 1.5.6+ keeps its native binary outside the npm package.
- Optional gzip, Brotli, and zstd exports with private chunked download handles.
- Ordered index and key metadata, catalog table/storage estimates, and a `get_table_stats` tool.
- Lazy connection-to-table-to-schema resources.
- Private expiring result handles, row/column pagination, long-cell reads, and bounded export chunks.
- Workspace-scoped private notes with atomic writes and a storage limit.
- Multiple explicitly configured database instances behind one MCP server, with separate read-only settings, credentials, access rules, timeouts, result limits, and pool sizes.
- A portable Rust SQL analyzer for schema/table policies across query tools, exports, transactions, and resources. npm installations include WebAssembly and need no Rust compiler.

### Changed
- Bun 1.4.3 handles development, builds, tests, and standalone installs. Published JavaScript also supports Node 22.15+ and 24+.
- Real Codex screenshots use lossless WebP; the site minifies CSS/JavaScript and defers the demo video until playback.
- Oracle metadata arguments now use exact catalog names, preserving quoted table case.
- CLI help/version commands avoid loading the MCP server; SQL drivers load only when used. Local benchmarks and reproduction commands are documented under `docs/benchmarks/`.
- CLI release packages omit development source maps and type declarations.
- Ordinary PostgreSQL, MySQL/MariaDB, and SQL Server queries reuse isolated connection pools.
- Native SQL drivers collect results within row and byte budgets rather than rewriting SQL with LIMIT/TOP.
- Connection names retain spaces and Unicode; ambiguous workspace IDs fail instead of silently selecting one project.
- SSH forwards track transport failures and close active sockets during shutdown.


### Fixed
- Page large catalog documents and bind schema comparisons to both source connections. Reject incomplete catalog discovery and bound comparison work by table count, catalog bytes, and checks between batches.
- Bound concurrent cached-result reads, count escaped UTF-8 previews and headers, and label serialized JSON cells for exact reconstruction.
- Preserve exact nested JSON numbers, PostgreSQL NUMERIC arrays, and sub-millisecond PostgreSQL/MySQL timestamps without global driver changes.
- Read Oracle LOBs in bounded pieces, close skipped locators, and share the remaining query deadline across fetches.
- Reject malformed UTF-8 and incomplete embedded-engine JSON; keep file locks until failed or timed-out processes close.
- Apply database-specific policies to configured defaults, confine cross-database SQL, and require exact declared database selections on engines with configurable name collations.
- Bind cached result/export handles to their original connection settings and application policy revision.
- Accept the database argument consistently on write, schema, and transaction-start tools.
- Incomplete catalog details are marked partial; schema comparisons reject incomplete inputs. Nested warehouse types and enum literal case survive comparisons, and embedded newlines cannot escape migration-review comments.
- CTE aliases use dialect-specific ASCII folding; differently cased physical references cannot disappear from table policy analysis.
- Access policies resolve actual catalog identities and native case rules, cover qualified denies and selected-database scope, and recheck stored results/exports.
- Policy lookups share one round trip for joins and reuse transaction leases, including pools limited to one connection.
- MySQL/MariaDB metadata distinguishes case-sensitive table names; SQL Server table discovery works with case-sensitive catalogs.
- Transactions bound row/byte output, preserve duplicate columns, and roll back after policy changes or query errors.
- Certificate hostname verification survives SSH forwarding for PostgreSQL, MySQL, and SQL Server; unreadable explicit TLS material fails closed.
- IAM authentication defaults to verified TLS when no mode is specified.
- Schema comparisons now preserve qualified names, case, type dimensions, indexes, and constraints. Migration previews are explicitly commented review outlines.
- Connection responses omit raw properties and embedded credentials; debug logs omit SQL and analysis text.
- Tool calls validate arguments without coercion, SQL guards reject stacked DDL and comment-only WHERE clauses, and read tools block known side-effect functions.
- Saved read-only connections reject write tools. PostgreSQL, MySQL/MariaDB, and Oracle use read-only query transactions; SQLite queries have a process deadline and output safety cap.
- SQL Server queries use an isolated pool with cleanup and configured TLS settings. Revoked SSH keys take precedence; disabled TLS is rejected for IAM authentication.

- Replaced Docusaurus with a custom static website, searchable documentation, and client setup commands.
- Rewrote the database, configuration, tool, and access guides; added site link and media checks to CI.
- Replaced the illustrated walkthrough with a real Codex CLI session and included its terminal capture.
- Updated the logo, README, and site colors.

## [2.2.0] - 2026-10-18

### Added
- Update notices check npm once a day, write only to stderr, and support `OMNISQL_UPDATE_NOTIFIER=false`.
- Integration demo using isolated SQLite and PostgreSQL fixtures, with README media.
- Guided `npx omnisql-mcp install` setup for Claude Code, Codex, and OpenCode, with workspace, read-only, and connection allowlist prompts.
- **Native Oracle support** via `oracledb` in Thin mode. Oracle connections previously fell through to the CLI fallback and failed.

- Optional `database` argument on query, export, explain, metadata, connection test, and pool statistics tools; `list_databases` discovers accessible databases on PostgreSQL, MySQL/MariaDB, and SQL Server (#33).
- One-command macOS/Linux installer at `https://srthkdev.github.io/omnisql-mcp/install.sh`, with a private Node.js runtime when needed.

### Fixed
- MySQL TLS settings now honor DBeaver's enabled SSL handler, certificate paths, and verification choice while preserving explicit driver properties (#31).
- Read-only checks reject stacked statements, write CTEs, SELECT INTO, and mutating PRAGMAs; export and read-only EXPLAIN calls use the same checks. SQLite runs in CLI safe mode.
- SQLite result parsing preserves commas, newlines, numbers, and nulls; schema flags and query plans are read correctly. SQL is passed as an argument so CLI dot commands cannot run through multiline input.
- Table listings expose a consistent name for schema comparison.
- Oracle SQL delimiters and metadata parsing; TNS aliases reject SSH configurations they cannot honor.
- Release packaging rebuilds compiled files before packing; CI exercises the packed server, custom workspace projects (#30), read-only checks, and whitelists.
- Updated dependencies to clear reported vulnerabilities and removed the shell helper from the build.
- npm publishing is manual; CI validates builds, tests, packaged runtime compatibility, the installer, and dependency audits.

## [2.1.0] - 2026-08-29

First release carrying the connection-handling work that had accumulated on `main`. Notably, `OMNISQL_PROJECT` was documented before it shipped (#30) - it is in this release.

### Added
- **AWS RDS IAM authentication**: Connections that authenticate with an IAM token instead of a stored password now work natively, for both PostgreSQL and MySQL. Tokens are minted with `aws rds generate-db-auth-token` (so SSO and role-chained profiles work as configured), cached for 13 minutes under their 15-minute lifetime, and re-minted per physical connection so long-lived pools keep working. TLS is forced for these connections, as RDS requires. Recognised from AWS Advanced JDBC Wrapper properties (`wrapperPlugins: "iam"`) or an `iam` auth model.
- **Database username derivation**: When an IAM connection records no username, it is derived from the caller's AWS identity — either the per-developer role name (`<profile>-<user>`) or the assumed SSO session name.
- **Custom driver support**: Drivers with an opaque id (a UUID, for instance) now route to the right native driver by falling back to the connection's `provider` and then the JDBC URL sub-protocol, including wrapped protocols such as `jdbc:aws-wrapper:postgresql://`. Previously any such driver fell through to the CLI fallback and failed.
- **SSH tunnel support** (#28): connections that DBeaver reaches through an SSH tunnel are now tunneled here too, rather than connecting straight to the target host — which for a tunneled connection is the database *as seen from the SSH server*, usually `localhost`. Agent, password and public-key authentication are supported, including tunnel credentials stored separately from the database credentials in the workspace. The forward binds loopback only, is shared between the direct-query and pooled paths, and is closed on shutdown. A tunnel that cannot be opened fails with that reason instead of falling through to the recorded host.
- **SSH host key verification**: tunnel hosts are checked against `known_hosts`. A recorded host must match; an unrecorded one is accepted unless `OMNISQL_SSH_STRICT_HOST_KEY=true`.
- **Database override syntax** (#24, thanks @rrsela): a connection id may carry `\<connection\>/\<database\>` to query another database on the same server without adding a second connection. Not applicable to file-backed engines such as SQLite, where the database is a file path.
- **Multi-project workspaces**: connections are now read from every project directory in the workspace, each paired with its own credentials, instead of only `General`. `OMNISQL_PROJECT` (#27, thanks @zerafachris) still pins reading to one project, and `get_connection_info` debug output lists the projects found.
- New `OMNISQL_AWS_CLI_PATH`, `OMNISQL_IAM_TOKEN_TIMEOUT`, `OMNISQL_PROJECT`, `OMNISQL_SSH_KNOWN_HOSTS` and `OMNISQL_SSH_STRICT_HOST_KEY` environment variables.

### Fixed
- **MySQL TLS options were read from the wrong place**: only top-level connection properties were checked, so the nested `properties` block written by the JSON workspace format was ignored. PostgreSQL already handled both.
- **MySQL `ssl-mode` semantics**: `REQUIRED` now encrypts without validating the certificate chain, per MySQL's documented behaviour, and only the `VERIFY_CA`/`VERIFY_IDENTITY` modes verify it. Previously `REQUIRED` implied full verification, which fails against managed engines whose CA is not in the system trust store. `REQUIRED`/`DISABLED` spellings are also recognised now.
- **URL-mode connections connected to localhost** (#26): a connection configured by JDBC URL keeps its host/port fields at placeholder values that DBeaver never reads. Reading them meant every URL-mode connection failed with `ECONNREFUSED`, or silently reached whatever was listening on that port locally. `configurationType` now decides which side is authoritative, as DBeaver does.
- **Host, port and database are backfilled from the JDBC URL** when a connection config omits them. URL parsing now also handles SQL Server `;databaseName=` tails, both Oracle address forms, file-backed URLs, credentials in the authority, failover host lists and IPv6 literals.
- **SQLite queries could crash the server** (#25, thanks @aneeskodappana): a missing or non-executable `sqlite3` binary emitted an unhandled `error` event — on the child process and again on its stdin — which took the whole server down instead of failing the one tool call.
- **Custom drivers registered under a UUID could resolve to the wrong dialect**: `db2` is a valid hex triple, so a UUID containing it was treated as naming a dialect and its `provider` was ignored.
- Unsupported-driver errors now name the raw driver id and provider alongside the resolved driver, instead of only the resolved one.

### Internal
- TLS resolution is now shared between the direct-query and pooled connection paths, which previously read different property locations and disagreed about what `require` meant.

## [2.0.1] - 2026-04-20

### Changed
- **Package size reduced from 306 kB to 60 kB**: added a `files` whitelist in `package.json` so the npm tarball no longer includes `docs-site/`, `tests/`, `scripts/`, `examples/`, or local runtime logs. Only `dist/`, `README.md`, `CHANGELOG.md`, and `LICENSE` are published.

## [2.0.0] - 2026-04-20

### Changed (Breaking)
- **Renamed package**: `dbeaver-mcp-server` → `omnisql-mcp`. The old npm package is deprecated; install `omnisql-mcp` going forward.
- **Renamed binary**: `dbeaver-mcp-server` → `omnisql-mcp`.
- **Renamed environment variables**: All `DBEAVER_*` env vars are now `OMNISQL_*` (for example, the old `DBEAVER_READ_ONLY` is now `OMNISQL_READ_ONLY`, old `DBEAVER_WORKSPACE` is now `OMNISQL_WORKSPACE`, and old `DBEAVER_PATH` is now `OMNISQL_CLI_PATH`). Update your MCP client config.
- **Renamed resource URI scheme**: `dbeaver://` → `omnisql://` for table schema resources.
- **Renamed internal classes**: `DBeaverConfigParser` → `WorkspaceConfigParser`, `DBeaverClient` → `WorkspaceClient`, `DBeaverMCPServer` → `OmniSQLMCPServer`. Interfaces `DBeaverConnection` → `DatabaseConnection`, `DBeaverConfig` → `WorkspaceConfig`.
- **CLI auto-detection removed**: `OMNISQL_CLI_PATH` must now be set explicitly to use the CLI fallback for unsupported drivers. Previously the server attempted to locate the DB client binary in hardcoded install paths.

Functional behavior is otherwise unchanged — the server still reads connections from the same local DB client workspace (DBeaver-compatible).

## [1.3.0] - 2026-02-16

### Added
- **Postgres-compatible driver routing**: CockroachDB, TimescaleDB, Redshift, YugabyteDB, AlloyDB, Supabase, Neon, and Citus now route through the native PostgreSQL driver automatically
- **CI auto-publish**: Every push to `main` with a new version automatically publishes to npm and creates a git tag
- **Stale transaction cleanup**: Periodic cleanup (every 5 minutes) automatically rolls back transactions older than 1 hour
- **Graceful shutdown improvements**: Active transactions are rolled back before connection pools are closed
- `rollbackAll()` method on TransactionManager for shutdown scenarios

### Fixed
- **Credential leak (Security)**: `list_connections` with `includeDetails=true` and `get_connection_info` no longer expose passwords — all sensitive fields are redacted
- **Debug log credential leak (Security)**: Tool arguments are redacted before debug logging to prevent passwords appearing in logs
- **Pool creation race condition**: Concurrent `getPool()` calls for the same connection no longer create duplicate pools — uses a pending-creation map for deduplication
- **Transaction resource leak**: Failed `commit`/`rollback` now releases the database client back to the pool instead of leaking it
- **Insights file unbounded growth**: Capped at 1,000 entries, oldest entries are trimmed on save

### Changed
- CI workflow now includes a `publish` job that runs after all checks pass on `main`
- Pool manager's `isPostgresCompatible()` is now a public method shared with workspace-client

## [1.2.5] - 2026-02-15

### Added
- Connection whitelist via `OMNISQL_ALLOWED_CONNECTIONS` environment variable — restrict which workspace connections are visible by ID or name
- `enforceReadOnly()` query-level enforcement — `execute_query` now strictly allows only read-only statements (SELECT, EXPLAIN, SHOW, DESCRIBE, PRAGMA)
- Test queries for SAP HANA (`SELECT * FROM DUMMY`) and DB2 (`SYSIBM.SYSDUMMY1`)

### Fixed
- **Read-only mode bypass (Issue #19)**: `execute_query` no longer allows write operations (INSERT/UPDATE/DELETE/CREATE/ALTER/DROP). Transaction tools (`begin_transaction`, `commit_transaction`, `rollback_transaction`, `execute_in_transaction`) are now blocked in read-only mode.
- **Unsupported driver errors (Issue #17)**: CLI fallback now provides clear, actionable error messages listing natively supported drivers and workarounds. CLI availability is checked before attempting fallback.
- **UPDATE validation regex**: `UPDATE ... SET ... WHERE ...` was incorrectly blocked by the dangerous query filter. The regex now correctly allows UPDATE with WHERE clause.

### Changed
- CLI fallback uses connection name-based spec for better compatibility

## [1.2.4] - 2026-01-15

### Added
- Native MySQL/MariaDB support via `mysql2` library
- Read-only mode (`OMNISQL_READ_ONLY=true`) to disable write operations
- Tool filtering via `OMNISQL_DISABLED_TOOLS` environment variable
- GitHub Actions CI/CD pipeline
- ESLint and Prettier configuration
- Pre-commit hooks via Husky
- Vitest test framework
- Issue and PR templates
- Connection pooling for PostgreSQL, MySQL, and MSSQL with configurable pool settings
- Transaction support with `begin_transaction`, `commit_transaction`, `rollback_transaction`, and `execute_in_transaction` tools
- Query explain tool (`explain_query`) for analyzing query execution plans
- Schema comparison tool (`compare_schemas`) for diffing schemas between connections
- Pool statistics tool (`get_pool_stats`) for monitoring connection pool health

### Changed
- Upgraded `@modelcontextprotocol/sdk` from 1.9.0 to 1.25.2 (security fix)
- Improved error messages for unsupported database drivers
- Better trailing semicolon handling in LIMIT clause

### Fixed
- Security vulnerabilities in dependencies
- `@types/mssql` moved to devDependencies
- SQL injection vulnerability in table/schema name handling
- Deprecated `.substr()` replaced with secure `crypto.randomBytes()`
- Added maxRows validation with upper bounds (100k query, 1M export)
- Removed unsupported export formats (xml, excel) from API schema

## [1.2.3] - 2026-01-07

### Added
- Native MSSQL/SQL Server support via `mssql` library
- `xml2js` for legacy XML workspace config parsing

### Fixed
- Missing `xml2js` runtime dependency that broke npm installations
- PostgreSQL connection cleanup logging

## [1.2.2] - 2024-12-XX

### Added
- SSL/TLS support for PostgreSQL connections
- Credential decryption from the workspace credentials-config.json

### Fixed
- Authentication failures with PostgreSQL (Issue #8)

## [1.2.0] - 2024-10-XX

### Added
- Native PostgreSQL support via `pg` library
- Native SQLite support via sqlite3 CLI
- CLI fallback for unsupported drivers
- Business insights tracking feature

### Changed
- Query execution no longer requires the DB client GUI for supported databases

## [1.1.0] - 2024-09-XX

### Added
- Initial MCP server implementation
- Support for legacy XML and modern JSON workspace config formats
- Connection management tools
- Query execution tools
- Schema management tools
- Data export functionality