dameng-rails 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 31605a94e92ed817c32ec8f0e40382a994e4b0d3dbab66e4ea0deeb9559561bb
+  data.tar.gz: 0adae4275c6fb981fa04c620ff388bf748db5ea74aa39d5fc17eaee71ff0ac31
+SHA512:
+  metadata.gz: a13c115aaab33f595051b3be0f964900983c8f48c11fd1aedc0d4270d8d95c9f3eba900b21325fe063622087a8462d0603d4cf3e9f6b53000893457a78367a95
+  data.tar.gz: f20958ce3fbbceed43683e2d4d206f001fa82a5b53f2a4e01d93aea47c2a4d8e3d645f305d21bab0837cc6f8f519787ebfe5e0737b7f93f670811321fa2878f4

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 qinyuanmao
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,95 @@
+# dm-rails
+
+让 Ruby on Rails 运行在达梦数据库（DM8）上。
+
+Run Ruby on Rails on DM (Dameng) database — via a MySQL-protocol proxy, no Ruby driver needed.
+
+## 背景
+
+达梦没有 Ruby 驱动，也没有 ActiveRecord 适配器，Rails 无法直连。dm-rails 采用「协议桥接」路线：
+
+```
+Rails (mysql2 适配器，零改动)
+  │  MySQL 协议
+  ▼
+ShardingSphere-Proxy 5.5.0 + 本仓库达梦 SPI 适配包（proxy/ss-dm-dialect）
+  │  达梦 JDBC
+  ▼
+达梦 DM8（MySQL 兼容模式）
+```
+
+gem 负责 Ruby 侧：把 ActiveRecord 的 MySQL 自省语句（`SHOW FULL FIELDS` / `SHOW KEYS` /
+`SHOW CREATE TABLE` / `information_schema`——代理与达梦均不支持）替换为查询达梦侧辅助视图。
+
+本方案在一套生产环境 Rails 7.1 IoT 平台上完整验证（含 migration、seed、动态查询、定时任务）。
+
+## 达梦实例要求（硬性）
+
+初始化参数（`dminit`）：
+
+| 参数 | 值 | 说明 |
+|---|---|---|
+| `CHARSET` | `1` (UTF-8) | 初始化级，装错重建 |
+| `CASE_SENSITIVE` | `0`（不敏感） | **成败关键**：Rails 经代理发出的是反引号小写标识符 |
+| `COMPATIBLE_MODE`(dm.ini) | `4` (MySQL) | 可改配置后重启生效 |
+
+## 安装
+
+### 1. Ruby 侧
+
+```ruby
+# Gemfile
+gem "dameng-rails"   # rubygems.org（源码仓库为 github.com/qinyuanmao/dm-rails）
+```
+
+环境变量：
+
+```bash
+DM_RAILS_ENABLED=1          # 启用补丁（不设则 gem 完全无副作用）
+# DM_RAILS_VIEW=dm_rails_columns   # 辅助视图名，默认即此
+```
+
+`database.yml` 照常用 mysql2 适配器，host/port 指向代理（如 `127.0.0.1:3307`）。
+
+### 2. 达梦侧辅助视图
+
+用达梦客户端（disql 等）在业务 schema 下执行 [`sql/dm_rails_columns.sql`](sql/dm_rails_columns.sql)
+（或 `bin/rails dm_rails:view_sql` 输出后拷去执行）。**不要经代理执行**（视图 DDL 是达梦方言）。
+
+### 3. 代理侧
+
+1. 构建 SPI 适配包：`cd proxy/ss-dm-dialect && mvn package`
+2. 把 `ss-dm-dialect-1.0.0.jar` 与达梦 JDBC 驱动（`DmJdbcDriver18`）放入
+   ShardingSphere-Proxy 的 `ext-lib/`
+3. 逻辑库配置见 [`proxy/conf/database-example.yaml`](proxy/conf/database-example.yaml)，两个必踩点：
+   - URL 前缀用 `jdbc:dmwrap:`（包装驱动，修正 CLOB→LONGVARCHAR 类型码、列标签转小写、
+     `getObject` 的 Clob/Blob 对象转实际内容）
+   - 必须声明 `!SINGLE tables: ["*.*"]`，否则代理不做表发现
+
+## SPI 适配包做了什么
+
+| SPI | 作用 |
+|---|---|
+| `DatabaseType`（trunk=MySQL） | 让代理认识 `jdbc:dm:` / `jdbc:dmwrap:` |
+| `DialectMetaDataLoader` | 达梦无 information_schema，改查 `USER_TAB_COLUMNS`/`USER_CONSTRAINTS`，名称转小写 |
+| `ConnectionPropertiesParser` | 解析达梦 URL 的 `schema` 参数（否则元数据无目标库） |
+| `DialectDatabaseMetaData` | 反引号引用、NULL 排序对齐 MySQL |
+| `java.sql.Driver`（dmwrap） | 动态代理包装真实驱动，修结果集类型码/标签/LOB 取值 |
+
+## 从 MySQL 迁移数据的语义注意事项
+
+- 应用侧生成主键（雪花 ID 等）的表**不要**建成 IDENTITY 列（达梦禁止对 IDENTITY 显式赋值）
+- MySQL TIMESTAMP 的「插入 NULL 自动变当前时间」语义达梦没有，可用 BEFORE INSERT 触发器模拟：
+  `:NEW.created_at := NVL(:NEW.created_at, CURRENT_TIMESTAMP);`
+- 达梦索引名是 schema 级全局唯一（MySQL 是表级），迁移索引需加表名前缀
+- `LENGTH_IN_CHAR=0`（字节语义）时 VARCHAR 长度按 MySQL 版 ×4
+
+## 已知限制
+
+- `rails db:schema:dump` 产物不完整（索引/表选项返回空）——按「迁移先行、schema 只读」使用
+- 运行时 DDL（`create_table` 等）能否穿透取决于代理的 SQL 翻译，生产建议 DDL 走达梦客户端
+- 每语句经代理约有毫秒级额外开销，重 N+1 的代码路径建议用 `includes` 预加载
+
+## License
+
+MIT

