deriva 1.7.3__py3-none-any.whl → 1.7.5__py3-none-any.whl

deriva/core/ermrest_model.py

@@ -1,15 +1,16 @@
 
 from __future__ import annotations
 
+import base64
+import hashlib
+import json
+import re
 from collections import OrderedDict
 from collections.abc import Iterable
 from enum import Enum
-import json
-import re
-import base64
-import hashlib
 
-from . import AttrDict, tag, urlquote, stob
+from . import AttrDict, tag, urlquote, stob, mmo
+
 
 class NoChange (object):
     """Special class used to distinguish no-change default arguments to methods.
@@ -23,6 +24,12 @@ class NoChange (object):
 # singletone to use in APIs below
 nochange = NoChange()
 
+class UpdateMappings (str, Enum):
+    """Update Mappings flag enum"""
+    no_update = ''
+    deferred = 'deferred'
+    immediate = 'immediate'
+
 def make_id(*components):
     """Build an identifier that will be OK for ERMrest and Postgres.
 
@@ -91,6 +98,19 @@ def make_id(*components):
     # last-ditch (e.g. multibyte unicode suffix worst case)
     return truncate(naive_result, 55) + naive_hash
 
+def sql_identifier(s):
+    # double " to protect from SQL
+    return '"%s"' % (s.replace('"', '""'))
+
+def sql_literal(v):
+    if v is None:
+        return 'NULL'
+    if type(v) is list:
+        s = json.dumps(v)
+    # double ' to protect from SQL
+    s = '%s' % v
+    return "'%s'" % (s.replace("'", "''"))
+
 def presence_annotation(tag_uri):
     """Decorator to establish property getter/setter/deleter for presence annotations.
 
@@ -521,6 +541,15 @@ class Schema (object):
             for tname, tdoc in schema_doc.get('tables', {}).items()
         }
 
+    def __repr__(self):
+        cls = type(self)
+        return "<%s.%s object %r at 0x%x>" % (
+            cls.__module__,
+            cls.__name__,
+            self.name,
+            id(self),
+        )
+
     @property
     def catalog(self):
         return self.model.catalog
@@ -625,16 +654,16 @@ class Schema (object):
         for tname, table in self.tables.items():
             table.apply(existing.tables[tname] if existing else None)
 
-    def alter(self, schema_name=nochange, comment=nochange, acls=nochange, annotations=nochange):
+    def alter(self, schema_name=nochange, comment=nochange, acls=nochange, annotations=nochange, update_mappings=UpdateMappings.no_update):
         """Alter existing schema definition.
 
         :param schema_name: Replacement schema name (default nochange)
         :param comment: Replacement comment (default nochange)
         :param acls: Replacement ACL configuration (default nochange)
         :param annotations: Replacement annotations (default nochange)
+        :param update_mappings: Update annotations to reflect changes (default UpdateMappings.no_updates)
 
         Returns self (to allow for optional chained access).
-
         """
         changes = strip_nochange({
             'schema_name': schema_name,
@@ -648,9 +677,14 @@ class Schema (object):
         changed = r.json() # use changed vs changes to get server-digested values
 
         if 'schema_name' in changes:
+            old_schema_name = self.name
             del self.model.schemas[self.name]
             self.name = changed['schema_name']
             self.model.schemas[self.name] = self
+            if update_mappings:
+                mmo.replace(self.model, [old_schema_name, None], [self.name, None])
+                if update_mappings == UpdateMappings.immediate:
+                    self.model.apply()
 
         if 'comment' in changes:
             self.comment = changed['comment']
@@ -686,11 +720,19 @@ class Schema (object):
         self.model.digest_fkeys()
         return newtable
 
-    def drop(self):
+    def drop(self, cascade=False, update_mappings=UpdateMappings.no_update):
         """Remove this schema from the remote database.
