sqlalchemy-lsp

Language server for SQLAlchemy ORM and Alembic. Diagnostics, completions, hover, navigation, and a headless CLI linter — one Rust binary, any LSP-capable editor.

Features

Diagnostics

Best-practice lints (SQLA-W1xx–SQLA-H4xx) default on and cover modernization, nullable hygiene, and Alembic migration checks.

Installation

uv tool install sqlalchemy-lsp

Or with pip:

pip install sqlalchemy-lsp

Or download a pre-built binary from the releases page.

Configuration

Zero config for standard projects. Place a sqlalchemy-lsp.toml or [tool.sqlalchemy-lsp] section in pyproject.toml at the project root.

# sqlalchemy-lsp.toml

# Path to the declarative base (auto-detected if absent)
# base = "app/database.py"

# Extra source roots for import resolution
# source_roots = ["src"]

[diagnostics]
# Run only these codes
# select = ["SQLA-E301", "SQLA-E401"]

# Suppress codes
ignore = ["SQLA-H406"]

# Override severity per code
[diagnostics.severity]
"SQLA-W303" = "error"

Suppress a single line with # noqa or # noqa: SQLA-W303.

CLI

# Run diagnostics
sqlalchemy-lsp check .
sqlalchemy-lsp check app/models/ --select SQLA-E3xx --ignore SQLA-H406
sqlalchemy-lsp check --format json

# Print the workspace ER schema
sqlalchemy-lsp schema

# Print model statistics
sqlalchemy-lsp stats

Editor Setup

Zed

Install from the Zed extensions panel (Cmd+Shift+X) — search for sqlalchemy-lsp and click Install. It activates automatically for Python files.

To control server order alongside other language servers, add to ~/.config/zed/settings.json:

{
  "languages": {
    "Python": { "language_servers": ["sqlalchemy-lsp", "..."] }
  }
}

Helix

Merge editors/helix/languages.toml into ~/.config/helix/languages.toml.

Neovim

Requires Neovim 0.11+. Use the snippet from editors/neovim/sqlalchemy_lsp.lua or add to your init.lua:

vim.lsp.config('sqlalchemy_lsp', {
  cmd = { 'sqlalchemy-lsp', 'lsp', '--stdio' },
  filetypes = { 'python' },
  root_markers = { 'pyproject.toml', 'sqlalchemy-lsp.toml', 'alembic.ini', '.git' },
})
vim.lsp.enable('sqlalchemy_lsp')

Other editors

The server speaks standard LSP over stdio:

sqlalchemy-lsp lsp --stdio

License

MIT