data/lib/dm_rails/introspection.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module DmRails
+  # ActiveRecord（mysql2 适配器）自省补丁。
+  #
+  # 背景：mysql2 适配器的表结构自省依赖 SHOW FULL FIELDS / SHOW KEYS /
+  # SHOW CREATE TABLE / information_schema，这些经代理透传到达梦（MySQL 兼容模式）
+  # 均不支持。列信息改由达梦侧辅助视图（sql/dm_rails_columns.sql）提供，
+  # 表清单用代理可自答的 SHOW TABLES。
+  module Introspection
+    def column_definitions(table_name)
+      sql = "SELECT fld, ctype, is_null, key_kind, def_val, extra_str FROM #{DmRails.view_name} " \
+            "WHERE tbl = #{quote(table_name.to_s.downcase)} ORDER BY col_order"
+      execute(sql, "SCHEMA").to_a.map do |row|
+        vals = row.is_a?(Hash) ? row.values : row
+        { Field: vals[0], Type: vals[1], Collation: "", Null: vals[2],
+          Key: vals[3].to_s, Default: dm_rails_normalize_default(vals[4]), Extra: vals[5].to_s,
+          Privileges: "", Comment: "" }
+      end
+    end
+
+    def primary_keys(table_name)
+      sql = "SELECT fld FROM #{DmRails.view_name} WHERE tbl = #{quote(table_name.to_s.downcase)} " \
+            "AND key_kind = 'PRI' ORDER BY col_order"
+      execute(sql, "SCHEMA").to_a.map { |row| (row.is_a?(Hash) ? row.values : row)[0] }
+    end
+
+    def data_sources
+      execute("SHOW TABLES", "SCHEMA").to_a.map { |row| (row.is_a?(Hash) ? row.values : row)[0] }
+    end
+
+    def tables
+      data_sources
+    end
+
+    def views
+      []
+    end
+
+    def data_source_exists?(name)
+      data_sources.include?(name.to_s.downcase)
+    end
+
+    def table_exists?(name)
+      data_source_exists?(name)
+    end
+
+    def view_exists?(_name)
+      false
+    end
+
+    # 索引/表选项仅用于 schema dump 与迁移生成，运行时不依赖；达梦链路无对应查询通道
+    def indexes(_table_name)
+      []
+    end
+
+    def table_options(_table_name)
+      {}
+    end
+
+    def table_comment(_table_name)
+      nil
+    end
+
+    # 达梦链路无法执行 SHOW CREATE TABLE（AR 解析生成列/默认值类型的兜底路径）
+    def create_table_info(_table_name)
+      ""
+    end
+
+    def default_type(_table_name, _field_name)
+      nil
+    end
+
+    private
+
+    # 达梦 DATA_DEFAULT 是原样表达式：字符串默认值带引号、可能带空白；
+    # 转成 MySQL SHOW FULL FIELDS 风格
+    def dm_rails_normalize_default(raw)
+      return nil if raw.nil?
+
+      v = raw.to_s.strip
+      return nil if v.empty? || v.casecmp("NULL").zero?
+      return "CURRENT_TIMESTAMP" if v =~ /\ACURRENT_TIMESTAMP(\(\))?\z/i || v =~ /\ANOW\(\)\z/i
+
+      v = Regexp.last_match(1) if v =~ /\A'(.*)'\z/m
+      v
+    end
+  end
+end

