Show HN: I forked usql into a MCP server

usql is a universal command-line interface for PostgreSQL, MySQL, Oracle Database, SQLite3, Microsoft SQL Server, and many other databases including NoSQL and non-relational databases!

usql provides a simple way to work with SQL and NoSQL databases via a command-line inspired by PostgreSQL's psql. usql supports most of the core psql features, such as variables, backticks, backslash commands and has additional features that psql does not, such as multiple database support, copying between databases, syntax highlighting, context-based completion, and terminal graphics.

Database administrators and developers that would prefer to work with a tool like psql with non-PostgreSQL databases, will find usql intuitive, easy-to-use, and a great replacement for the command-line clients/tools for other databases.

This is a fork of usql that adds server capabilities with Model Context Protocol (MCP) support.

usqlr transforms the powerful usql CLI tool into a server that can manage multiple database connections simultaneously and exposes them through the Model Context Protocol (MCP). This enables AI assistants and other applications to interact with databases programmatically while maintaining all of usql's extensive database driver support.

• Server Mode: Run as a persistent server instead of a CLI tool
• MCP Protocol: Full JSON-RPC 2.0 compliant MCP implementation for AI integration
• Multi-Connection: Manage multiple database connections concurrently
• All usql Drivers: Supports the same 70+ database drivers as usql
• HTTP API: RESTful endpoints for health checks and connection management
• Container Support: Easy database testing with Docker/Podman integration

Build the server binary using the included Makefile:

The project includes comprehensive tests for both SQLite integration and multi-database driver support:

For detailed testing information, see the Testing README.

Start the usqlr server:

The server exposes:

• MCP Protocol: POST /mcp - JSON-RPC 2.0 endpoint for AI integration
• Health Check: GET /health - Server health and connection status
• Connection Management: REST API for database operations

The server implements the full MCP specification with tools for:

• create_connection - Create new database connections
• execute_query - Execute SQL queries with results
• execute_statement - Execute SQL statements (INSERT, UPDATE, DELETE)
• close_connection - Close database connections

Example MCP request:

usql can be installed via Release, via Homebrew, via AUR, via Scoop, via Go, or via Docker:

1. Download a release for your platform
2. Extract the usql or usql.exe file from the .tar.bz2 or .zip file
3. Move the extracted executable to somewhere on your $PATH (Linux/macOS) or %PATH% (Windows)

Install usql from the xo/xo tap in the usual way with the brew command:

Support for ODBC databases is available through the --with-odbc install flag:

Install usql from the Arch Linux AUR in the usual way with the yay command:

Alternately, build and install using makepkg:

Install usql using Scoop:

Install usql in the usual Go fashion:

See below for information on usql build tags.

An official container image (docker.io/usql/usql) is maintained by the usql team, and can be used with Docker, Podman, or other container runtime.

Install usql with Docker, Podman, or other container runtime:

When building usql out-of-the-box with go build or go install, only the base drivers for PostgreSQL, MySQL, SQLite3, Microsoft SQL Server, Oracle, CSVQ will be included in the build:

Other databases can be enabled by specifying the build tag for their database driver.

For every build tag <driver>, there is also a no_<driver> build tag that will disable the driver:

By specifying the build tags most or all, the build will include most, and all SQL drivers, respectively:

usql works with all Go standard library compatible SQL drivers supported by github.com/xo/dburl.

The list of drivers that usql was built with can be displayed with the \drivers command:

The above shows that usql was built with only the mysql, cassandra (ie, cql), and moderncsqlite drivers. The output above reflects information about the drivers available to usql, specifically the internal driver name, its primary URL scheme, the driver's available scheme aliases (shown in [...]), and the real/underlying driver (shown in (...)) for wire compatible drivers.

The following are the Go SQL drivers that usql supports, the associated database, scheme / build tag, and scheme aliases:

^† Requires CGO
^‡ Wire compatible (see respective driver)

Any of the protocol schemes/aliases above can be used in conjunction when connecting to a database via the command-line or with the \connect and \copy commands:

See the section below on connecting to databases for further details building DSNs/URLs for use with usql.

After installing, usql can be used similarly to the following:

Supported command-line options:

usql opens a database connection by parsing a URL and passing the resulting connection string to a database driver. Database connection strings (aka "data source name" or DSNs) have the same parsing rules as URLs, and can be passed to usql via command-line, or to the \connect, \c, and \copy commands.

Database connections can be defined with the \cset command or in the config.yaml configuration file.

Database connection strings look like the following:

Where the above are:

^± Some databases, such as Microsoft SQL Server, or Oracle Database support a path component (ie, /dbname) in the form of /instance/dbname, where /instance is the optional service identifier (aka "SID") or database instance