+
+        :param cascade: drop dependent objects.
+        :param update_mappings: Update annotations to reflect changes (default UpdateMappings.no_updates)
         """
         if self.name not in self.model.schemas:
             raise ValueError('Schema %s does not appear to belong to model.' % (self,))
+
+        if cascade:
+            for table in list(self.tables.values()):
+                table.drop(cascade=True, update_mappings=update_mappings)
+
         self.catalog.delete(self.uri_path).raise_for_status()
         del self.model.schemas[self.name]
         for table in self.tables.values():
@@ -770,6 +812,8 @@ class FindAssociationResult (object):
 class Table (object):
     """Named table.
     """
+    default_key_column_search_order = ["Name", "name", "ID", "id"]
+
     def __init__(self, schema, tname, table_doc):
         self.schema = schema
         self.name = tname
@@ -792,6 +836,16 @@ class Table (object):
         ])
         self.referenced_by = KeyedList([])
 
+    def __repr__(self):
+        cls = type(self)
+        return "<%s.%s object %r.%r at 0x%x>" % (
+            cls.__module__,
+            cls.__name__,
+            self.schema.name if self.schema is not None else None,
+            self.name,
+            id(self),
+        )
+
     @property
     def columns(self):
         """Sugared access to self.column_definitions"""
@@ -825,20 +879,211 @@ class Table (object):
     def system_key_defs(cls, custom=[]):
         """Build standard system key definitions, merging optional custom definitions."""
         def ktup(k):
-            return tuple(k['unique_columns'])
+            return frozenset(k['unique_columns'])
+        customized = { ktup(kdef): kdef for kdef in custom }
         return [
             kdef for kdef in [
                 Key.define(['RID'])
             ]
-            if ktup(kdef) not in { ktup(kdef): kdef for kdef in custom }
+            if ktup(kdef) not in customized
         ] + custom
 
     @classmethod
-    def define(cls, tname, column_defs=[], key_defs=[], fkey_defs=[], comment=None, acls={}, acl_bindings={}, annotations={}, provide_system=True):
+    def system_fkey_defs(cls, tname, custom=[]):
+        """Build standard system fkey definitions, merging optional custom definitions."""
+        def fktup(fk):
+            return (
+                fk["referenced_columns"][0]["schema_name"],
+                fk["referenced_columns"][0]["table_name"],
+                frozenset(zip(
+                    tuple( c["column_name"] for c in fk["foreign_key_columns"] ),
+                    tuple( c["column_name"] for c in fk["referenced_columns"] ),
+                ))
+            )
+        customized = { fktup(fkdef) for fkdef in custom }
+        return [
+            fkdef for fkdef in [
+                ForeignKey.define(
+                    ["RCB"], "public", "ERMrest_Client", ["ID"],
+                    constraint_name=make_id(tname, "RCB", "fkey"),
+                ),
+                ForeignKey.define(
+                    ["RMB"], "public", "ERMrest_Client", ["ID"],
+                    constraint_name=make_id(tname, "RMB", "fkey"),
+                ),
+            ]
+            if fktup(fkdef) not in customized
+        ] + custom
+    
+    @classmethod
+    def _expand_references(
+        cls,
+        table_name: str,
+        column_defs: list[Key | Table | dict | tuple[str, bool, Key | Table] | tuple[str, Key | Table]],
+        fkey_defs: Iterable[dict],
+        used_names: set[str] =set(),
+        key_column_search_order: Iterable[str] | None = None,
+    ):
+        """Expand implicit references in column_defs into actual column and fkey definitions.
+
+        :param table_name: Name of table, needed to build fkey constraint names
+        :param column_defs: List of column definitions and/or reference targets (see below)
+        :param fkey_defs: List of foreign key definitions
+        :param used_names: Set of reference base names to consider already in use
+
+        Each reference target may be one of:
+           - Key
+           - Table
+           - tuple (str, Key|Table)
+           - tuple (str, bool, Key|Table)
+
+        A target Key specifies the columns of the remote table to
+        reference. A target Table instance specifies the remote table
+        and relies on heuristics to choose the target Key. A target
+        tuple specifies a string "base name" and optionally a boolean
+        "nullok" for the implied referencing columns. When omitted, a
+        default base name is constructed from target table
+        information, and a default nullok=False is specified for
+        referencing columns. The key_column_search_order parameter
+        influences the heuristic for selecting a target Key for an
+        input target Table.
+
+        This method mutates the input column_defs and used_names
+        containers. This can be abused to chain state through a
+        sequence of calls.
+
+        Returns the column_defs and fkey_defs which includes input
+        definitions and implied definitions while removing the corresponding input
+        reference targets.
+
+        """
+        out_column_defs = []
+        out_fkey_defs = list(fkey_defs)
+
+        # materialize for mutation and replay
+        column_defs = list(column_defs)
+
+        if key_column_search_order is not None:
+            # materialize iterable for reuse
+            key_column_search_order = list(key_column_search_order)
+        else:
+            key_column_search_order = cls.default_key_column_search_order
+
+        def check_basename(basename):
+            if not isinstance(base_name, str):
+                raise TypeError('Base name %r is not of required type str' % (base_name,))
+            if base_name in used_names:
+                raise ValueError('Base name %r is not unique among inputs' % (base_name,))
+            used_names.add(base_name)
+
+        def choose_basename(key):
+            base_name = key.table.name
+            n = 2
+            while base_name in used_names or any(used.startswith(base_name) for used in used_names):
+                base_name = '%s%d' % (key.table.name, n)
+                n += 1
+            used_names.add(base_name)
+            return base_name
+
+        def check_key(key):
+            if isinstance(key, Table):
+                # opportunistic case: prefer (non-nullable) "name" or "id" keys, if found
+                for cname in key_column_search_order:
+                    try:
+                        candidate = key.key_by_columns([cname])
+                        if not candidate.unique_columns[0].nullok:
+                            return candidate
+                    except (KeyError, ValueError) as e:
+                        continue
+
+                # general case: try to use RID key
+                try:
+                    return key.key_by_columns(["RID"])
+                except (KeyError, ValueError) as e:
+                    raise ValueError('Could not determine default key for table %s' % (key,))
+            elif isinstance(key, Key):
+                return key
+            raise TypeError('Expected Key or Table instance as target reference, not %s' % (key,))
+
+        # check and normalize cdefs into list[(str, Key)] with distinct base names
+        for i in range(len(column_defs)):
+            if isinstance(column_defs[i], tuple):
+                if len(column_defs[i]) == 2:
+                    base_name, key = column_defs[i]
+                    nullok = False
+                elif len(column_defs[i]) == 3:
+                    base_name, nullok, key = column_defs[i]
+                else:
+                    raise ValueError('Expected column definition tuple (str, Key|Table) or (str, bool, Key|Table), not %s' % (len(column_defs[i]),))
+                check_basename(base_name)
+                key = check_key(key)
+                column_defs[i] = (base_name, nullok, key)
+            elif isinstance(column_defs[i], (Key, Table)):
+                key = check_key(column_defs[i])
+                base_name = choose_basename(key)
+                column_defs[i] = (base_name, False, key)
+            elif isinstance(column_defs[i], dict):
+                pass
+            else:
+                raise TypeError('Expected column definition dict, Key, or Table input, not %s' % (column_defs[i],))
+
+        def simplify_type(ctype):
+            if ctype.is_domain and ctype.typename.startswith('ermrest_'):
+                return ctype.base_type
+            return ctype
+
+        def cdefs_for_key(base_name, nullok, key):
+            return [
+                Column.define(
+                    '%s_%s' % (base_name, col.name) if len(key.unique_columns) > 1 else base_name,
+                    simplify_type(col.type),
+                    nullok=nullok,
+                )
+                for col in key.unique_columns
+            ]
+
+        def fkdef_for_key(base_name, nullok, key):
+            return ForeignKey.define(
+                [
+                    '%s_%s' % (base_name, col.name) if len(key.unique_columns) > 1 else base_name
+                    for col in key.unique_columns
+                ],
+                key.table.schema.name,
+                key.table.name,
+                [ col.name for col in key.unique_columns ],
+                on_update='CASCADE',
+                on_delete='CASCADE',
+                constraint_name=make_id(table_name, base_name, 'fkey'),
+            )
+
+        for cdef in column_defs:
+            if isinstance(cdef, tuple):
+                out_column_defs.extend(cdefs_for_key(*cdef))
+                out_fkey_defs.append(fkdef_for_key(*cdef))
+            else:
+                out_column_defs.append(cdef)
+
+        return out_column_defs, out_fkey_defs
+
+    @classmethod
+    def define(
+        cls,
+        tname: str,
+        column_defs: Iterable[dict | Key | Table | tuple[str, bool, Key | Table] | tuple[str, Key | Table]] = [],
+        key_defs: Iterable[dict] = [],
+        fkey_defs: Iterable[dict] = [],
+        comment: str | None = None,
+        acls: dict = {},
+        acl_bindings: dict = {},
+        annotations: dict = {},
+        provide_system: bool = True,
+        provide_system_fkeys: book = True,
+        key_column_search_order: Iterable[str] | None = None,
+    ):
         """Build a table definition.
 
         :param tname: the name of the newly defined table
-        :param column_defs: a list of Column.define() results for extra or overridden column definitions
+        :param column_defs: a list of custom Column.define() results and/or reference targets (see below)
         :param key_defs: a list of Key.define() results for extra or overridden key constraint definitions
         :param fkey_defs: a list of ForeignKey.define() results for foreign key definitions
         :param comment: a comment string for the table
@@ -846,11 +1091,38 @@ class Table (object):
         :param acl_bindings: a dictionary of dynamic ACL bindings
         :param annotations: a dictionary of annotations
         :param provide_system: whether to inject standard system column definitions when missing from column_defs