data/lib/dm_rails/railtie.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module DmRails
+  class Railtie < ::Rails::Railtie
+    initializer "dm_rails.patch_mysql2_adapter" do
+      next unless DmRails.enabled?
+
+      ActiveSupport.on_load(:active_record) do
+        require "active_record/connection_adapters/mysql2_adapter"
+        require_relative "introspection"
+        ActiveRecord::ConnectionAdapters::Mysql2Adapter.prepend(DmRails::Introspection)
+      end
+    end
+
+    rake_tasks do
+      namespace :dm_rails do
+        desc "输出达梦侧辅助视图的建视图 SQL（请用达梦客户端在业务 schema 下执行）"
+        task :view_sql do
+          puts DmRails.view_sql
+        end
+      end
+    end
+  end
+end

data/lib/dm_rails/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module DmRails
+  VERSION = "0.1.0"
+end

data/lib/dm_rails.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require_relative "dm_rails/version"
+
+# dm-rails —— 让 Rails 经 MySQL 协议代理（ShardingSphere-Proxy）运行在达梦 DM8 上。
+#
+# 启用条件（满足其一）：
+#   ENV["DM_RAILS_ENABLED"] = "1"   （或兼容旧开关 ENV["DM_PROXY"] = "1"）
+#
+# 可配置项（环境变量）：
+#   DM_RAILS_VIEW —— 达梦侧列结构视图名，默认 dm_rails_columns（见 sql/dm_rails_columns.sql）
+module DmRails
+  class << self
+    def enabled?
+      ENV["DM_RAILS_ENABLED"] == "1" || ENV["DM_PROXY"] == "1"
+    end
+
+    def view_name
+      ENV.fetch("DM_RAILS_VIEW", "dm_rails_columns")
+    end
+
+    # 达梦侧辅助视图的建视图 SQL（用达梦客户端在业务 schema 下执行，勿经代理执行）
+    def view_sql
+      File.read(File.expand_path("../sql/dm_rails_columns.sql", __dir__))
+          .gsub("dm_rails_columns", view_name)
+    end
+  end
+end
+
+require_relative "dm_rails/railtie" if defined?(Rails::Railtie)

data/sql/dm_rails_columns.sql

