uroboroSQL-fmt for VSCode

A Visual Studio Code extension for uroboroSQL-fmt that is a tool that formats SQL statements according to SQL coding standards created by Future Corporation (Japanese only).

Features

• Format SQL documents and selections.
• Format SQL embedded in non-SQL files via the Format Selection as SQL command.
• Lint diagnostics for SQL files, shown when a lint configuration can be resolved. See Lint.
• Checks that tables and columns exist in your PostgreSQL schema (catalog checks, Beta).
• Quick fixes for lint diagnostics (add a uroborosql-lint-disable-next-line directive, or remove an unknown rule name from a directive).
• Per-folder formatter and lint configuration resolution in multi-root workspaces.

Usage

Once installed in Visual Studio Code, "uroborosql-fmt" will be available as a formatter for SQL files. Please select "uroborosql-fmt" (extension id:Future.uroborosql-fmt) as the default formatter. You can do this either by using the context menu (right click on a open SQL file in the editor) and select "Format Document With...", or you can add the following to your settings:

{
  "[sql]": {
    "editor.defaultFormatter": "Future.uroborosql-fmt"
  }
}

Format on save

You can enable format on save for SQL by having the following values in your settings:

{
  "[sql]": {
    "editor.defaultFormatter": "Future.uroborosql-fmt",
    "editor.formatOnSave": true
  }
}

Lint (Beta)

Lint diagnostics are shown only when a lint configuration file is found. Without one, the extension only formats and never connects to a database.

1. Create .uroborosqllintrc.json in the workspace folder. An empty object enables all rules with their default severities:

   {}
   

   You can also create it with uroborosql-lint --init if you have the uroborosql-lint CLI. To use a file in another location, set uroborosql-fmt.lintConfigurationFilePath.

2. Open or save a SQL file. Diagnostics appear in the editor and the Problems panel. Lint runs on open and save, not while typing.

If the lint configuration file cannot be read (for example, invalid JSON), no lint diagnostics are shown and the reason is written to the Uroborosql-fmt output channel. Formatting keeps working.

Use rules to change severities (off / warn / error), ignore to skip files, and overrides for per-file settings:

{
  "rules": {
    "no-distinct": "error",
    "no-wildcard-projection": "off"
  },
  "ignore": ["dist/**"]
}

See the uroborosql-lint README for the list of rules, their default severities, and all configuration options. To suppress a diagnostic for one line, use the quick fix or write -- uroborosql-lint-disable-next-line <rule> above it.

Catalog checks

Lint rules are either rules that check the SQL alone or rules that also use the database catalog. The rule list shows which rules use the catalog. Rules that use the catalog run only when the lint configuration has a db section; without one, no database is read. SQL is never executed.

There are two ways to provide the catalog.

Catalog snapshot (recommended for regular use). Someone with database access exports a SQLite snapshot with the uroborosql-lint CLI and shares it, for example by committing it to the repository. The snapshot contains object names, not data rows or passwords.

uroborosql-lint export-catalog --host localhost --user catalog_reader --dbname app --output catalog.sqlite

{
  "db": {
    "schemaProvider": "file",
    "path": "catalog.sqlite"
  }
}

path is relative to the directory of the lint configuration file. The editor needs no database connection or credentials. The snapshot is not updated automatically; export it again after schema changes. The new snapshot is used from the next open or save.

Direct connection. Useful for trying catalog checks out. The extension connects to PostgreSQL 14–18 on every check.

{
  "db": {
    "schemaProvider": "server",
    "host": "localhost",
    "user": "catalog_reader",
    "dbname": "app",
    "tlsMode": "disable"
  }
}

The password is read from the PGPASSWORD environment variable of the VS Code process (pgpass files are not read), and the search path can be set with PGOPTIONS (for example -c search_path=app,public).

tlsMode sets how the connection uses TLS:

• verify-full (default): encrypts and verifies the server certificate and host name.
• verify-ca: encrypts and verifies the server certificate.
• require: encrypts without verifying the certificate.
• disable: does not use TLS.

[!NOTE] Beta limitation: Only single-table SELECT statements are checked against the catalog. Other statements, including JOIN, subqueries, and INSERT / UPDATE / DELETE, are skipped without a diagnostic. The Uroborosql-fmt output channel lists each skipped statement as path:line:column: not checked against the catalog (reason).

Settings

Configuration options

{
  "debug": false,
  "tab_size": 4,
  "complement_alias": true,
  "trim_bind_param": false,
  "keyword_case": "preserve",
  "identifier_case": "preserve",
  "max_char_per_line": 50,
  "complement_outer_keyword": true,
  "complement_column_as_keyword": true,
  "remove_table_as_keyword": true,
  "remove_redundant_nest": true,
  "complement_sql_id": true,
  "convert_double_colon_cast": false,
  "unify_not_equal": true,
  "indent_tab": true,
  "use_parser_error_recovery": true
}

Create .uroborosqlfmtrc.json in the directory where you run the command and write the configuration there.

If there is no configuration file, the default values are used.

Available Commands

License

Business Source License 1.1