+        :param provide_system_fkeys: whether to also inject foreign key definitions for RCB/RMB
+        :param key_column_search_order: override heuristic for choosing a Key from a Table input
+
+        Each reference target may be one of:
+           - Key
+           - Table
+           - tuple (str, Key|Table)
+           - tuple (str, bool, Key|Table)
+
+        A target Key specifies the columns of the remote table to
+        reference. A target Table instance specifies the remote table
+        and relies on heuristics to choose the target Key. A target
+        tuple specifies a string "base name" and optionally a boolean
+        "nullok" for the implied referencing columns. When omitted, a
+        default base name is constructed from target table
+        information, and a default nullok=False is specified for
+        referencing columns. The key_column_search_order parameter
+        influences the heuristic for selecting a target Key for an
+        input target Table.
 
         """
+        column_defs = list(column_defs) # materialize to allow replay
+        used_names = { cdef["name"] for cdef in column_defs if isinstance(cdef, dict) and 'name' in cdef }
+        column_defs, fkey_defs = cls._expand_references(tname, column_defs, fkey_defs, used_names, key_column_search_order)
+
         if provide_system:
             column_defs = cls.system_column_defs(column_defs)
             key_defs = cls.system_key_defs(key_defs)
+            if provide_system_fkeys:
+                fkey_defs = cls.system_fkey_defs(tname, fkey_defs)
+        else:
+            key_defs = list(key_defs)
 
         return {
             'table_name': tname,
@@ -864,13 +1136,29 @@ class Table (object):
         }
 
     @classmethod
-    def define_vocabulary(cls, tname, curie_template, uri_template='/id/{RID}', column_defs=[], key_defs=[], fkey_defs=[], comment=None, acls={}, acl_bindings={}, annotations={}, provide_system=True):
+    def define_vocabulary(
+        cls,
+        tname: str,
+        curie_template: str,
+        uri_template: str = '/id/{RID}',
+        column_defs: Iterable[dict | Key | Table | tuple[str, bool, Key | Table] | tuple[str, Key | Table]] = [],
+        key_defs=[],
+        fkey_defs=[],
+        comment: str | None = None,
+        acls: dict = {},
+        acl_bindings: dict = {},
+        annotations: dict = {},
+        provide_system: bool = True,
+        provide_system_fkeys: bool = True,
+        provide_name_key: bool = True,
+        key_column_search_order: Iterable[str] | None = None,
+    ):
         """Build a vocabulary table definition.
 
         :param tname: the name of the newly defined table
         :param curie_template: the RID-based template for the CURIE of locally-defined terms, e.g. 'MYPROJECT:{RID}'
         :param uri_template: the RID-based template for the URI of locally-defined terms, e.g. 'https://server.example.org/id/{RID}'
-        :param column_defs: a list of Column.define() results for extra or overridden column definitions
+        :param column_defs: a list of Column.define() results and/or reference targets (see below)
         :param key_defs: a list of Key.define() results for extra or overridden key constraint definitions
         :param fkey_defs: a list of ForeignKey.define() results for foreign key definitions
         :param comment: a comment string for the table
@@ -878,6 +1166,9 @@ class Table (object):
         :param acl_bindings: a dictionary of dynamic ACL bindings
         :param annotations: a dictionary of annotations
         :param provide_system: whether to inject standard system column definitions when missing from column_defs
+        :param provide_system_fkeys: whether to also inject foreign key definitions for RCB/RMB
+        :param provide_name_key: whether to inject a key definition for the Name column
+        :param key_column_search_order: override heuristic for choosing a Key from a Table input
 
         These core vocabulary columns are generated automatically if
         absent from the input column_defs.
@@ -888,7 +1179,10 @@ class Table (object):
         - Description: markdown, not null
         - Synonyms: text[]
 
-        However, caller-supplied definitions override the default.
+        However, caller-supplied definitions override the default. See
+        Table.define() documentation for an explanation reference
+        targets in the column_defs list and the related
+        key_column_search_order parameter.
 
         """
         if not re.match("^[A-Za-z][-_A-Za-z0-9]*:[{]RID[}]$", curie_template):
@@ -938,41 +1232,52 @@ class Table (object):
 
         def add_vocab_keys(custom):
             def ktup(k):
-                return tuple(k['unique_columns'])
+                return frozenset(k['unique_columns'])
             return [
                 key_def
                 for key_def in [
                         Key.define(['ID']),
                         Key.define(['URI']),
-                ]
+                ] + ([ Key.define(['Name']) ] if provide_name_key else [])
                 if ktup(key_def) not in { ktup(kdef): kdef for kdef in custom }
             ] + custom
 
+        used_names = {'ID', 'URI', 'Name', 'Description', 'Synonyms'}
+        column_defs, fkey_defs = cls._expand_references(tname, column_defs, fkey_defs, used_names, key_column_search_order)
+        column_defs = add_vocab_columns(column_defs)
+        key_defs = add_vocab_keys(key_defs)
+
         return cls.define(
             tname,
-            add_vocab_columns(column_defs),
-            add_vocab_keys(key_defs),
+            column_defs,
+            key_defs,
             fkey_defs,
             comment,
             acls,
             acl_bindings,
             annotations,
-            provide_system
+            provide_system=provide_system,
+            provide_system_fkeys=provide_system_fkeys,
+            key_column_search_order=key_column_search_order,
         )
 
     @classmethod
-    def define_asset(cls,
-                     sname,
-                     tname,
-                     hatrac_template=None,
-                     column_defs=[],
-                     key_defs=[],
-                     fkey_defs=[],
-                     comment=None,
-                     acls={},
-                     acl_bindings={},
-                     annotations={},
-                     provide_system=True):
+    def define_asset(
+        cls,
+        sname: str,
+        tname: str,
+        hatrac_template=None,
+        column_defs: Iterable[dict | Key | Table | tuple[str, bool, Key | Table] | tuple[str, Key | Table]] = [],
+        key_defs=[],
+        fkey_defs=[],
+        comment: str | None = None,
+        acls: dict = {},
+        acl_bindings: dict = {},
+        annotations: dict = {},
+        provide_system: bool = True,
+        provide_system_fkeys: bool = True,
+        key_column_search_order: Iterable[str] | None = None,
+    ):
         """Build an asset  table definition.
 
           :param sname: the name of the schema for the asset table
@@ -982,7 +1287,7 @@ class Table (object):
                      /hatrac/schema_name/table_name/md5.filename
                  where the filename and md5 value is computed on upload and the schema_name and table_name are the
                  values of the provided arguments.  If value is set to False, no hatrac_template is used.
