Install & Compatibility
Where this runs
tested against v3.0.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.930 runs
installs and imports cleanly · install 0.0s · import 1.150s · 43.5MB
glibcpy 3.10–3.930 runs
installs and imports cleanly · install 3.3s · import 1.026s · 42MB
42MB installed
● package 42MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
make_searchable
✓ from sqlalchemy_searchable import make_searchable
The primary function to integrate full-text search into your SQLAlchemy metadata.
SearchQueryMixin
✓ from sqlalchemy_searchable import SearchQueryMixin
Used for custom query classes if you need to extend search behavior.
This quickstart demonstrates how to integrate `sqlalchemy-searchable` into a basic SQLAlchemy application. It sets up a simple `Document` model, makes it searchable using `make_searchable`, and then performs a basic full-text search query. Note that while this example uses SQLite for simplicity, `sqlalchemy-searchable`'s full potential, especially for advanced full-text search, is realized with PostgreSQL.
import os
from sqlalchemy import create_engine, Column, Integer, String, Text
from sqlalchemy.orm import sessionmaker, declarative_base
from sqlalchemy_searchable import make_searchable
# from sqlalchemy_utils import TSVectorType # Often used for explicit search vector column type
# Database setup (using in-memory SQLite for simplicity)
# For PostgreSQL, use 'postgresql://user:password@host:port/database'
engine = create_engine(os.environ.get('SQLALCHEMY_DATABASE_URL', 'sqlite:///:memory:'))
Session = sessionmaker(bind=engine)
session = Session()
Base = declarative_base()
# IMPORTANT: Call make_searchable BEFORE defining your models
make_searchable(Base.metadata)
class Document(Base):
__tablename__ = 'document'
# __searchable__ defines which columns contribute to the search vector
__searchable__ = ['title', 'content']
id = Column(Integer, primary_key=True)
title = Column(String(255))
content = Column(Text)
# For PostgreSQL, you might define an explicit TSVectorType:
# search_vector = Column(TSVectorType('title', 'content'))
def __repr__(self):
return f"<Document(id={self.id}, title='{self.title}')>"
Base.metadata.create_all(engine)
# Add some data
doc1 = Document(title="Python Programming Basics", content="Learn the fundamentals of Python, including variables, data types, and control flow.")
doc2 = Document(title="Advanced SQLAlchemy Techniques", content="Explore advanced features of SQLAlchemy like custom types, events, and performance tuning.")
doc3 = Document(title="Web Development with Flask", content="Build web applications efficiently using the Flask microframework and Jinja2 templates.")
session.add_all([doc1, doc2, doc3])
session.commit()
# Perform searches
print("Searching for 'Python':")
results_python = session.query(Document).search('Python').all()
for doc in results_python:
print(f"- {doc.title}")
print("\nSearching for 'web applications':")
results_web = session.query(Document).search('web applications').all()
for doc in results_web:
print(f"- {doc.title}")
session.close()
Errors
Common errors & fixes
sqlalchemy.exc.ProgrammingError: type "tsvector" does not exist
This error typically occurs when using `sqlalchemy-searchable` with PostgreSQL without the `sqlalchemy_utils` package installed or without explicitly defining the `TSVectorType` column in your model, or if the PostgreSQL database itself is missing the required language configuration or `pg_trgm` extension.
fixInstall `sqlalchemy-utils` (`pip install sqlalchemy-searchable[sqlalchemy_utils]`) and consider defining a `TSVectorType` column in your model (e.g., `search_vector = Column(TSVectorType('column1', 'column2'))`). Ensure your PostgreSQL database has the necessary extensions enabled (e.g., `CREATE EXTENSION pg_trgm;`) and relevant language dictionaries configured. AttributeError: 'Query' object has no attribute 'search'
This error means that the `.search()` method was not added to your SQLAlchemy query object. This usually happens if `make_searchable(Base.metadata)` was not called, or if it was called *after* your models were defined.
fixVerify that `make_searchable(Base.metadata)` is called correctly and, crucially, that it is executed *before* any of your SQLAlchemy models that use `__searchable__` are defined.
No module named 'sqlalchemy_searchable'
The `sqlalchemy-searchable` library is not installed in your current Python environment.
fixInstall the package using pip: `pip install sqlalchemy-searchable`.
Upgrade
Version history
3.0.0latest on PyPI · released Feb 16, 2026
Audit
Dependencies
SQLAlchemyrequiredCore ORM dependency
SQLAlchemy-UtilsoptionalProvides `TSVectorType` and other utilities often used for full-text search setup.
psycopg2-binaryoptionalRequired for PostgreSQL database connectivity, where full-text search is most robust.