deriva 1.7.1__py3-none-any.whl → 1.7.4__py3-none-any.whl

deriva/core/ermrest_model.py

@@ -1,9 +1,16 @@
 
-from collections import OrderedDict
+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
+
+from . import AttrDict, tag, urlquote, stob, mmo
 
-from . import AttrDict, tag, urlquote, stob
 
 class NoChange (object):
     """Special class used to distinguish no-change default arguments to methods.
@@ -17,6 +24,93 @@ 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.
+
+    Naively, append as '_'.join(components).
+
+    Fallback to heuristics mixing truncation with short hashes.
+    """
+    # accept lists at top-level for convenience (compound keys, etc.)
+    expanded = []
+    for e in components:
+        if isinstance(e, list):
+            expanded.extend(e)
+        else:
+            expanded.append(e)
+
+    # prefer to use naive name as requested
+    naive_result = '_'.join(expanded)
+    naive_len = len(naive_result.encode('utf8'))
+    if naive_len <= 63:
+        return naive_result
+
+    # we'll need to truncate and hash in some way...
+    def hash(s, nbytes):
+        return base64.urlsafe_b64encode(hashlib.md5(s.encode('utf8')).digest()).decode()[0:nbytes]
+
+    def truncate(s, maxlen):
+        encoded_len = len(s.encode('utf8'))
+        # we need to chop whole (unicode) chars but test encoded byte lengths!
+        for i in range(max(1, len(s) - maxlen), len(s) - 1):
+            result = s[0:-1 * i].rstrip()
+            if len(result.encode('utf8')) <= (maxlen - 2):
+                return result + '..'
+        return s
+
+    naive_hash = hash(naive_result, 5)
+    parts = [
+        (i, expanded[i])
+        for i in range(len(expanded))
+    ]
+
+    # try to find a solution truncating individual fields
+    for maxlen in [15, 12, 9]:
+        parts.sort(key=lambda p: (len(p[1].encode('utf8')), p[0]), reverse=True)
+        for i in range(len(parts)):
+            idx, part = parts[i]
+            if len(part.encode('utf8')) > maxlen:
+                parts[i] = (idx, truncate(part, maxlen))
+            candidate_result = '_'.join([
+                p[1]
+                for p in sorted(parts, key=lambda p: p[0])
+            ] + [naive_hash])
+            if len(candidate_result.encode('utf8')) < 63:
+                return candidate_result
+
+    # fallback to truncating original naive name
+    # try to preserve suffix and trim in middle
+    result = ''.join([
+        truncate(naive_result, len(naive_result)//3),
+        naive_result[-len(naive_result)//3:],
+        '_',
+        naive_hash
+    ])
+    if len(result.encode('utf8')) <= 63:
+        return result
+
+    # 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.
 
@@ -447,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
@@ -551,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,
@@ -574,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']
@@ -612,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():
@@ -684,9 +800,20 @@ class KeyedList (list):
         list.append(self, e)
         self.elements[e.name] = e
 
+class FindAssociationResult (object):
+    """Wrapper for results of Table.find_associations()"""
+    def __init__(self, table, self_fkey, other_fkeys):
+        self.table = table
+        self.name = table.name
+        self.schema = table.schema
+        self.self_fkey = self_fkey
+        self.other_fkeys = other_fkeys
+    
 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
@@ -709,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"""
@@ -742,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
@@ -763,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,
@@ -781,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
@@ -795,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.
@@ -805,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):
@@ -855,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
@@ -899,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
@@ -907,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)
@@ -956,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
@@ -977,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),
@@ -986,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):
@@ -1033,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 [
@@ -1063,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),
@@ -1072,7 +1492,129 @@ 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
+    def define_association(
+        cls,
+        associates: Iterable[Key | Table | tuple[str, Key | Table]],
+        metadata: Iterable[Key | Table | dict | tuple[str, bool, Key | Table]] = [],
+        table_name: str | None = None,
+        comment: str | None = None,
+        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: 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
+        control. For full customization, consider using Table.define()
+        directly instead.
+
+        A normal ("pure") N-ary association is a table with N foreign
+        keys referencing N primary keys in referenced tables, with a
+        composite primary key covering the N foreign keys. These pure
+        association tables manage a set of distinct combinations of
+        the associated foreign key values.
+
+        An "impure" association table adds additional metadata
+        alongside the N foreign keys.
+
+        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')
+
+        used_names = set()
+
+        for assoc in associates:
+            if not isinstance(assoc, (tuple, Table, Key)):
+                raise TypeError("Associates must be Table or Key instances, not %s" % (assoc,))
+
+        # 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)
+
+        if table_name is None:
+            # 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 fkdef in fkdefs:
+            k_cnames.extend([ colref["column_name"] for colref in fkdef["foreign_key_columns"] ])
+
+        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,
         )
 
     def prejson(self, prune=True):
@@ -1155,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.
 
@@ -1165,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
@@ -1192,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']
@@ -1240,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
@@ -1255,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
@@ -1268,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):
@@ -1282,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.
 
@@ -1348,7 +1940,7 @@ class Table (object):
         if raise_nomatch:
             raise KeyError(from_to_map)
 
-    def is_association(self, min_arity=2, max_arity=2, unqualified=True, pure=True, no_overlap=True):
+    def is_association(self, min_arity=2, max_arity=2, unqualified=True, pure=True, no_overlap=True, return_fkeys=False):
         """Return (truthy) integer arity if self is a matching association, else False.
 
         min_arity: minimum number of associated fkeys (default 2)
@@ -1356,6 +1948,7 @@ class Table (object):
         unqualified: reject qualified associations when True (default True)
         pure: reject impure assocations when True (default True)
         no_overlap: reject overlapping associations when True (default True)
+        return_fkeys: return the set of N associated ForeignKeys if True
 
         The default behavior with no arguments is to test for pure,
         unqualified, non-overlapping, binary assocations.
@@ -1444,8 +2037,74 @@ class Table (object):
             # reject: impure association
             return False
 
-        # return (truthy) arity
-        return len(covered_fkeys)
+        # return (truthy) arity or fkeys
+        if return_fkeys:
+            return covered_fkeys
+        else:
+            return len(covered_fkeys)
+
+    def find_associations(self, min_arity=2, max_arity=2, unqualified=True, pure=True, no_overlap=True) -> Iterable[FindAssociationResult]:
+        """Yield (iterable) Association objects linking to this table and meeting all criteria.
+
+        min_arity: minimum number of associated fkeys (default 2)
+        max_arity: maximum number of associated fkeys (default 2) or None
+        unqualified: reject qualified associations when True (default True)
+        pure: reject impure assocations when True (default True)
+        no_overlap: reject overlapping associations when True (default True)
+
+        See documentation for sibling method Table.is_association(...)
+        for more explanation of these association detection criteria.
+
+        """
+        peer_tables = set()
+        for fkey in self.referenced_by:
+            peer = fkey.table
+            if peer in peer_tables:
+                # check each peer only once
+                continue
+            peer_tables.add(peer)
+            answer = peer.is_association(min_arity=min_arity, max_arity=max_arity, unqualified=unqualified, pure=pure, no_overlap=no_overlap, return_fkeys=True)
+            if answer:
+                answer = set(answer)
+                for fkey in answer:
+                    if fkey.pk_table == self:
+                        answer.remove(fkey)
+                        yield FindAssociationResult(peer, fkey, answer)
+                        # 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
@@ -1495,6 +2154,40 @@ class Table (object):
     @object_annotation(tag.viz_3d_display)
     def viz_3d_display(self): pass
     
+class Quantifier (str, Enum):
+    """Logic quantifiers"""
+    any = 'any'
+    all = 'all'
+
+def find_tables_with_foreign_keys(target_tables: Iterable[Table], quantifier: Quantifier=Quantifier.all) -> set[Table]:
+    """Return set of tables with foreign key references to target tables.
+
+    :param target_tables: an iterable of ermrest_model.Table instances
+    :param quantifier: one of the Quantifiers 'any' or 'all' (default 'all')
+
+    Each returned Table instance will be a table that references the
+    targets according to the selected quantifier. A reference is a
+    direct foreign key in the returned table that refers to a primary
+    key of the target table.
+
+    - quantifier==all: a returned table references ALL targets
+    - quantifier==any: a returned table references AT LEAST ONE target
+
+    For proper function, all target_tables instances MUST come from
+    the same root Model instance hierarchy.
+
+    """
+    candidates = None
+    for table in target_tables:
+        referring = { fkey.table for fkey in table.referenced_by }
+        if candidates is None:
+            candidates = referring
+        elif quantifier == Quantifier.all:
+            candidates.intersection_update(referring)
+        else:
+            candidates.update(referring)
+    return candidates
+
 class Column (object):
     """Named column.
     """
@@ -1510,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
@@ -1604,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.
 
@@ -1616,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).
 
@@ -1642,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'])
@@ -1671,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
 
@@ -1696,7 +2435,6 @@ class Column (object):
 
     @object_annotation(tag.column_display)
     def column_display(self): pass
-    
 
 def _constraint_name_parts(constraint, doc):
     # modern systems should have 0 or 1 names here
@@ -1707,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]
@@ -1728,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"""
@@ -1781,10 +2542,29 @@ class Key (object):
         }
 
     @classmethod
-    def define(cls, colnames, constraint_names=[], comment=None, annotations={}):
-        """Build a key definition."""
+    def define(cls, colnames, constraint_names=[], comment=None, annotations={}, constraint_name=None):
+        """Build a key definition.
+
+        :param colnames: List of names of columns participating in the key
+        :param constraint_names: Legacy input [ [ schema_name, constraint_name ] ] (for API backwards-compatibility)
+        :param comment: Comment string
+        :param annotations: Dictionary of { annotation_uri: annotation_value, ... }
+        :param constraint_name: Constraint name string
+
+        The constraint_name kwarg takes a bare constraint name string
+        and acts the same as setting the legacy constraint_names kwarg
+        to: [ [ "placeholder", constraint_name ] ].  This odd syntax
+        is for backwards-compatibility with earlier API versions, and
+        mirrors the structure of constraint names in ERMrest model
+        description outputs. In those outputs, the "placeholder" field
+        contains the schema name of the table containing the
+        constraint.
+
+        """
         if not isinstance(colnames, list):
             raise TypeError('Colnames should be a list.')
+        if constraint_name is not None:
+            constraint_names = [ [ "placeholder", constraint_name ] ]
         return {
             'unique_columns': list(colnames),
             'names': constraint_names,
@@ -1826,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).
 
@@ -1852,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']
@@ -1863,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.
     """