-          :param column_defs: a list of Column.define() results for extra or overridden column definitions
+          :param column_defs: a list of Column.define() results and/or reference targets (see below)
           :param key_defs: a list of Key.define() results for extra or overridden key constraint definitions
           :param fkey_defs: a list of ForeignKey.define() results for foreign key definitions
           :param comment: a comment string for the table
@@ -990,22 +1295,28 @@ class Table (object):
           :param acl_bindings: a dictionary of dynamic ACL bindings
           :param annotations: a dictionary of annotations
           :param provide_system: whether to inject standard system column definitions when missing from column_defs
+          :param provide_system_fkeys: whether to also inject foreign key definitions for RCB/RMB
+          :param key_column_search_order: override heuristic for choosing a Key from a Table input
 
           These core asset table columns are generated automatically if
           absent from the input column_defs.
 
           - Filename: ermrest_curie, unique not null, default curie template "%s:{RID}" % curie_prefix
           - URL: Location of the asset, unique not null.  Default template is:
-                    /hatrac/sname/tname/{{{MD5}}}.{{{Filename}}} where tname is the name of the asset table.
+                    /hatrac/cat_id/sname/tname/{{{MD5}}}.{{{Filename}}} where tname is the name of the asset table.
           - Length: Length of the asset.
           - MD5: text
           - Description: markdown, not null
 
-          However, caller-supplied definitions override the default.
+          However, caller-supplied definitions override the
+          default. See Table.define() documentation for an explanation
+          reference targets in the column_defs list and the related
+          key_column_search_order parameter.
 
           In addition to creating the columns, this function also creates an asset annotation on the URL column to
           facilitate use of the table by Chaise.
-          """
+
+        """
 
         if hatrac_template is None:
             hatrac_template = '/hatrac/{{$catalog.id}}/%s/%s/{{{MD5}}}.{{#encode}}{{{Filename}}}{{/encode}}' % (sname, tname)
@@ -1039,7 +1350,7 @@ class Table (object):
 
         def add_asset_keys(custom):
             def ktup(k):
