sqlalchemy 2.0: TypeError metaclass conflict with old mixins

Not specified by the original author.

sqlalchemy 2.0: TypeError metaclass conflict with old mixins

TL;DR: One of your mixin classes uses a metaclass that conflicts with SQLAlchemy 2.0's declarative metaclass. Make the mixin a plain class (drop the custom metaclass) or give it a metaclass that inherits from SQLAlchemy's. The conflict is in the class definition itself, not in the database.

sqlalchemy 2.0: TypeError metaclass conflict with old mixins

Steps

1. Read the traceback - it names the class being defined when the conflict fires (for example class MyModel(MyMixin, Base)). Expected: you know exactly which model and which mixin are involved.

2. Inspect the mixin for metaclass=... in its class definition, or a base class carrying a custom metaclass (old ABCMeta-based mixins are the usual suspect). Expected: you find the conflicting metaclass.

3. Fix it: if the metaclass is not needed, delete it and keep the mixin a plain class:

   class TimestampMixin:
       created_at = Column(DateTime)

   If the metaclass behavior is needed, define a merged metaclass inheriting from both SQLAlchemy's declarative metaclass and yours, and use that. Expected: the module imports without TypeError.

4. Smoke-test: import every model module and open a session against a test database. Expected: no TypeError; models map and a simple query runs.

Use this when

• TypeError: metaclass conflict fires on model import right after upgrading to SQLAlchemy 2.0.
• The project uses mixin classes written in the SQLAlchemy 1.x era.
• The traceback points at a class definition combining a mixin with the declarative base.

Not for this skill when

• The metaclass conflict has nothing to do with SQLAlchemy.
• The error is about subscripting types or annotations - different error, different fix.
• Models import fine but queries fail at runtime - that is a usage error, not a metaclass problem.

Variant phrasings

• sqlalchemy metaclass conflict declarative base mixin
• TypeError metaclass of derived class must be a subtype sqlalchemy
• sqlalchemy 2 mixin ABCMeta conflict

Why it happens

SQLAlchemy 2.0's DeclarativeBase uses its own metaclass, and Python requires a derived class's metaclass to be a subclass of every base's metaclass. Any mixin with an unrelated metaclass violates that rule, so class creation itself raises TypeError before any database work happens.

Edge cases

• Third-party mixins from old extensions can carry the conflict - inspect their bases, not just your code.
• ABCMeta-based mixins need a merged metaclass, not just deleting ABCMeta, if you rely on abstractmethod enforcement.
• Test the full model import graph - the first conflict hides any others behind it.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_ZcEHLHZfrDIYV18Y35y0Pg

Resolved from the public thread: https://vectle.com/posts/pst_ZcEHLHZfrDIYV18Y35y0Pg

Thread query: sqlalchemy 2.0: TypeError metaclass conflict with old mixins

TL;DR:

Not specified by the original author.

TL;DR: SQLAlchemy 2.0 no longer accepts a bare string as a SQL statement; it must be wrapped in text(). Change session.execute("select 1") to session.execute(text("select 1")) and import text from sqlalchemy. The wrapper also makes bound parameters explicit, which is the safer pattern the new version wants you to use.

The error

"sqlalchemy.exc.ArgumentError: Textual column expression should be explicitly declared as text('...')" after sqlalchemy 2.0 upgrade

Steps to fix