@@ -1898,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:
@@ -1910,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):
@@ -1983,9 +2808,41 @@ class ForeignKey (object):
         }
 
     @classmethod
-    def define(cls, fk_colnames, pk_sname, pk_tname, pk_colnames, on_update='NO ACTION', on_delete='NO ACTION', constraint_names=[], comment=None, acls={}, acl_bindings={}, annotations={}):
+    def define(cls, fk_colnames, pk_sname, pk_tname, pk_colnames, on_update='NO ACTION', on_delete='NO ACTION', constraint_names=[], comment=None, acls={}, acl_bindings={}, annotations={}, constraint_name=None):
+        """Define a foreign key.
+
+        :param fk_colnames: List of column names participating in the foreign key
+        :param pk_sname: Schema name string of the referenced primary key
+        :param pk_tname: Table name string of the referenced primary key
+        :param pk_colnames: List of column names participating in the referenced primary key
+        :param on_update: Constraint behavior when referenced primary keys are updated
+        :param on_update: Constraint behavior when referenced primary keys are deleted
+        :param constraint_names: Legacy input [ [ schema_name, constraint_name ] ] (for API backwards-compatibility)
+        :param comment: Comment string
+        :param acls: Dictionary of { acl_name: acl, ... }
+        :param acl_bindings: Dictionary of { binding_name: acl_binding, ... }
+        :param annotations: Dictionary of { annotation_uri: annotation_value, ... }
+        :param constraint_name: Constraint name string
+
+        The contraint behavior values for on_update and on_delete must
+        be one of the following literal strings:
+
+        'NO ACTION', 'RESTRICT', 'CASCADE', 'SET NULL', 'SET DEFAULT'
+
+        The constraint_name kwarg takes a bare constraint name string
+        and acts the same as setting the legacy constraint_names kwarg
+        to: [ [ "placeholder", constraint_name ] ].  This odd syntax
+        is for backwards-compatibility with earlier API versions, and
+        mirrors the structure of constraint names in ERMrest model
+        description outputs. In those outputs, the "placeholder" field
+        contains the schema name of the table containing the
+        constraint.
+
+        """
         if len(fk_colnames) != len(pk_colnames):
             raise ValueError('The fk_colnames and pk_colnames lists must have the same length.')
+        if constraint_name is not None:
+            constraint_names = [ [ "placeholder", constraint_name ], ]
         return {
             'foreign_key_columns': [
                 {
@@ -2057,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.
 
@@ -2068,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).
 
@@ -2095,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']
@@ -2124,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))
@@ -2133,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.
         """
@@ -2168,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.
     """
@@ -2184,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.
     """
@@ -2200,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
     {