-                return tuple(k['unique_columns'])
+                return frozenset(k['unique_columns'])
 
             return [
                 key_def
@@ -1060,6 +1371,9 @@ class Table (object):
             asset_annotations.update(custom)
             return asset_annotations
 
+        used_names = {'URL', 'Filename', 'Description', 'Length', 'MD5'}
+        column_defs, fkey_defs = cls._expand_references(tname, column_defs, fkey_defs, used_names, key_column_search_order)
+
         return cls.define(
             tname,
             add_asset_columns(column_defs),
@@ -1069,29 +1383,49 @@ class Table (object):
             acls,
             acl_bindings,
             add_asset_annotations(annotations),
-            provide_system
+            provide_system=provide_system,
+            provide_system_fkeys=provide_system_fkeys,
+            key_column_search_order=key_column_search_order,
         )
 
     @classmethod
-    def define_page(cls, tname, column_defs=[], key_defs=[], fkey_defs=[], comment=None, acls={}, acl_bindings={}, annotations={}, provide_system=True):
+    def define_page(
+        cls,
+        tname,
+        column_defs: Iterable[dict | Key | Table | tuple[str, bool, Key | Table] | tuple[str, Key | Table]] = [],
+        key_defs=[],
+        fkey_defs=[],
+        comment: str | None = None,
+        acls: dict = {},
+        acl_bindings: dict = {},
+        annotations: dict = {},
+        provide_system: bool = True,
+        provide_system_fkeys: bool = True,
+        key_column_search_order: Iterable[str] | None = None,
+    ):
         """Build a wiki-like "page" table definition.
 
         :param tname: the name of the newly defined table
         :param column_defs: a list of Column.define() results for extra or overridden column definitions
-        :param key_defs: a list of Key.define() results for extra or overridden key constraint definitions
+        :param key_defs: a list of Key.define() results and/or reference targets (see below)
         :param fkey_defs: a list of ForeignKey.define() results for foreign key definitions
         :param comment: a comment string for the table
         :param acls: a dictionary of ACLs for specific access modes
         :param acl_bindings: a dictionary of dynamic ACL bindings
         :param annotations: a dictionary of annotations
         :param provide_system: whether to inject standard system column definitions when missing from column_defs
+        :param provide_system_fkeys: whether to also inject foreign key definitions for RCB/RMB
+        :param key_column_search_order: override heuristic for choosing a Key from a Table input
 
         These core page columns are generated automatically if absent from the input column_defs.
 
         - Title: text, unique not null
         - Content: markdown
 
-        However, caller-supplied definitions override the default.
+        However, caller-supplied definitions override the default. See
+        Table.define() documentation for an explanation reference
+        targets in the column_defs list and the related
+        key_column_search_order parameter.
         """
 
         def add_page_columns(custom):
@@ -1116,7 +1450,7 @@ class Table (object):
 
         def add_page_keys(custom):
             def ktup(k):
-                return tuple(k['unique_columns'])
+                return frozenset(k['unique_columns'])
             return [
                 key_def
                 for key_def in [
@@ -1146,6 +1480,9 @@ class Table (object):
             page_annotations.update(annotations)
             return page_annotations
 
+        used_names = {'Title', 'Content'}
+        column_defs, fkey_defs = cls._expand_references(tname, column_defs, fkey_defs, used_names, key_column_search_order)
+
         return cls.define(
             tname,
             add_page_columns(column_defs),
@@ -1155,7 +1492,9 @@ class Table (object):
             acls,
             acl_bindings,
             add_page_annotations(annotations),
-            provide_system
+            provide_system=provide_system,
+            provide_system_fkeys=provide_system_fkeys,
+            key_column_search_order=key_column_search_order,
         )
 
     @classmethod
@@ -1165,14 +1504,19 @@ class Table (object):
         metadata: Iterable[Key | Table | dict | tuple[str, bool, Key | Table]] = [],
         table_name: str | None = None,
         comment: str | None = None,
-        provide_system: bool = True) -> dict:
+        provide_system: bool = True,
+        provide_system_fkeys: bool = True,
+        key_column_search_order: Iterable[str] | None = None,
+    ) -> dict:
         """Build an association table definition.
 
-        :param associates: the existing Key instances being associated
-        :param metadata: additional metadata fields for impure associations
+        :param associates: reference targets being associated (see below)
+        :param metadata: additional metadata fields and/or reference targets for impure associations
         :param table_name: name for the association table or None for default naming
         :param comment: comment for the association table or None for default comment
         :param provide_system: add ERMrest system columns when True
+        :param provide_system_fkeys: whether to also inject foreign key definitions for RCB/RMB
+        :param key_column_search_order: override heuristic for choosing a Key from a Table input
 
         This is a utility function to help build an association table
         definition. It simplifies the task, but removes some
@@ -1188,154 +1532,91 @@ class Table (object):
         An "impure" association table adds additional metadata
         alongside the N foreign keys.
 
-        The "associates" parameter takes an iterable of Key instances
-        from other tables.  The association will be comprised of
-        foreign keys referencing these associates. Optionally, a tuple
-        of (str, Key) can supply a string _base name_ to influence how
-        the foreign key columns and constraint will be named in the
-        new association table. A bare Key instance will get a base
-        name derived from the referenced table name.
-
-        The "metadata" parameter takes an iterable of plain dict
-        column definitions or Key instances. Each dict must be a
-        scalar column definition, such as produced by the
-        Column.define() class method. Key instance will cause
-        corresponding columns and foreign keys to be added to the
-        association table to act as metadata. Optionally, a tuple of
-        (str, bool, Key) can supply a string _base name_ and a boolean
-        _nullok_ property to influence how the foreign key columns and
-        constraint will be constructed and named. A bare Key instance
-        will get a base name derived from the referened table name,
-        and presumed as nullok=False.
-
-        If a Table instance is supplied instead of a Key instance for
-        associates or metadata inputs, an attempt will be made to
-        locate a key based on the RID system column. If this key
-        cannot be found, a KeyError will be raised.
+        The "associates" parameter takes an iterable of reference
+        targets.  The association will be comprised of foreign keys
+        referencing these associates. This includes columns to store
+        the associated foreign key values, foreign key constraints to
+        the associated tables, and a composite key constraint
+        covering all the associated foreign key values.
+
+        The "metadata" parameter takes an iterable Column.define()
+        results and/or reference targets. The association table will
+        be augmented with extra metadata columns and foreign keys as
+        directed by these inputs.
+
+        See the Table.define() method documentation for more on
+        reference targets. Association columns must be defined with
+        nullok=False, so the associates parameter is restricted to a
+        more limited form of reference target input without
+        caller-controlled nullok boolean values.
 
         """
         associates = list(associates)
         metadata = list(metadata)
 
+        if key_column_search_order is not None:
+            # materialize iterable for reuse
+            key_column_search_order = list(key_column_search_order)
+        else:
+            key_column_search_order = cls.default_key_column_search_order
+                
         if len(associates) < 2:
             raise ValueError('An association table requires at least 2 associates')
 
-        cdefs = []
-        kdefs = []
-        fkdefs = []
-
         used_names = set()
 
-        def check_basename(basename):
-            if not isinstance(base_name, str):
-                raise TypeError('Base name %r is not of required type str' % (base_name,))
-            if base_name in used_names:
-                raise ValueError('Base name %r is not unique among associates and metadata' % (base_name,))
-            used_names.add(base_name)
-
-        def choose_basename(key):
-            base_name = key.table.name
-            n = 2
-            while base_name in used_names:
-                base_name = '%s%d' % (key.table.name, n)
-                n += 1
-            used_names.add(base_name)
-            return base_name
-
-        def check_key(key):
-            if isinstance(key, Table):
-                return key.key_by_columns(["RID"])
-            return key
+        for assoc in associates:
+            if not isinstance(assoc, (tuple, Table, Key)):
+                raise TypeError("Associates must be Table or Key instances, not %s" % (assoc,))
 
-        # check and normalize associates into list[(str, Key)] with distinct base names
-        for i in range(len(associates)):
-            if isinstance(associates[i], tuple):
-                base_name, key = associates[i]
-                check_basename(base_name)
-                key = check_key(key)
-                associates[i] = (base_name, key)
-            else:
-                key = check_key(associates[i])
-                base_name = choose_basename(key)
-                associates[i] = (base_name, key)
+        # first pass: build "pure" association table parts
+        # HACK: use dummy table name if we don't have one yet
+        tname = table_name if table_name is not None else "dummy"
+        cdefs, fkdefs = cls._expand_references(tname, associates, [], used_names)
 
-        # build assoc table name if not provided
         if table_name is None:
-            table_name = make_id(*[ assoc[1].table.name for assoc in associates ])
-
-        def simplify_type(ctype):
-            if ctype.is_domain and ctype.typename.startswith('ermrest_'):
-                return ctype.base_type
-
-            return ctype
-
-        def cdefs_for_key(base_name, key, nullok=False):
-            return [
-                Column.define(
-                    '%s_%s' % (base_name, col.name) if len(key.unique_columns) > 1 else base_name,
-                    simplify_type(col.type),
-                    nullok=nullok,
-                )
-                for col in key.unique_columns
-            ]
-
-        def fkdef_for_key(base_name, key):
-            return ForeignKey.define(
-                [
-                    '%s_%s' % (base_name, col.name) if len(key.unique_columns) > 1 else base_name
-                    for col in key.unique_columns
-                ],
-                key.table.schema.name,
-                key.table.name,
-                [ col.name for col in key.unique_columns ],
-                on_update='CASCADE',
-                on_delete='CASCADE',
-                constraint_name=make_id(table_name, base_name, 'fkey'),
-            )
-
-        # build core association definition (i.e. the "pure" parts)
+            # use first pass results to build table_name
+            def get_assoc_name(assoc):
+                if isinstance(assoc, tuple):
+                    table = assoc[1]
+                elif isinstance(assoc, Key):
+                    table = key.table
+                elif isinstance(assoc, Table):
+                    table = assoc
+                else:
+                    raise ValueError("expected (str, Key|Table) | Key | Table, not %s" % (assoc,))
+                return table.name
+            table_name = make_id(*[ get_assoc_name(assoc) for assoc in associates ])
+            # HACK: repeat first pass to make proper fkey def constraint names
+            used_names = set()
+            cdefs, fkdefs = cls._expand_references(table_name, associates, [], used_names)
+
+        # build assoc key from union of associates' foreign key columns
         k_cnames = []
-        for base_name, key in associates:
-            cdefs.extend(cdefs_for_key(base_name, key))
-            fkdefs.append(fkdef_for_key(base_name, key))
-
-            k_cnames.extend([
-                '%s_%s' % (base_name, col.name) if len(key.unique_columns) > 1 else base_name
-                for col in key.unique_columns
-            ])
+        for fkdef in fkdefs:
+            k_cnames.extend([ colref["column_name"] for colref in fkdef["foreign_key_columns"] ])
 
-        kdefs.append(
+        kdefs = [
             Key.define(
                 k_cnames,
                 constraint_name=make_id(table_name, 'assoc', 'key'),
             )
+        ]
+
+        # run second pass to expand out metadata targets
+        cdefs, fkdefs = cls._expand_references(table_name, cdefs + metadata, fkdefs, used_names)
+
+        return Table.define(
+            table_name,
+            cdefs,
+            kdefs,
+            fkdefs,
+            comment=comment,
+            provide_system=provide_system,
+            provide_system_fkeys=provide_system_fkeys,
+            key_column_search_order=key_column_search_order,
         )
 
-        # check and normalize metadata into list[dict | (str, bool, Key)]
-        for i in range(len(metadata)):
-            if isinstance(metadata[i], tuple):
-                base_name, nullok, key = metadata[i]
-                check_basename(base_name)
-                key = check_key(key)
-                metadata[i] = (base_name, nullok, key)
-            elif isinstance(metadata[i], dict):
-                pass
-            else:
-                key = check_key(metadata[i])
-                base_name = choose_basename(key)
-                metadata[i] = (base_name, False, key)
-
-        # add metadata to definition
-        for md in metadata:
-            if isinstance(md, dict):
-                cdefs.append(md)
-            else:
-                base_name, nullok, key = md
-                cdefs.extend(cdefs_for_key(base_name, key, nullok))
-                fkdefs.append(fkdef_for_key(base_name, key))
-
-        return Table.define(table_name, cdefs, kdefs, fkdefs, comment=comment, provide_system=provide_system)
-
     def prejson(self, prune=True):
         return {
             "schema_name": self.schema.name,
@@ -1416,7 +1697,8 @@ class Table (object):
             comment=nochange,
             acls=nochange,
             acl_bindings=nochange,
-            annotations=nochange
+            annotations=nochange,
+            update_mappings=UpdateMappings.no_update
     ):
         """Alter existing schema definition.
 
@@ -1426,6 +1708,7 @@ class Table (object):
         :param acls: Replacement ACL configuration (default nochange)
         :param acl_bindings: Replacement ACL bindings (default nochange)
         :param annotations: Replacement annotations (default nochange)
+        :param update_mappings: Update annotations to reflect changes (default UpdateMappings.no_updates)
 
         A change of schema name is a transfer of the existing table to
         an existing destination schema (not a rename of the current
@@ -1453,14 +1736,25 @@ class Table (object):
             self.schema.tables[self.name] = self
 
         if 'schema_name' in changes:
+            old_schema_name = self.schema.name
             del self.schema.tables[self.name]
             self.schema = self.schema.model.schemas[changed['schema_name']]
+            for key in self.keys:
+                if key.constraint_schema:
+                    key.constraint_schema = self.schema
             for fkey in self.foreign_keys:
                 if fkey.constraint_schema:
                     del fkey.constraint_schema._fkeys[fkey.constraint_name]
                     fkey.constraint_schema = self.schema
                     fkey.constraint_schema._fkeys[fkey.constraint_name] = fkey
             self.schema.tables[self.name] = self
+            if update_mappings:
+                for key in self.keys:
+                    mmo.replace(self.schema.model, [old_schema_name] + [key.constraint_name], [self.schema.name] + [key.constraint_name])
+                for fkey in self.foreign_keys:
+                    mmo.replace(self.schema.model, [old_schema_name] + [fkey.constraint_name], [self.schema.name] + [fkey.constraint_name])
+                if update_mappings == UpdateMappings.immediate:
+                    self.schema.model.apply()
 
         if 'comment' in changes:
             self.comment = changed['comment']
@@ -1501,7 +1795,7 @@ class Table (object):
             created = created[0]
         return registerfunc(constructor(self, created))
 
-    def create_column(self, column_def):
+    def create_column(self, column_def: dict) -> Column:
         """Add a new column to this table in the remote database based on column_def.
 
            Returns a new Column instance based on the server-supplied
@@ -1516,7 +1810,7 @@ class Table (object):
             return col
         return self._create_table_part('column', add_column, Column, column_def)
 
-    def create_key(self, key_def):
+    def create_key(self, key_def: dict) -> Key:
         """Add a new key to this table in the remote database based on key_def.
 
            Returns a new Key instance based on the server-supplied
@@ -1529,12 +1823,12 @@ class Table (object):
             return key
         return self._create_table_part('key', add_key, Key, key_def)
 
-    def create_fkey(self, fkey_def):
+    def create_fkey(self, fkey_def: dict) -> ForeignKey:
         """Add a new foreign key to this table in the remote database based on fkey_def.
 
            Returns a new ForeignKey instance based on the
            server-supplied representation of the new foreign key, and
-           adds it to self.fkeys too.
+           adds it to self.foreign_keys too.
 
         """
         def add_fkey(fkey):
@@ -1543,16 +1837,53 @@ class Table (object):
             return fkey
         return self._create_table_part('foreignkey', add_fkey, ForeignKey, fkey_def)
 
-    def drop(self):
+    def create_reference(
+        self,
+        target: Key | Table | tuple[str, bool, Key | Table] | tuple[str, Key | Table],
+        key_column_search_order: Iterable[str] | None = None,
+    ) -> tuple[ list[Column], ForeignKey ]:
+        """Add column(s) and a foreign key to this table in the remote database for a reference target.
+
+        See Table.define() documentation for more about reference
+        targets.
+
+        Returns a list of new Column instances and a ForeignKey instance based on
+        the server-supplied representation of the new model elements, and
+        adds them to the self.columns and self.foreign_keys too.
+
+        """
+        used_names = { col.name for col in self.columns }
+        cdefs, fkdefs = self._expand_references(self.name, [ target ], [], used_names, key_column_search_order)
+        if not cdefs or len(fkdefs) != 1:
+            raise NotImplementedError("BUG? got unexpected results from self._expand_reference()")
+        cols = [ self.create_column(cdef) for cdef in cdefs ]
+        fkeys = [ self.create_fkey(fkdef) for fkdef in fkdefs ]
+        return cols, fkeys[0]
+
+    def drop(self, cascade=False, update_mappings=UpdateMappings.no_update):
         """Remove this table from the remote database.
+
+        :param cascade: drop dependent objects.
+        :param update_mappings: update annotations to reflect changes (default False)
         """
         if self.name not in self.schema.tables:
             raise ValueError('Table %s does not appear to belong to schema %s.' % (self, self.schema))
+
+        if cascade:
+            for fkey in list(self.referenced_by):
+                fkey.drop(update_mappings=update_mappings)
+
         self.catalog.delete(self.uri_path).raise_for_status()
         del self.schema.tables[self.name]
         for fkey in self.foreign_keys:
             fkey._cleanup()
 
+        if update_mappings:
+            for fkey in self.foreign_keys:
+                mmo.prune(self.schema.model, [fkey.constraint_schema.name, fkey.constraint_name])
+            if update_mappings == UpdateMappings.immediate:
+                self.schema.model.apply()
+
     def key_by_columns(self, unique_columns, raise_nomatch=True):
         """Return key from self.keys with matching unique columns.
 
@@ -1742,7 +2073,39 @@ class Table (object):
                         # arbitrarily choose first fkey to self
                         # in case association is back to same table
                         break
-    
+
+    def sqlite3_table_name(self) -> str:
+        """Return SQLite3 mapped table name for this table"""
+        return "%s:%s" % (
+            self.schema.name,
+            self.name,
+        )
+
+    def sqlite3_ddl(self, keys: bool=True) -> str:
+        """Return SQLite3 table definition DDL statement for this table.
+
+        :param keys: If true, include unique constraints for each table key
+
+        Caveat: this utility does not produce:
+        - column default expressions
+        - foreign key constraint DDL
+
+        Both of these features are fragile in data export scenarios
+        where we want to represent arbitrary ERMrest catalog dumps.
+
+        """
+        parts = [ col.sqlite3_ddl() for col in self.columns ]
+        if keys:
+            parts.extend([ key.sqlite3_ddl() for key in self.keys ])
+        return ("""
+CREATE TABLE IF NOT EXISTS %(tname)s (
+  %(body)s
+);
+""" % {
+    'tname': sql_identifier(self.sqlite3_table_name()),
+    'body': ',\n  '.join(parts),
+})
+
     @presence_annotation(tag.immutable)
     def immutable(self): pass
 
@@ -1840,6 +2203,17 @@ class Column (object):
         self.default = column_doc.get('default')
         self.comment = column_doc.get('comment')
 
+    def __repr__(self):
+        cls = type(self)
+        return "<%s.%s object %r.%r.%r at 0x%x>" % (
+            cls.__module__,
+            cls.__name__,
+            self.table.schema.name if self.table is not None and self.table.schema is not None else None,
+            self.table.name if self.table is not None else None,
+            self.name,
+            id(self),
+        )
+
     @property
     def catalog(self):
         return self.table.schema.model.catalog
@@ -1934,7 +2308,8 @@ class Column (object):
             comment=nochange,
             acls=nochange,
             acl_bindings=nochange,
-            annotations=nochange
+            annotations=nochange,
+            update_mappings=UpdateMappings.no_update
     ):
         """Alter existing schema definition.
 
@@ -1946,6 +2321,7 @@ class Column (object):
         :param acls: Replacement ACL configuration (default nochange)
         :param acl_bindings: Replacement ACL bindings (default nochange)
         :param annotations: Replacement annotations (default nochange)
+        :param update_mappings: Update annotations to reflect changes (default UpdateMappings.no_updates)
 
         Returns self (to allow for optional chained access).
 
@@ -1972,8 +2348,14 @@ class Column (object):
 
         if 'name' in changes:
             del self.table.column_definitions.elements[self.name]
+            oldname = self.name
             self.name = changed['name']
             self.table.column_definitions.elements[self.name] = self
+            if update_mappings:
+                basename = [self.table.schema.name, self.table.name]
+                mmo.replace(self.table.schema.model, basename + [oldname], basename + [self.name])
+                if update_mappings == UpdateMappings.immediate:
+                    self.table.schema.model.apply()
 
         if 'type' in changes:
             self.type = make_type(changed['type'])
@@ -2001,14 +2383,41 @@ class Column (object):
 
         return self
 
-    def drop(self):
+    def drop(self, cascade=False, update_mappings=UpdateMappings.no_update):
         """Remove this column from the remote database.
+
+        :param cascade: drop dependent objects (default False)
+        :param update_mappings: Update annotations to reflect changes (default UpdateMappings.no_updates)
         """
         if self.name not in self.table.column_definitions.elements:
             raise ValueError('Column %s does not appear to belong to table %s.' % (self, self.table))
+
+        if cascade:
+            for fkey in list(self.table.foreign_keys):
+                if self in fkey.foreign_key_columns:
+                    fkey.drop(update_mappings=update_mappings)
+            for key in list(self.table.keys):
+                if self in key.unique_columns:
+                    key.drop(cascade=True, update_mappings=update_mappings)
+
         self.catalog.delete(self.uri_path).raise_for_status()
         del self.table.column_definitions[self.name]
 
+        if update_mappings:
+            mmo.prune(self.table.schema.model, [self.table.schema.name, self.table.name, self.name])
+            if update_mappings == UpdateMappings.immediate:
+                self.table.schema.model.apply()
+
+    def sqlite3_ddl(self) -> str:
+        """Return SQLite3 column definition DDL fragment for this column."""
+        parts = [
+            sql_identifier(self.name),
+            self.type.sqlite3_ddl(),
+        ]
+        if not self.nullok:
+            parts.append('NOT NULL')
+        return ' '.join(parts)
+
     @presence_annotation(tag.immutable)
     def immutable(self): pass
 
@@ -2036,6 +2445,19 @@ def _constraint_name_parts(constraint, doc):
         constraint_schema = None
     elif names[0][0] == constraint.table.schema.name:
         constraint_schema = constraint.table.schema
+    elif names[0][0] == 'placeholder':
+        # mitigate ermrest API response bug reflecting our 'placeholder' value
+        if constraint.table.kind == 'table':
+            if isinstance(constraint, Key):
+                constraint_schema = constraint.table.schema
+            elif isinstance(constraint, ForeignKey):
+                # HACK: mostly correct for regular ermrest users
+                # may be revised later during fkey digest for irregular cases with SQL views!
+                constraint_schema = constraint.table.schema
+            else:
+                raise TypeError('_constraint_name_parts requires a Key or ForeignKey constraint argument, not %s' % (constraint,))
+        else:
+            constraint_schema = None
     else:
         raise ValueError('Unexpected schema name in constraint %s' % (names[0],))
     constraint_name = names[0][1]
@@ -2057,6 +2479,16 @@ class Key (object):
             for cname in key_doc['unique_columns']
         ])
 
+    def __repr__(self):
+        cls = type(self)
+        return "<%s.%s object %r.%r at 0x%x>" % (
+            cls.__module__,
+            cls.__name__,
+            self.constraint_schema.name if self.constraint_schema is not None else None,
+            self.constraint_name,
+            id(self),
+        )
+
     @property
     def columns(self):
         """Sugared access to self.unique_columns"""
@@ -2174,13 +2606,15 @@ class Key (object):
             self,
             constraint_name=nochange,
             comment=nochange,
-            annotations=nochange
+            annotations=nochange,
+            update_mappings=UpdateMappings.no_update
     ):
         """Alter existing schema definition.
 
         :param constraint_name: Unqualified constraint name string
         :param comment: Replacement comment (default nochange)
         :param annotations: Replacement annotations (default nochange)
+        :param update_mappings: Update annotations to reflect changes (default UpdateMappings.no_updates)
 
         Returns self (to allow for optional chained access).
 
@@ -2200,7 +2634,13 @@ class Key (object):
         changed = r.json() # use changed vs changes to get server-digested values
 
         if 'names' in changes:
+            oldname = self.constraint_name
             self.constraint_name = changed['names'][0][1]
+            if update_mappings:
+                basename = [self.table.schema.name]
+                mmo.replace(self.table.schema.model, basename + [oldname], basename + [self.constraint_name])
+                if update_mappings == UpdateMappings.immediate:
+                    self.table.schema.model.apply()
 
         if 'comment' in changes:
             self.comment = changed['comment']
@@ -2211,14 +2651,34 @@ class Key (object):
 
         return self
 
-    def drop(self):
+    def drop(self, cascade=False, update_mappings=UpdateMappings.no_update):
         """Remove this key from the remote database.
+
+        :param cascade: drop dependent objects (default False)
+        :param update_mappings: Update annotations to reflect changes (default UpdateMappings.no_updates)
         """
         if self.name not in self.table.keys.elements:
             raise ValueError('Key %s does not appear to belong to table %s.' % (self, self.table))
+
+        if cascade:
+            for fkey in list(self.table.referenced_by):
+                assert self.table == fkey.pk_table, "Expected key.table and foreign_key.pk_table to match"
+                if set(self.unique_columns) == set(fkey.referenced_columns):
+                    fkey.drop(update_mappings=update_mappings)
+
         self.catalog.delete(self.uri_path).raise_for_status()
         del self.table.keys[self.name]
 
+        if update_mappings:
+            mmo.prune(self.table.schema.model, [self.constraint_schema.name, self.constraint_name])
+            if update_mappings == UpdateMappings.immediate:
+                self.table.schema.model.apply()
+
+    def sqlite3_ddl(self) -> str:
+        """Return SQLite3 unique constraint DDL fragment for this key."""
+        parts = [ sql_identifier(col.name) for col in self.unique_columns ]
+        return 'UNIQUE (%s)' % (', '.join(parts),)
+
 class ForeignKey (object):
     """Named foreign key.
     """
@@ -2246,6 +2706,16 @@ class ForeignKey (object):
         self._referenced_columns_doc = fkey_doc['referenced_columns']
         self.referenced_columns = None
 
+    def __repr__(self):
+        cls = type(self)
+        return "<%s.%s object %r.%r at 0x%x>" % (
+            cls.__module__,
+            cls.__name__,
+            self.constraint_schema.name if self.constraint_schema is not None else None,
+            self.constraint_name,
+            id(self),
+        )
+
     def digest_referenced_columns(self, model):
         """Finish construction deferred until model is known with all tables."""
         if self.referenced_columns is None:
@@ -2258,6 +2728,13 @@ class ForeignKey (object):
             ])
             self._referenced_columns_doc = None
             self.pk_table.referenced_by.append(self)