@@ -0,0 +1,30 @@
+-- dm-rails 辅助视图：为 ActiveRecord 提供 MySQL 风格的列结构信息
+-- 在达梦业务 schema 下用达梦客户端执行（勿经代理执行）；视图名可通过 DM_RAILS_VIEW 环境变量对应调整
+CREATE OR REPLACE VIEW dm_rails_columns AS
+SELECT LOWER(c.TABLE_NAME) AS tbl,
+       LOWER(c.COLUMN_NAME) AS fld,
+       CASE
+         WHEN c.DATA_TYPE = 'BIGINT' THEN 'bigint(20)'
+         WHEN c.DATA_TYPE IN ('INT','INTEGER') THEN 'int(11)'
+         WHEN c.DATA_TYPE = 'SMALLINT' THEN 'smallint(6)'
+         WHEN c.DATA_TYPE = 'TINYINT' THEN 'tinyint(4)'
+         WHEN c.DATA_TYPE = 'BIT' THEN 'tinyint(1)'
+         WHEN c.DATA_TYPE LIKE 'VARCHAR%' THEN CONCAT('varchar(', CAST(c.DATA_LENGTH AS VARCHAR(10)), ')')
+         WHEN c.DATA_TYPE LIKE 'CHAR%' THEN CONCAT('char(', CAST(c.DATA_LENGTH AS VARCHAR(10)), ')')
+         WHEN c.DATA_TYPE IN ('TEXT','CLOB','LONGVARCHAR') THEN 'text'
+         WHEN c.DATA_TYPE IN ('DATETIME','TIMESTAMP') THEN 'datetime'
+         WHEN c.DATA_TYPE = 'DATE' THEN 'date'
+         WHEN c.DATA_TYPE = 'TIME' THEN 'time'
+         WHEN c.DATA_TYPE IN ('DEC','DECIMAL','NUMERIC','NUMBER') THEN CONCAT('decimal(', CAST(NVL(c.DATA_PRECISION,10) AS VARCHAR(10)), ',', CAST(NVL(c.DATA_SCALE,0) AS VARCHAR(10)), ')')
+         WHEN c.DATA_TYPE = 'DOUBLE' THEN 'double'
+         WHEN c.DATA_TYPE = 'FLOAT' THEN 'float'
+         WHEN c.DATA_TYPE IN ('BLOB','IMAGE','LONGVARBINARY','VARBINARY','BINARY') THEN 'blob'
+         ELSE 'varchar(255)'
+       END AS ctype,
+       CASE c.NULLABLE WHEN 'Y' THEN 'YES' ELSE 'NO' END AS is_null,
+       NVL((SELECT 'PRI' FROM USER_CONS_COLUMNS cu JOIN USER_CONSTRAINTS uc ON cu.CONSTRAINT_NAME = uc.CONSTRAINT_NAME
+            WHERE uc.CONSTRAINT_TYPE = 'P' AND cu.TABLE_NAME = c.TABLE_NAME AND cu.COLUMN_NAME = c.COLUMN_NAME AND ROWNUM <= 1), '') AS key_kind,
+       c.DATA_DEFAULT AS def_val,
+       CASE WHEN LOWER(c.COLUMN_NAME) = 'id' THEN 'auto_increment' ELSE '' END AS extra_str,
+       c.COLUMN_ID AS col_order
+FROM USER_TAB_COLUMNS c;

metadata

@@ -0,0 +1,83 @@
+--- !ruby/object:Gem::Specification
+name: dameng-rails
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- qinyuanmao
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-07-31 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.1'
+- !ruby/object:Gem::Dependency
+  name: mysql2
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.5'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.5'
+description: DM8 has no Ruby driver or ActiveRecord adapter. dm-rails keeps the stock
+  mysql2 adapter and routes it through ShardingSphere-Proxy to DM8, patching ActiveRecord
+  schema introspection (SHOW FULL FIELDS / information_schema) with a DM-side helper
+  view. Battle-tested on a production Rails 7.1 system.
+email:
+- wandering.garfield@outlook.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/dm_rails.rb
+- lib/dm_rails/introspection.rb
+- lib/dm_rails/railtie.rb
+- lib/dm_rails/version.rb
+- sql/dm_rails_columns.sql
+homepage: https://github.com/qinyuanmao/dm-rails
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/qinyuanmao/dm-rails
+  source_code_uri: https://github.com/qinyuanmao/dm-rails
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.7'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.19
+signing_key:
+specification_version: 4
+summary: Run Ruby on Rails on DM (Dameng / 达梦) database via a MySQL-protocol proxy
+test_files: []