make+tools: add custom sqlfluff plugin

Author: guggero

Makefile

@@ -57,6 +57,9 @@ DOCKER_TOOLS = docker run \
   -v $(shell bash -c "mkdir -p /tmp/go-lint-cache; echo /tmp/go-lint-cache"):/root/.cache/golangci-lint \
   -v $$(pwd):/build taproot-assets-tools
 
+DOCKER_SQLFLUFF = docker run --rm --user "$$UID:$$(id -g)" -e UID=$$UID \
+	-v $(shell pwd):/sql sqlfluff-builder
+
 GO_VERSION = 1.23.9
 
 GREEN := "\\033[0;32m"
@@ -149,6 +152,10 @@ docker-tools:
 	@$(call print, "Building tools docker image.")
 	docker build -q -t taproot-assets-tools $(TOOLS_DIR)
 
+docker-sqlfluff:
+	@$(call print, "Building sqlfluff docker image.")
+	docker build -q -t sqlfluff-builder tools/sqlfluff
+
 scratch: build
 
 # ===================
@@ -268,6 +275,12 @@ sqlc-check: sqlc
 		exit 1; \
 	fi
 
+sql-lint: docker-sqlfluff
+	$(DOCKER_SQLFLUFF) lint tapdb/sqlc/migrations/* tapdb/sqlc/queries/*
+
+sql-fix: docker-sqlfluff
+	$(DOCKER_SQLFLUFF) fix tapdb/sqlc/migrations/* tapdb/sqlc/queries/*
+
 rpc:
 	@$(call print, "Compiling protos.")
 	cd ./taprpc; ./gen_protos_docker.sh

tools/sqlfluff/Dockerfile

@@ -0,0 +1,14 @@
+FROM sqlfluff/sqlfluff:latest
+
+COPY sqlfluff_plugin_ref_type/ /plugins/sqlfluff_plugin_ref_type/
+
+ENV PYTHONPATH="/plugins/sqlfluff_plugin_ref_type"
+
+USER root
+
+RUN cd /plugins/sqlfluff_plugin_ref_type \
+    chown -R 5000 . \
+    && chmod -R 777 /plugins /sql \
+    && pip install -e .
+
+USER 5000

tools/sqlfluff/sqlfluff_plugin_ref_type/pyproject.toml

@@ -0,0 +1,14 @@
+[build-system]
+requires = ["setuptools>=40.8.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "sqlfluff_plugin_ref_type"
+version = "1.0.0"
+requires-python = ">=3.9"
+dependencies = [
+    "sqlfluff>=3.1.0"
+]
+
+[project.entry-points.sqlfluff]
+sqlfluff_plugin_ref_type = "sqlfluff_plugin_ref_type"

tools/sqlfluff/sqlfluff_plugin_ref_type/sqlfluff_plugin_ref_type/__init__.py

@@ -0,0 +1,32 @@
+"""A plugin that checks for forbidden foreign key types in SQL
+
+This uses the rules API supported from 0.4.0 onwards.
+"""
+
+from typing import Any
+
+from sqlfluff.core.config import load_config_resource
+from sqlfluff.core.plugin import hookimpl
+from sqlfluff.core.rules import BaseRule, ConfigInfo
+
+
+@hookimpl
+def get_rules() -> list[type[BaseRule]]:
+    """Get plugin rules.
+    """
+    # i.e. we DO recommend importing here:
+    from .rules import Rule_LL01  # noqa: F811
+
+    return [Rule_LL01]
+
+
+@hookimpl
+def load_default_config() -> dict[str, Any]:
+    """Loads the default configuration for the plugin."""
+    return {}
+
+
+@hookimpl
+def get_configs_info() -> dict[str, dict[str, ConfigInfo]]:
+    """Get rule config validations and descriptions."""
+    return {}

tools/sqlfluff/sqlfluff_plugin_ref_type/sqlfluff_plugin_ref_type/rules.py

@@ -0,0 +1,79 @@
+"""A custom rule that checks for forbidden INTEGER foreign keys.
+
+This uses the rules API supported from 0.4.0 onwards.
+"""
+
+from sqlfluff.core.rules import (
+    BaseRule,
+    LintResult,
+    RuleContext,
+)
+from sqlfluff.core.rules.crawlers import SegmentSeekerCrawler
+from sqlfluff.utils.functional import FunctionalContext, sp
+
+
+# These two decorators allow plugins
+# to be displayed in the sqlfluff docs
+class Rule_LL01(BaseRule):
+    """INTEGER ... REFERENCES is forbidden! Use BIGINT instead.
+
+    **Anti-pattern**
+
+    Using ``INTEGER ... REFERENCES`` in a foreign key definition is creating
+    a mismatch between the actual data type of the referenced primary key and
+    the foreign key. See ``scripts/gen_sqlc_docker.sh`` for a long-form
+    explanation.
+
+    .. code-block:: sql
+
+        transfer_id INTEGER NOT NULL REFERENCES asset_transfers (id),
+
+    **Best practice**
+
+    If the primary key of the referenced table is of type
+    ``INTEGER PRIMARY KEY``, it will be transformed to ``BIGSERIAL`` in
+    PostgreSQL. Therefore, the foreign key should also be of type ``BIGINT``.
+    For SQLite both INTEGER and BIGINT are equivalent, so this rule is for
+    PostgreSQL.
+
+    .. code-block:: sql
+
+        transfer_id BIGINT NOT NULL REFERENCES asset_transfers (id),
+    """
+
+    groups = ("all",)
+    crawl_behaviour = SegmentSeekerCrawler({"column_definition"})
+    is_fix_compatible = True
+
+    def __init__(self, *args, **kwargs):
+        """Overwrite __init__ to set config."""
+        super().__init__(*args, **kwargs)
+
+    def _eval(self, context: RuleContext):
+        """We should not use INTEGER ... REFERENCES."""
+        has_integer = False
+        has_reference = False
+        data_type_segment = None
+
+        for child in context.segment.segments:
+            if child.type == "data_type":
+                # Check if any part of data_type is INTEGER.
+                for part in child.segments:
+                    if part.raw.upper() == "INTEGER":
+                        has_integer = True
+                        data_type_segment = part
+            elif child.type == "column_constraint_segment":
+                # Look for REFERENCES keyword inside constraints.
+                for subpart in child.segments:
+                    if "REFERENCES" in subpart.raw.upper():
+                        has_reference = True
+
+        if has_integer and has_reference:
+            return LintResult(
+                anchor=data_type_segment,
+                description="Must use BIGINT instead of INTEGER as a data "
+                            "type in foreign key references. See "
+                            "scripts/gen_sqlc_docker.sh for explanation.",
+            )
+
+        return None