+            # HACK: clean up schema qualification for psuedo constraint
+            # this may happen only with SQL views in the ermrest catalog
+            if self.pk_table.kind != 'table' and self.constraint_name in self.table.schema._fkeys:
+                del self.table.schema._fkeys[self.constraint_name]
+                self.table.schema.model._fkeys[self.constraint_name] = self
+                del self.table.foreign_keys.elements[(self.table.schema, self.constraint_name)]
+                self.table.foreign_keys.elements[(None, self.constraint_name)] = self
 
     @property
     def column_map(self):
@@ -2437,7 +2914,8 @@ class ForeignKey (object):
             comment=nochange,
             acls=nochange,
             acl_bindings=nochange,
-            annotations=nochange
+            annotations=nochange,
+            update_mappings=UpdateMappings.no_update
     ):
         """Alter existing schema definition.
 
@@ -2448,6 +2926,7 @@ class ForeignKey (object):
         :param acls: Replacement ACL configuration (default nochange)
         :param acl_bindings: Replacement ACL bindings (default nochange)
         :param annotations: Replacement annotations (default nochange)
+        :param update_mappings: Update annotations to reflect changes (default UpdateMappings.no_updates)
 
         Returns self (to allow for optional chained access).
 
@@ -2475,11 +2954,17 @@ class ForeignKey (object):
                 del self.constraint_schema._fkeys[self.constraint_name]
             else:
                 del self.table.schema.model._pseudo_fkeys[self.constraint_name]
+            oldname = self.constraint_name
             self.constraint_name = changed['names'][0][1]
             if self.constraint_schema:
                 self.constraint_schema._fkeys[self.constraint_name] = self
             else:
                 self.table.schema.model._pseudo_fkeys[self.constraint_name] = self
+            if update_mappings:
+                basename = [self.table.schema.name]
+                mmo.replace(self.table.schema.model, basename + [oldname], basename + [self.constraint_name])
+                if update_mappings == UpdateMappings.immediate:
+                    self.table.schema.model.apply()
 
         if 'on_update' in changes:
             self.on_update = changed['on_update']
@@ -2504,8 +2989,10 @@ class ForeignKey (object):
 
         return self
 
-    def drop(self):
+    def drop(self, update_mappings=UpdateMappings.no_update):
         """Remove this foreign key from the remote database.
