{"id":10256,"library":"sqlalchemy-searchable","title":"SQLAlchemy Searchable","description":"SQLAlchemy Searchable provides full-text search capabilities for declarative SQLAlchemy models, primarily leveraging PostgreSQL's `tsvector` type for robust search. The current version is 3.0.0, and the library maintains a regular release cadence, with major versions often aligning with SQLAlchemy and PostgreSQL version support changes.","status":"active","version":"3.0.0","language":"en","source_language":"en","source_url":"https://github.com/falcony-io/sqlalchemy-searchable","tags":["SQLAlchemy","search","full-text","PostgreSQL","ORM"],"install":[{"cmd":"pip install sqlalchemy-searchable","lang":"bash","label":"Install core library"},{"cmd":"pip install sqlalchemy-searchable[sqlalchemy_utils]","lang":"bash","label":"Install with SQLAlchemy-Utils (recommended for TSVectorType)"},{"cmd":"pip install sqlalchemy-searchable[psycopg2-binary]","lang":"bash","label":"Install with PostgreSQL driver (recommended for PostgreSQL)"}],"dependencies":[{"reason":"Core ORM dependency","package":"SQLAlchemy","optional":false},{"reason":"Provides `TSVectorType` and other utilities often used for full-text search setup.","package":"SQLAlchemy-Utils","optional":true},{"reason":"Required for PostgreSQL database connectivity, where full-text search is most robust.","package":"psycopg2-binary","optional":true}],"imports":[{"note":"The primary function to integrate full-text search into your SQLAlchemy metadata.","symbol":"make_searchable","correct":"from sqlalchemy_searchable import make_searchable"},{"note":"Used for custom query classes if you need to extend search behavior.","symbol":"SearchQueryMixin","correct":"from sqlalchemy_searchable import SearchQueryMixin"}],"quickstart":{"code":"import os\nfrom sqlalchemy import create_engine, Column, Integer, String, Text\nfrom sqlalchemy.orm import sessionmaker, declarative_base\nfrom sqlalchemy_searchable import make_searchable\n# from sqlalchemy_utils import TSVectorType # Often used for explicit search vector column type\n\n# Database setup (using in-memory SQLite for simplicity)\n# For PostgreSQL, use 'postgresql://user:password@host:port/database'\nengine = create_engine(os.environ.get('SQLALCHEMY_DATABASE_URL', 'sqlite:///:memory:'))\nSession = sessionmaker(bind=engine)\nsession = Session()\n\nBase = declarative_base()\n\n# IMPORTANT: Call make_searchable BEFORE defining your models\nmake_searchable(Base.metadata)\n\nclass Document(Base):\n    __tablename__ = 'document'\n    # __searchable__ defines which columns contribute to the search vector\n    __searchable__ = ['title', 'content']\n\n    id = Column(Integer, primary_key=True)\n    title = Column(String(255))\n    content = Column(Text)\n    # For PostgreSQL, you might define an explicit TSVectorType:\n    # search_vector = Column(TSVectorType('title', 'content'))\n\n    def __repr__(self):\n        return f\"<Document(id={self.id}, title='{self.title}')>\"\n\nBase.metadata.create_all(engine)\n\n# Add some data\ndoc1 = Document(title=\"Python Programming Basics\", content=\"Learn the fundamentals of Python, including variables, data types, and control flow.\")\ndoc2 = Document(title=\"Advanced SQLAlchemy Techniques\", content=\"Explore advanced features of SQLAlchemy like custom types, events, and performance tuning.\")\ndoc3 = Document(title=\"Web Development with Flask\", content=\"Build web applications efficiently using the Flask microframework and Jinja2 templates.\")\n\nsession.add_all([doc1, doc2, doc3])\nsession.commit()\n\n# Perform searches\nprint(\"Searching for 'Python':\")\nresults_python = session.query(Document).search('Python').all()\nfor doc in results_python:\n    print(f\"- {doc.title}\")\n\nprint(\"\\nSearching for 'web applications':\")\nresults_web = session.query(Document).search('web applications').all()\nfor doc in results_web:\n    print(f\"- {doc.title}\")\n\nsession.close()","lang":"python","description":"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."},"warnings":[{"fix":"Upgrade your PostgreSQL database to version 14 or newer, or downgrade `sqlalchemy-searchable` to a 2.x version (e.g., `pip install 'sqlalchemy-searchable<3'`).","message":"Version 3.0.0 drops support for PostgreSQL 11, 12, and 13. Users on these older PostgreSQL versions must upgrade their database or stick to `sqlalchemy-searchable < 3.0.0`.","severity":"breaking","affected_versions":"3.0.0"},{"fix":"Upgrade your Python environment to 3.8 or newer and SQLAlchemy to 1.4 or newer. Alternatively, pin `sqlalchemy-searchable` to a version less than 2.0.0 (e.g., `pip install 'sqlalchemy-searchable<2'`).","message":"Version 2.0.0 dropped support for Python 3.6, 3.7 and SQLAlchemy 1.3. Your application must use Python 3.8+ and SQLAlchemy 1.4+ (or 2.x) to use `sqlalchemy-searchable >= 2.0.0`.","severity":"breaking","affected_versions":"2.0.0"},{"fix":"For production full-text search, it is highly recommended to use PostgreSQL as your database. Ensure `psycopg2-binary` is installed and configure your PostgreSQL database with appropriate extensions (e.g., `pg_trgm`) and language dictionaries.","message":"`sqlalchemy-searchable`'s advanced full-text search capabilities, particularly with `tsvector` types and linguistic features, are most robust and performant when used with PostgreSQL. While it can work with other databases, their FTS support might be limited or rely on generic string matching.","severity":"gotcha","affected_versions":"All"},{"fix":"Ensure that `make_searchable(Base.metadata)` is executed immediately after `Base = declarative_base()` and before any `class MyModel(Base):` definitions.","message":"The `make_searchable(Base.metadata)` function must be called *before* defining your SQLAlchemy models. If called afterwards, the models will not be properly instrumented for search capabilities, and you might encounter `AttributeError`.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Install `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.","cause":"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.","error":"sqlalchemy.exc.ProgrammingError: type \"tsvector\" does not exist"},{"fix":"Verify 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.","cause":"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.","error":"AttributeError: 'Query' object has no attribute 'search'"},{"fix":"Install the package using pip: `pip install sqlalchemy-searchable`.","cause":"The `sqlalchemy-searchable` library is not installed in your current Python environment.","error":"No module named 'sqlalchemy_searchable'"}]}