usql supports the same driver names and aliases as the dburl package. Databases have at least one or more aliases. See dburl's scheme documentation for a list of all supported aliases.

All database drivers have a two character short form that is usually the first two letters of the database driver. For example, pg for postgres, my for mysql, ms for sqlserver, or for oracle, or sq for sqlite3.

Driver options are specified as standard URL query options in the form of ?opt1=a&opt2=b. Refer to the relevant database driver's documentation for available options.

If a URL does not have a driver: scheme, usql will check if it is a path on disk. If the path exists, usql will attempt to use an appropriate database driver to open the path.

When the path is a Unix Domain Socket, usql will attempt to open it with the MySQL driver. When the path is a directory, usql will attempt to open it using the PostgreSQL driver. And, lastly, when the path is a regular file, usql will attempt to open the file using the SQLite3 or DuckDB drivers.

As with URLs, most components in the URL are optional and many components can be left out. usql will attempt connecting using defaults where possible:

See the relevant documentation on database drivers for more information.

The following are example connection strings and additional ways to connect to databases using usql:

See the section on connection variables for information on defining connection names.

The interactive interpreter reads queries and backslash meta (\) commands, sending the query to the connected database:

Commands may accept one or more parameter, and can be quoted using either ' or ". Command parameters may also be backticked.

usql supports interleaved backslash (\) meta commands to modify or alter the way that usql interprets queries, formats its output, and changes the resulting interactive flow.

Available backslash meta commands can be displayed with \?:

Parameters passed to commands can be backticked.

An overview of usql's features, functionality, and compatibility with psql:

• Configuration
• Variables
• Backticks
• Copying Between Databases
• Syntax Highlighting
• Time Formatting
• Context Completion
• Host Connection Information
• Passwords
• Runtime Configuration (RC) File

The usql project's goal is to support as much of psql's core features and functionality, and aims to be as compatible as possible - contributions are always appreciated!

During its initialization phase, usql reads a standard YAML configuration file config.yaml. On Windows this is %AppData%/usql/config.yaml, on macOS this is $HOME/Library/Application Support/usql/config.yaml, and on Linux and other Unix systems this is normally $HOME/.config/usql/config.yaml.

Named connection DSNs can be defined under connections: as a string or as a map:

Defined connections: can be used on the command-line with \connect, \c, \copy, and other commands:

An initialization script can be defined as init: as a string:

The init: script is commonly used to set environment variables or other configuration, and can be disabled on the command-line using the --no-init / -X flag. The script will be executed prior to any -c / --command / -f / --file flag and before starting the interactive interpreter.

Please see contrib/config.yaml for an overview of available configuration options.

usql supports runtime, connection, and display formatting variables that can be \set, \cset, or \pset respectively.

Runtime variables are managed with the \set and \unset commands:

Runtime variables can be displayed with \set:

When a runtime variable NAME has been \set, then :NAME, :'NAME', and :"NAME" will be interpolated into the query buffer:

Where a runtime variable is used as :'NAME' or :"NAME" the interpolated value will be quoted using ' or " respectively:

The query buffer and interpolated values can be displayed with \p and \print, or the raw query buffer can be displayed with \raw:

Note

Variables contained within other strings will not be interpolated:

Connection variables work similarly to runtime variables, and are managed with \cset. Connection variables can be used with the \c, \connect, \copy, or other commands:

Connection variables are not interpolated into queries. See the configuration section for information on defining persistent connection variables.

Connection variables can be displayed with \cset:

Display formatting variables can be set using \pset and other commands:

Display formatting variables can be displayed with \pset:

Runtime behavior, such as enabling or disabling syntax highlighting can be modified through special variables like SYNTAX_HL.

Use the \? variables command to display variable help information and to list special variables recognized by usql:

Backslash (\) meta commands support backticks on parameters:

Backticked parameters will be passed to the user's SHELL, exactly as written, and can be combined with \set:

usql provides a \copy command that reads data from a source database DSN and writes to a destination database DSN:

As demonstrated above, the \copy command does not require being connected to a database, and will not modify or change the current open database connection or state.

Any valid URL or DSN name maybe used for the source and destination database:

Note

usql's \copy is distinct from and does not function like psql's \copy.

The \copy command has two parameter forms:

Where:

• SRC - is the source database URL to connect to, and where the QUERY will be executed
• DST - is the destination database URL to connect to, and where the destination TABLE resides
• QUERY - is the query to execute on the SRC connection, the results of which will be copied to TABLE
• TABLE - is the destination table name, followed by an optional SQL-like column list of the form (COL1, COL2, ..., COLN)
• (COL1, COL2, ..., COLN) - a list of the destination column names, 1-to-N

The usual rules for variables, interpolation, and quoting apply to \copy's parameters.

QUERY and TABLE must be quoted when containing spaces:

The QUERY must return the same number of columns as defined by the TABLE expression:

The \copy command does not attempt to perform any kind of datatype conversion.

If a QUERY returns columns with different datatypes than expected by the TABLE's column, the QUERY can use the source database's conversion/casting functionality to cast columns to a datatype that will work for TABLE's columns:

The \copy command is capable of importing data from CSV's (or any other database!) using the csvq driver:

Note

When importing large datasets (> 1GiB) from one database to another, it is better to use a database's native clients and tools.

The \copy command (and all usql commands) works with variables. When scripting, or when needing to perform multiple \copy operations from/to multiple sources/destinations, the best practice is to \set connection variables either in a script or in the $HOME/.usqlrc RC script.

Similarly, passwords can be stored for easy reuse (and kept out of scripts) by storing in the $HOME/.usqlpass password file.

For example:

Interactive queries will be syntax highlighted by default, using Chroma. There are a number of variables that control syntax highlighting:

The SYNTAX_* variables are regular usql variables, and can be \set and \unset:

When using the interactive shell, context completion is available in usql by hitting the <Tab> key. For example, hitting <Tab> can complete some parts of SELECT queries on a PostgreSQL databases:

Or, for example completing backslash commands while connected to a database:

Not all commands, contexts, or databases support completion. If you're interested in helping to make usql's completion better, see the section below on contributing.

Command completion can be canceled with <Control-C>.

Some databases support time/date columns that support formatting. By default, usql formats time/date columns as RFC3339Nano, and can be set using \pset time FORMAT:

usql's time format supports any Go supported time format, or can be any standard Go const name, such as Kitchen above. See below for an overview of the available time constants.

The following are the time constant names available in usql, corresponding time format value, and example display output:

^↓ Generated using timestamp 2022-08-03T20:12:48.693257Z

By default, usql displays connection information when connecting to a database. This might cause problems with some databases or connections. This can be disabled by setting the system environment variable USQL_SHOW_HOST_INFORMATION to false:

SHOW_HOST_INFORMATION is a standard usql variable, and can be \set or \unset. Additionally, it can be passed via the command-line using -v or --set:

usql supports terminal graphics for Kitty, iTerm, and Sixel enabled terminals using the github.com/kenshaw/rasterm package. Terminal graphics are only available when using the interactive shell.

usql will attempt to detect when terminal graphics support is available using the USQL_TERM_GRAPHICS, TERM_GRAPHICS and other environment variables unique to various terminals.

When support is available, the logo will be displayed at the start of an interactive session:

The \chart command can be used to display a chart directly in the terminal:

See the section on the \chart meta command for details.

Terminal graphics can be forced enabled or disabled by setting the USQL_TERM_GRAPHICS or the TERM_GRAPHICS environment variable:

The following terminals have been tested with usql:

• WezTerm is a cross-platform terminal for Windows, macOS, Linux, and many other platforms that supports iTerm graphics

• iTerm2 is a macOS terminal that supports iTerm graphics

• kitty is a terminal for Linux, macOS, and various BSDs that supports Kitty graphics

• foot is a Wayland terminal for Linux (and other Wayland hosts) that supports Sixel graphics

Additional terminals that support Sixel graphics are catalogued on the Are We Sixel Yet? website.

usql supports reading passwords for databases from a .usqlpass file contained in the user's HOME directory at startup:

While the .usqlpass functionality will not be removed, it is recommended to define named connections preferably via the config.yaml file.

Note

The .usqlpass file cannot be readable by other users, and the permissions should be set accordingly:

usql supports executing a .usqlrc runtime configuration (RC) file contained in the user's HOME directory:

The .usqlrc file is read at startup in the same way as a file passed on the command-line with -f / --file. It is commonly used to set startup environment variables and settings.

RC-file execution can be temporarily disabled at startup by passing -X or --no-init on the command-line:

While the .usqlrc functionality will not be removed, it is recommended to set an init script in the config.yaml file.

The following are additional notes and miscellania related to usql:

Release builds are built with the most build tag and with additional SQLite3 build tags (see: build.sh).

The recommended installation method on macOS is via brew due to the way library dependencies for the sqlite3 driver are done on macOS. If the following (or similar) error is encountered when attempting to run usql:

Then missing library dependency can be fixed by installing icu4c using brew:

usql is currently a WIP, and is aiming towards a 1.0 release soon. Well-written PRs are always welcome -- and there is a clear backlog of issues marked help wanted on the GitHub issue tracker! For technical details on contributing, see CONTRIBUTING.md.

Pick up an issue today, and submit a PR tomorrow!

• dburl - Go package providing a standard, URL-style mechanism for parsing and opening database connection URLs
• xo - Go command-line tool to generate Go code from a database schema