+
+        :param update_mappings: Update annotations to reflect changes (default UpdateMappings.no_updates)
         """
         if self.name not in self.table.foreign_keys.elements:
             raise ValueError('Foreign key %s does not appear to belong to table %s.' % (self, self.table))
@@ -2513,6 +3000,11 @@ class ForeignKey (object):
         del self.table.foreign_keys[self.name]
         self._cleanup()
 
+        if update_mappings:
+            mmo.prune(self.table.schema.model, [self.constraint_schema.name, self.constraint_name])
+            if update_mappings == UpdateMappings.immediate:
+                self.table.schema.model.apply()
+
     def _cleanup(self):
         """Cleanup references in the local model following drop from remote database.
         """
@@ -2548,6 +3040,22 @@ class Type (object):
         }
         return d
 
+    def sqlite3_ddl(self) -> str:
+        """Return a SQLite3 column type DDL fragment for this type"""
+        return {
+            'boolean': 'boolean',
+            'date': 'date',
+            'float4': 'real',
+            'float8': 'real',
+            'int2': 'integer',
+            'int4': 'integer',
+            'int8': 'integer',
+            'json': 'json',
+            'jsonb': 'json',
+            'timestamptz': 'datetime',
+            'timestamp': 'datetime',
+        }.get(self.typename, 'text')
+
 class DomainType (Type):
     """Named domain type.
     """
@@ -2564,6 +3072,10 @@ class DomainType (Type):
         })
         return d
 
+    def sqlite3_ddl(self) -> str:
+        """Return a SQLite3 column type DDL fragment for this type"""
+        return self.base_type.sqlite3_ddl()
+
 class ArrayType (Type):
     """Named domain type.
     """
@@ -2580,6 +3092,10 @@ class ArrayType (Type):
         })
         return d
 
+    def sqlite3_ddl(self) -> str:
+        """Return a SQLite3 column type DDL fragment for this type"""
+        return 'json'
+
 builtin_types = AttrDict(
     # first define standard scalar types
     {