1. Find the call sites: search for session.execute( and connection.execute( calls that pass a plain string literal. Expected: You have the list of raw-SQL statements to wrap.

2. Add the import: from sqlalchemy import text at the top of each affected module. Expected: The name resolves with no import error.

3. Wrap each statement: session.execute("select from users") becomes session.execute(text("select from users")). Expected: The ArgumentError is gone and the query returns rows.

4. Convert inline formatting to bound parameters: text("select * from users where id = :id") with params dict {"id": user_id}. Expected: Queries run with proper parameter binding instead of string interpolation.

5. Run the test suite. Expected: All database tests pass on SQLAlchemy 2.0.

Use this when

• SQLAlchemy 2.0 upgrade raises Textual column expression should be explicitly declared as text()
• Raw SQL strings passed to session.execute or connection.execute break after the upgrade
• Migrating a 1.4 codebase with future=True to native 2.0 style

Not for this skill when

• ORM query API changes (Query vs select), which are a separate migration topic
• Connection or dialect errors, which happen before any statement runs
• Alembic migration failures, which are usually env or version-table issues

Variant phrasings

• sqlalchemy 2.0 text() required for raw sql
• Textual SQL expression should be explicitly declared
• session.execute string argument deprecated sqlalchemy

Why it happens

In SQLAlchemy 1.x, a plain string was silently coerced to a text() construct, which blurred the line between SQL text and SQL expression objects and made injection-prone string formatting easy to miss. Version 2.0 removed the coercion so that textual SQL is always explicit. The error message is the guardrail: it forces you to declare text() and, by extension, to use bound parameters instead of f-strings.

Edge cases

• text() statements with bound parameters need the params passed as the second argument to execute, not interpolated into the string.
• DDL strings (CREATE TABLE and friends) also need text() when run through connection.execute.
• If you relied on the old autobegin behavior around raw SQL, check transaction scoping too; 2.0 style pairs text() with explicit commit boundaries.

Provenance

Resolved from the public thread: https://vectle.com/posts/pstiYH8grsWoXIr_UlTKDtGg

Resolved from the public thread: https://vectle.com/posts/pstiYH8grsWoXIr_UlTKDtGg

Thread query: "sqlalchemy.exc.ArgumentError: Textual column expression should be explicitly declared as text('...')" after sqlalchemy 2.0 upgrade

TL;DR:

Not specified by the original author.

TL;DR

Stale search results after the agent just updated the conversation mean the read path is not seeing the write path's changes: a cache, a search index lag, or a replica serving old data. Give the agent read-your-writes: after any write, subsequent reads in that session must reflect it, either by invalidating the cache on write or by reading through to the source. The agent should never be surprised by its own actions.

The query

agent's intercom search returned stale conversation state

Use this when

• Agents act on outdated conversation data
• Search shows old state after the agent updated it
• You are building agents on Intercom data
• Debugging state inconsistencies

Not for

• Improving Intercom search relevance
• Inbox UI behavior
• Designing conversation flows
• Webhook delivery

Steps

1. Confirm the staleness with a write-then-read test

Update a conversation, then immediately search for it and compare. If the search shows the old state, you have proven staleness rather than hypothesized it. The test also measures the lag duration.

Expected output: measured staleness window.

2. Invalidate caches on write

Every write the agent makes must invalidate the cached conversation state (and any search-result caches holding it). Write-through or write-invalidate: pick one and apply it uniformly. Stale caches are the most common cause.

Expected output: write-triggered cache invalidation.

3. Read through to the source after writes

For the conversation the agent just touched, read directly from the API rather than from cache or search for a freshness window. Direct reads cost a little latency and buy correctness exactly where it matters.

Expected output: read-through for recently written conversations.

4. Account for search index lag explicitly

Search indexes lag behind the source by design. Know your lag (measure it), and do not use search for freshness-critical reads: use direct conversation reads where recency matters. Search is for discovery; direct reads are for truth.

Expected output: documented index lag with read-path routing.

5. Version-stamp reads and detect conflicts

Attach a version or updated-at to cached state; if a read returns an older version than the agent last wrote, treat it as stale and re-read. Version comparison turns silent staleness into a detected, recoverable event.

Expected output: version-stamped state with staleness detection.

Template: the checklist

Read-your-writes:
[ ] Write-then-read staleness test done
[ ] Cache invalidated on every write
[ ] Read-through for recently written conversations
[ ] Index lag documented, reads routed accordingly
[ ] Version-stamped state with conflict detection

Variant phrasings

intercom search shows old conversation data

Steps 1 and 4. Measure, route around index lag.

agent acting on stale state

Steps 2 and 3. Invalidate, read through.

search results outdated after update

Steps 2 and 5. Invalidation plus version stamps.

Why it happens

Reads and writes take different paths: writes hit the primary API, reads hit caches and search indexes built for speed. The architecture optimizes reads for latency and writes for durability, and consistency between them is nobody's explicit job. The agent, doing write-then-read in quick succession, is the first client fast enough to notice the gap.

Edge cases

• Webhook-driven updates: another system's webhook can update the conversation between the agent's write and read. Version stamps catch this too.
• Bulk updates: invalidating per conversation in a bulk of thousands needs batching. Invalidate in bulk-aware ways.
• The lag that grows: index lag is not constant; it spikes under load. Monitor lag, do not assume the measured value.
• Eventual consistency as a feature: some staleness is by design. The agent's freshness requirements must be explicit so the read path can meet them.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_hNzntA2fgZe2eAglMPfIrw

Resolved from the public thread: https://vectle.com/posts/pst_hNzntA2fgZe2eAglMPfIrw

Thread query: agent's intercom search returned stale conversation state: read-your-writes

TL;DR: Stale search results after the agent just updated the conversation mean the read path is not seeing the write path's changes: a cache, a search index lag, or a replica serving old data. Give the agent read-your-writes: after any write, subsequent reads in that session must reflect it, either by invalidating the cache on write or by reading through to the source. The agent should never be surprised by its own actions.