Remove serializes flag; longblob is now raw bytes

Simplified design:
- Plain longblob columns store/return raw bytes (no serialization)
- <djblob> type handles serialization via encode/decode
- Legacy AttributeAdapter handles blob pack/unpack internally
  for backward compatibility

This eliminates the need for the serializes flag by making
blob serialization the responsibility of the adapter/type,
not the framework. Migration to <djblob> is now required
for existing schemas that rely on implicit serialization.

Author: claude

docs/src/design/tables/customtype.md

@@ -498,22 +498,42 @@ class ProcessedData(dj.Manual):
     definition = """
     data_id : int
     ---
-    results : <djblob>      # Explicit serialization
-    raw_bytes : longblob    # Backward-compatible (auto-serialized)
+    results : <djblob>      # Serialized Python objects
+    raw_bytes : longblob    # Raw bytes (no serialization)
     """
 ```
 
 #### When to Use `<djblob>`
 
-- **New tables**: Prefer `<djblob>` for clarity and future-proofing
-- **Custom types**: Use `<djblob>` when your type chains to blob storage
-- **Migration**: Existing `longblob` columns can be migrated to `<djblob>`
+- **Serialized data**: When storing Python objects (dicts, arrays, etc.)
+- **New tables**: Prefer `<djblob>` for automatic serialization
+- **Migration**: Existing schemas with implicit serialization must migrate
 
-#### Backward Compatibility
+#### Raw Blob Behavior
 
-For backward compatibility, `longblob` columns without an explicit type
-still receive automatic serialization. The behavior is identical to `<djblob>`,
-but using `<djblob>` makes the serialization explicit in your code.
+Plain `longblob` (and other blob variants) columns now store and return
+**raw bytes** without automatic serialization:
+
+```python
+@schema
+class RawData(dj.Manual):
+    definition = """
+    id : int
+    ---
+    raw_bytes : longblob    # Stores/returns raw bytes
+    serialized : <djblob>   # Stores Python objects with serialization
+    """
+
+# Raw bytes - no serialization
+RawData.insert1({"id": 1, "raw_bytes": b"raw binary data", "serialized": {"key": "value"}})
+
+row = (RawData & "id=1").fetch1()
+row["raw_bytes"]    # Returns: b"raw binary data"
+row["serialized"]   # Returns: {"key": "value"}
+```
+
+**Important**: Existing schemas that relied on implicit blob serialization
+must be migrated to `<djblob>` to preserve their behavior.
 
 ## Schema Migration
 

src/datajoint/attribute_adapter.py

@@ -15,6 +15,9 @@
 from .attribute_type import AttributeType, get_type, is_type_registered
 from .errors import DataJointError
 
+# Pattern to detect blob types for internal pack/unpack
+_BLOB_PATTERN = re.compile(r"^(tiny|small|medium|long|)blob", re.I)
+
 
 class AttributeAdapter(AttributeType):
     """
@@ -87,12 +90,37 @@ def dtype(self) -> str:
             )
         return attr_type
 
+    def _is_blob_dtype(self) -> bool:
+        """Check if dtype is a blob type requiring pack/unpack."""
+        return bool(_BLOB_PATTERN.match(self.dtype))
+
     def encode(self, value: Any, *, key: dict | None = None) -> Any:
-        """Delegate to legacy put() method."""
-        return self.put(value)
+        """
+        Delegate to legacy put() method, with blob packing if needed.
+
+        Legacy adapters expect blob.pack to be called after put() when
+        the dtype is a blob type. This wrapper handles that automatically.
+        """
+        result = self.put(value)
+        # Legacy adapters expect blob.pack after put() for blob dtypes
+        if self._is_blob_dtype():
+            from . import blob
+
+            result = blob.pack(result)
+        return result
 
     def decode(self, stored: Any, *, key: dict | None = None) -> Any:
-        """Delegate to legacy get() method."""
+        """
+        Delegate to legacy get() method, with blob unpacking if needed.
+
+        Legacy adapters expect blob.unpack to be called before get() when
+        the dtype is a blob type. This wrapper handles that automatically.
+        """
+        # Legacy adapters expect blob.unpack before get() for blob dtypes
+        if self._is_blob_dtype():
+            from . import blob
+
+            stored = blob.unpack(stored)
         return self.get(stored)
 
     def put(self, obj: Any) -> Any:

src/datajoint/attribute_type.py

@@ -153,10 +153,6 @@ def decode(self, stored: Any, *, key: dict | None = None) -> Any:
         """
         ...
 
-    # Class attribute: If True, encode() produces final binary data (no blob.pack needed)
-    # Override in subclasses that handle their own serialization
-    serializes: bool = False
-
     def validate(self, value: Any) -> None:
         """
         Validate a value before encoding.
@@ -440,19 +436,19 @@ class ProcessedData(dj.Manual):
             definition = '''
             data_id : int
             ---
-            results : <djblob>      # Explicit DataJoint serialization
+            results : <djblob>      # Serialized Python objects
             raw_bytes : longblob    # Raw bytes (no serialization)
             '''
 
     Note:
-        For backward compatibility, ``longblob`` columns without an explicit type
-        still use automatic serialization. Use ``<djblob>`` to be explicit about
-        serialization behavior.
+        Plain ``longblob`` columns store and return raw bytes without serialization.
+        Use ``<djblob>`` when you need automatic serialization of Python objects.
+        Existing schemas using implicit blob serialization should migrate to ``<djblob>``
+        using ``dj.migrate.migrate_blob_columns()``.
     """
 
     type_name = "djblob"
     dtype = "longblob"
-    serializes = True  # This type handles its own serialization
 
     def encode(self, value: Any, *, key: dict | None = None) -> bytes:
         """
@@ -508,7 +504,6 @@ class LargeData(dj.Manual):
     # It's used internally when blob@store syntax is detected
     type_name = "djblob_external"
     dtype = "blob@store"  # Placeholder - actual store is determined at declaration time
-    serializes = True  # This type handles its own serialization
 
     def encode(self, value: Any, *, key: dict | None = None) -> bytes:
         """Serialize a Python object to DataJoint's blob format."""

src/datajoint/fetch.py

@@ -92,10 +92,11 @@ def adapt(x):
         return adapt(uuid.UUID(bytes=data))
     elif attr.is_blob:
         blob_data = extern.get(uuid.UUID(bytes=data)) if attr.is_external else data
-        # Skip unpack if adapter handles its own deserialization
-        if attr.adapter and getattr(attr.adapter, "serializes", False):
+        # Adapters (like <djblob>) handle deserialization in decode()
+        # Without adapter, blob columns return raw bytes (no deserialization)
+        if attr.adapter:
             return attr.adapter.decode(blob_data, key=None)
-        return adapt(blob.unpack(blob_data, squeeze=squeeze))
+        return blob_data  # raw bytes
     else:
         return adapt(data)
 

src/datajoint/table.py

@@ -742,9 +742,8 @@ def __make_placeholder(self, name, value, ignore_extra_fields=False):
                         raise DataJointError("badly formed UUID value {v} for attribute `{n}`".format(v=value, n=name))
                 value = value.bytes
             elif attr.is_blob:
-                # Skip blob.pack if adapter already handles serialization
-                if not (attr.adapter and getattr(attr.adapter, "serializes", False)):
-                    value = blob.pack(value)
+                # Adapters (like <djblob>) handle serialization in encode()
+                # Without adapter, blob columns store raw bytes (no serialization)
                 if attr.is_external:
                     value = self.external[attr.store].put(value).bytes
             elif attr.is_attachment:

tests/test_attribute_type.py

@@ -359,7 +359,6 @@ def test_djblob_properties(self):
         blob_type = get_type("djblob")
         assert blob_type.type_name == "djblob"
         assert blob_type.dtype == "longblob"
-        assert blob_type.serializes is True
 
     def test_djblob_encode_decode_roundtrip(self):
         """Test that encode/decode is a proper roundtrip."""
@@ -400,16 +399,21 @@ def test_djblob_in_list_types(self):
         types = list_types()
         assert "djblob" in types
 
-    def test_serializes_flag_prevents_double_pack(self):
-        """Test that serializes=True prevents blob.pack being called twice.
+    def test_djblob_handles_serialization(self):
+        """Test that DJBlobType handles serialization internally.
 
-        This is a unit test for the flag itself. Integration test with tables
-        is in test_blob.py or test_adapted_attributes.py.
+        With the new design:
+        - Plain longblob columns store/return raw bytes (no serialization)
+        - <djblob> handles pack/unpack in encode/decode
+        - Legacy AttributeAdapter handles pack/unpack internally for backward compat
         """
         blob_type = get_type("djblob")
-        assert blob_type.serializes is True
 
-        # Legacy adapters should not have serializes=True
-        # (they rely on blob.pack being called after encode)
-        # AttributeType base class defaults to False
-        assert AttributeType.serializes is False
+        # DJBlobType.encode() should produce packed bytes
+        data = {"key": "value"}
+        encoded = blob_type.encode(data)
+        assert isinstance(encoded, bytes)
+
+        # DJBlobType.decode() should unpack back to original
+        decoded = blob_type.decode(encoded)
+        assert decoded == data