sqlalchemy-lsp 0.2.0

Language server for SQLAlchemy ORM intelligence

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	missing tablename, duplicate tablename/column, unknown FK table/column, FK type mismatch, relationship wiring errors, back_populates mismatch, uselist mismatch, orphan cascades, circular relationships, Alembic migration checks
Completions	FK strings, relationship() kwargs and values, mapped_column() kwargs, __table_args__ column names, model-constructor keywords, Alembic op.* names and arguments, snippets
Hover	model card, column card (type, nullability, FK target, indexes), FK resolution, relationship card, cascade tokens, back_populates counterpart
Navigation	go-to-definition, find references, rename — models, columns, relationships, FK targets
Signature help	model constructors, relationship() kwargs
Symbols	models and Alembic revisions in the symbol picker
Inlay hints	resolved FK targets inline
Code actions	generate __tablename__, fix back_populates, add missing FK column
Schema view	ER diagram of the workspace models
check CLI	same diagnostics as the LSP — sqlalchemy-lsp check .

Diagnostics

Code	Severity	What it catches
SQLA-W101	warning	missing __tablename__
SQLA-E102	error	duplicate __tablename__
SQLA-E103	error	duplicate column name
SQLA-E105	error	__table_args__ references unknown column
SQLA-W201	warning	nullable=True column typed as non-optional
SQLA-E301	error	FK references unknown table
SQLA-E302	error	FK references unknown column
SQLA-W303	warning	FK type mismatch
SQLA-E401	error	relationship target not found
SQLA-W402	warning	back_populates points at wrong attribute
SQLA-W403	warning	back_populates target not found
SQLA-W404	warning	uselist disagrees with cardinality
SQLA-W405	warning	relationship target mismatch
SQLA-H406	hint	missing FK for relationship
SQLA-H407	hint	one-to-one missing unique=True
SQLA-W408	warning	unknown cascade token
SQLA-W409	warning	orphan cascade without delete
SQLA-H410	hint	circular relationship

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