db_meta 0.13.1 → 0.14.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8adeed469464ae77a3a9c1a4bf97232a5ac8dee25ec05099de171ffa198e97ef
-  data.tar.gz: f9c80bd97da0777df4435de3ac662683e4962c493c227d75a0a8874bf2be4bf0
+  metadata.gz: 2a8daf933344c242f2d8b50b218bddb5a4cf488a729316ad11c658af6c5cb782
+  data.tar.gz: b20f8d156bdfd1839d52781603a4abb83a099adfa415399acf53308cf887a566
 SHA512:
-  metadata.gz: 2c2216ce758aaa1788d34b02691c9fdbbe6406f23b4a261e4bebf0971def0b939878cea61d93852e78c3c81cf9291174ca171cb8455943f1c6c5d00385ed8b56
-  data.tar.gz: 1c45fc8c844195b9aa099fc008bd8f10ad7f6d8da1f22261b724d9aaa14c92bf6d118974b9d1ce8da80dcd0a7bcffe5ffd83056632cb46be2d85193deaae40e3
+  metadata.gz: cdddc2bfff37d407e381f9a642dd586c6ecf728f3db170f9db6e0ffc03d4c999633ee8c840d80fb4c2ced75910e399f8ea063825000c143bd4df87ea725eb863
+  data.tar.gz: 5ff480c88420a57634dc65bdd99dcf418a82bbd978457a42b8fd610c4c6d4896243f6b62fa312536b08efc4b21fc43ee4df90694b55c091a1d14c90d646e70d8

data/.github/workflows/01_test.yml

@@ -28,11 +28,11 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        ruby: [ '3.4', '3.3', '3.2']
+        ruby: [ '4.0', '3.4', '3.3']
 
     name: Ruby ${{ matrix.ruby }}
     steps:
-    - uses: actions/checkout@v5
+    - uses: actions/checkout@v6
 
     - name: Install Oracle instant client
       run: |

data/.github/workflows/02_release.yml

@@ -20,7 +20,7 @@ jobs:
 
     steps:
     - name: Checkout current code
-      uses: actions/checkout@v5
+      uses: actions/checkout@v6
 
     - name: Install Oracle instant client
       run: |
@@ -45,7 +45,7 @@ jobs:
     - name: Set up Ruby
       uses: ruby/setup-ruby@v1
       with:
-        ruby-version: '3.4'
+        ruby-version: '4.0'
         bundler: latest
         bundler-cache: true
         cache-version: 1

data/.ruby-version

@@ -1 +1 @@
-3.4.7
+4.0.3

data/.tool-versions

@@ -1 +1 @@
-ruby 3.4.7
+ruby 4.0.3

data/CHANGELOG.md

@@ -1,3 +1,23 @@
+## [0.14.0] - 2026-04-28
+
+### Changed
+- Reuse a single OCI8 logical connection per worker thread for the duration of the fetch instead of acquiring/logging off on every type fetch. Drastically reduces session attach/detach traffic against the connection pool, which avoids the per-attach overhead (and the 23c Instant Client byte-leak symptom) on long extracts.
+- Batch-load constraint metadata via two bulk queries against `USER_CONSTRAINTS` and `USER_CONS_COLUMNS` once before the parallel object fetch, and have `Constraint#fetch` read from an in-memory cache. Removes 2-3 round-trips per constraint.
+- Constraints with Oracle-generated `SYS_*` names are now emitted without an explicit `CONSTRAINT <name>` clause, so DDL diffs across instances aren't dominated by name churn. User-given names are preserved.
+- Redundant `SYS_*` NOT NULL CHECK constraints (whose condition is just `"COL" IS NOT NULL`) are filtered out — the column-level NOT NULL in the table DDL already covers them.
+- Fixed `View#fetch` to reuse the acquired connection (previously called `Connection.instance.get` twice, leaking a logical connection per view).
+- Fixed `View#extract` crash when a view has columns without comments (`column.comment.size` on nil).
+- Fixed `Table#fetch` ensure logic (was `rescue` instead of `ensure`).
+- Fixed `Column.all` typo (`loggoff` → cleanup no longer needed).
+
+### Added
+- README troubleshooting section for macOS / Apple Silicon: short tip covering both the 23c OID lookup hang and the `libclntsh` ↔ OpenLDAP symbol-clash, with the shared `tnsnames.ora` + `NAMES.DIRECTORY_PATH=(TNSNAMES, EZCONNECT)` fix and links to the relevant ruby-oci8 / Oracle docs.
+- Significantly expanded test coverage (49 → 125 examples; line coverage 58.94% → ~86%).
+- Added Ruby 4.0 to the supported/tested matrix.
+
+### Removed
+- Dropped Ruby 3.2 from the actively tested matrix (EOL 31 Mar 2026).
+
 ## [0.13.1] - 2025-11-09
 
 ### Added

data/README.md

@@ -2,12 +2,15 @@
 [![01 - Test](https://github.com/thomis/db_meta/actions/workflows/01_test.yml/badge.svg)](https://github.com/thomis/db_meta/actions/workflows/01_test.yml)
 [![02 - Release](https://github.com/thomis/db_meta/actions/workflows/02_release.yml/badge.svg)](https://github.com/thomis/db_meta/actions/workflows/02_release.yml)
 
-# Welcome to db_meta
-Database meta and core data extraction.
+# db_meta
 
-## Is it production ready?
+Extract Oracle schema metadata and core data as SQL DDL files.
 
-Well, I would not say, but I am using it already for my database development work where the gem covers my needs. Be careful and check details. Please create an issue when you think that someting is wrong or missing.
+`db_meta` connects to an Oracle schema and writes out DDL for every object (tables, views, indexes, constraints, packages, sequences, synonyms, grants, …), plus optional `INSERT` scripts for reference/lookup data. The output is a folder of `.sql` files organized by object type — suitable for checking into version control, diffing across environments, or seeding a fresh schema.
+
+## Status
+
+Used in day-to-day database development by the author. It covers the most common Oracle object types but is not exhaustive — exotic features (advanced storage clauses, partitioning details, etc.) may be missing or simplified. Spot-check the output before relying on it for a migration, and please open an issue if you hit something that's wrong or missing.
 
 ## Installation
 via Gemfile
@@ -30,6 +33,13 @@ meta.fetch
 meta.extract
 ```
 
+## Output conventions
+
+A few decisions worth knowing about, especially if you compare extracts across instances:
+
+- **Auto-generated `SYS_*` constraint names are stripped from the output.** Oracle invents names like `SYS_C0012345` for unnamed constraints, and those names differ between instances — making schema diffs noisy. Constraints with a `SYS_*` name are emitted without an explicit `CONSTRAINT <name>` clause; on import, Oracle just generates a fresh name. User-given constraint names are preserved as-is.
+- **Redundant `NOT NULL` CHECK constraints are omitted.** Oracle exposes column-level `NOT NULL` both as a column attribute and as a `SYS_*` CHECK constraint with a body of `"COL" IS NOT NULL`. The column-level form is already in the table DDL, so the duplicate CHECK is filtered out.
+
 ## Supported Databases
 - Oracle
 
@@ -49,12 +59,13 @@ meta.extract
 
 Currently supported and tested ruby versions are:
 
+- 4.0 (EOL 31 Mar 2029)
 - 3.4 (EOL 31 Mar 2028)
 - 3.3 (EOL 31 Mar 2027)
-- 3.2 (EOL 31 Mar 2026)
 
 Ruby versions not tested anymore:
 
+- 3.2 (EOL 31 Mar 2026)
 - 3.1 (EOL 31 Mar 2025)
 - 3.0 (EOL 31 Mar 2024)
 - 2.7 (EOL 31 Mar 2023)
@@ -63,6 +74,16 @@ Ruby versions not tested anymore:
 ## Planned Features
 - Storage and tablespace clause
 
+## Troubleshooting (macOS / Apple Silicon)
+
+If `OCI8.new` hangs for ~10s, prints "byte leak" gibberish, or crashes with `ldap_first_entry: Assertion …`, the issue is almost always that the Instant Client is trying to use LDAP/OID for database name resolution. The fix is the same in both cases: tell Oracle to use a local `tnsnames.ora` instead of LDAP. Create `~/opt/oracle/admin/tnsnames.ora` with your DB alias and `~/opt/oracle/admin/sqlnet.ora` containing `NAMES.DIRECTORY_PATH=(TNSNAMES, EZCONNECT)`, then `export TNS_ADMIN=$HOME/opt/oracle/admin`.
+
+For background and the `libclntsh` ↔ OpenLDAP symbol-clash variant (caused by Oracle's bundled LDAP client and Homebrew's OpenLDAP both loading into the same Ruby process), see:
+
+- [ruby-oci8 #32 — OCI8 hangs when switching to LDAP](https://github.com/kubo/ruby-oci8/issues/32)
+- [ruby-oci8 #41 — Assertion failure using LDAP](https://github.com/kubo/ruby-oci8/issues/41)
+- [Oracle Instant Client FAQ](https://www.oracle.com/database/technologies/instant-client/faqs.html)
+
 ## Publishing
 
 This project uses [Trusted Publishing](https://guides.rubygems.org/trusted-publishing/) to securely publish gems to RubyGems.org. Trusted Publishing eliminates the need for long-lived API tokens by using OpenID Connect (OIDC) to establish a trusted relationship between GitHub Actions and RubyGems.org.

data/db_meta.gemspec

@@ -18,7 +18,7 @@ Gem::Specification.new do |spec|
   spec.executables = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
 
-  spec.add_development_dependency "bundler", "~> 2.3"
+  spec.add_development_dependency "bundler", ">= 2.3"
   spec.add_development_dependency "rake", "~> 13.1"
   spec.add_development_dependency "rspec", "~> 3.13"
   spec.add_development_dependency "standard", "~> 1.34"

data/lib/db_meta/oracle/connection.rb

@@ -5,6 +5,8 @@ module DbMeta
     class Connection
       include Singleton
 
+      THREAD_KEY = :db_meta_oracle_connection
+
       attr_accessor :username, :password, :database_instance
       attr_reader :pool
       attr_reader :worker
@@ -23,11 +25,22 @@ module DbMeta
           Log.info("Connected to #{@username}@#{@database_instance}")
         end
 
-        # create and return logical connection. It creates physical connection as needed.
-        ::OCI8.new(@username, @password, @pool)
+        # one logical connection per thread - reused across all fetches in that thread
+        Thread.current[THREAD_KEY] ||= ::OCI8.new(@username, @password, @pool)
+      end
+
+      def release_thread_connection
+        connection = Thread.current[THREAD_KEY]
+        return unless connection
+        connection.logoff
+      rescue
+        # connection may already be closed
+      ensure
+        Thread.current[THREAD_KEY] = nil
       end
 
       def disconnect
+        release_thread_connection
         return unless @pool
         @pool.destroy
         Log.info("Logged off from #{@username}@#{@database_instance}")

data/lib/db_meta/oracle/objects.rb

@@ -26,6 +26,9 @@ module DbMeta
       end
 
       def fetch(args = {})
+        # bulk-load metadata that would otherwise drive N round-trips per object
+        Constraint.preload
+
         # fetch details in parallel
         # number of threads = physical connections / 2 to prevent application locking
         worker = (1..Connection.instance.worker / 2).map {
@@ -35,6 +38,8 @@ module DbMeta
               object.fetch
             end
           rescue ThreadError
+          ensure
+            Connection.instance.release_thread_connection
           end
         }
         worker.map(&:join) # wait until all are done
@@ -215,8 +220,6 @@ module DbMeta
         Log.info("Objects: #{items.size}, Object Types: #{types.uniq.size}")
 
         objects
-      ensure
-        connection&.logoff # closes logical connection
       end
     end
   end

data/lib/db_meta/oracle/types/column.rb

@@ -36,8 +36,6 @@ module DbMeta
         cursor.close
 
         columns
-      rescue
-        connection.loggoff
       end
 
       private

data/lib/db_meta/oracle/types/comment.rb

@@ -9,8 +9,6 @@ module DbMeta
         while (row = cursor.fetch)
           @text = row[0]
         end
-      ensure
-        connection.logoff
       end
     end
   end

data/lib/db_meta/oracle/types/constraint.rb

@@ -5,6 +5,72 @@ module DbMeta
 
       attr_reader :constraint_type, :table_name, :search_condition, :referential_constraint, :delete_rule, :columns
 
+      @@cache = {}
+      @@cache_mutex = Mutex.new
+
+      def self.preload(args = {})
+        connection_class = args[:connection_class] || Connection
+        connection = connection_class.instance.get
+
+        meta = {}
+        cursor = connection.exec(
+          "select constraint_name, constraint_type, table_name, search_condition, r_constraint_name, delete_rule " \
+          "from user_constraints"
+        )
+        cursor.fetch_hash do |row|
+          name = row["CONSTRAINT_NAME"]
+          type = translate_constraint_type(row["CONSTRAINT_TYPE"])
+          search_condition = row["SEARCH_CONDITION"]
+
+          # Skip Oracle-generated NOT NULL CHECK constraints. They are already
+          # represented by the column's NOT NULL clause in the table DDL, so
+          # emitting them again is redundant noise that breaks schema diffs.
+          next if redundant_not_null?(name, type, search_condition)
+
+          meta[name] = {
+            constraint_type: type,
+            table_name: row["TABLE_NAME"],
+            search_condition: search_condition,
+            r_constraint_name: row["R_CONSTRAINT_NAME"],
+            delete_rule: row["DELETE_RULE"],
+            columns: []
+          }
+        end
+        cursor.close
+
+        cursor = connection.exec(
+          "select constraint_name, column_name, position " \
+          "from user_cons_columns order by constraint_name, position"
+        )
+        cursor.fetch_hash do |row|
+          entry = meta[row["CONSTRAINT_NAME"]]
+          next unless entry
+          entry[:columns] << row["COLUMN_NAME"]
+        end
+        cursor.close
+
+        @@cache_mutex.synchronize { @@cache = meta }
+      end
+
+      def self.system_generated?(name)
+        name.to_s.start_with?("SYS_")
+      end
+
+      def self.redundant_not_null?(name, type, search_condition)
+        return false unless system_generated?(name) && type == "CHECK"
+        return false if search_condition.nil?
+        # Match patterns like: "COL_NAME" IS NOT NULL  or  COL_NAME IS NOT NULL
+        !!search_condition.match?(/\A\s*"?[A-Z0-9_$#]+"?\s+IS\s+NOT\s+NULL\s*\z/i)
+      end
+
+      def self.cache
+        @@cache
+      end
+
+      def self.reset_cache
+        @@cache_mutex.synchronize { @@cache = {} }
+      end
+
       def initialize(args = {})
         super
 
@@ -13,37 +79,29 @@ module DbMeta
       end
 
       def fetch(args = {})
-        connection = Connection.instance.get
-        cursor = connection.exec("select * from user_constraints where constraint_name = '#{@name}'")
-        cursor.fetch_hash do |item|
-          @constraint_type = translate_constraint_type(item["CONSTRAINT_TYPE"])
-          @extract_type = :merged if @constraint_type == "FOREIGN KEY"
-          @table_name = item["TABLE_NAME"]
-          @search_condition = item["SEARCH_CONDITION"]
-          @delete_rule = item["DELETE_RULE"]
-
-          if @constraint_type == "FOREIGN KEY"
-            constraint = Constraint.new("OBJECT_TYPE" => "CONSTRAINT", "OBJECT_NAME" => item["R_CONSTRAINT_NAME"])
-            constraint.fetch
-            @referential_constraint = constraint
-          end
-        end
-        cursor.close
+        entry = @@cache[@name]
+        return unless entry
 
-        # get affected columns
-        cursor = connection.exec("select * from user_cons_columns where constraint_name = '#{@name}' order by position")
-        cursor.fetch_hash do |item|
-          @columns << item["COLUMN_NAME"]
+        @constraint_type = entry[:constraint_type]
+        @table_name = entry[:table_name]
+        @search_condition = entry[:search_condition]
+        @delete_rule = entry[:delete_rule]
+        @columns = entry[:columns].dup
+        @extract_type = :merged if @constraint_type == "FOREIGN KEY"
+
+        if @constraint_type == "FOREIGN KEY" && entry[:r_constraint_name]
+          @referential_constraint = Constraint.new(
+            "OBJECT_TYPE" => "CONSTRAINT",
+            "OBJECT_NAME" => entry[:r_constraint_name]
+          )
+          @referential_constraint.fetch
         end
-        cursor.close
-      ensure
-        connection.logoff
       end
 
       def extract(args = {})
         buffer = []
         buffer << "ALTER TABLE #{@table_name} ADD ("
-        buffer << "  CONSTRAINT #{@name}"
+        buffer << "  CONSTRAINT #{@name}" unless Constraint.system_generated?(@name)
 
         case @constraint_type
         when "CHECK"
@@ -69,9 +127,7 @@ module DbMeta
         ["PRIMARY KEY", "FOREIGN KEY", "UNIQUE", "CHECK"].index(type)
       end
 
-      private
-
-      def translate_constraint_type(type)
+      def self.translate_constraint_type(type)
         case type
         when "P"
           "PRIMARY KEY"

data/lib/db_meta/oracle/types/database_link.rb

@@ -15,8 +15,6 @@ module DbMeta
           @host = row[2].to_s
         end
         cursor.close
-      ensure
-        connection.logoff
       end
 
       def extract(args = {})

data/lib/db_meta/oracle/types/function.rb

@@ -14,8 +14,6 @@ module DbMeta
           @source << row[0].to_s
         end
         cursor.close
-      ensure
-        connection.logoff
       end
 
       def extract(args = {})

data/lib/db_meta/oracle/types/index.rb

@@ -38,8 +38,6 @@ module DbMeta
           @columns[idx] = row[0] # replace sys_... entry
         end
         cursor.close
-      ensure
-        connection.logoff
       end
 
       def extract(args = {})

data/lib/db_meta/oracle/types/materialized_view.rb

@@ -33,8 +33,6 @@ module DbMeta
           @comment = item["COMMENTS"]
         end
         cursor.close
-      ensure
-        connection.logoff
       end
 
       def extract(args = {})

data/lib/db_meta/oracle/types/package.rb

@@ -6,22 +6,21 @@ module DbMeta
       attr_reader :header, :body
 
       def fetch
+        connection = Connection.instance.get
+
         @header = ""
-        cursor = Connection.instance.get.exec("select text from user_source where type = 'PACKAGE' and name = '#{@name}' order by line")
+        cursor = connection.exec("select text from user_source where type = 'PACKAGE' and name = '#{@name}' order by line")
         while (row = cursor.fetch)
           @header << row[0].to_s
         end
         cursor.close
 
         @body = ""
-        connection = Connection.instance.get
         cursor = connection.exec("select text from user_source where type = 'PACKAGE BODY' and name = '#{@name}' order by line")
         while (row = cursor.fetch)
           @body << row[0].to_s
         end
         cursor.close
-      ensure
-        connection.logoff
       end
 
       def extract(args = {})

data/lib/db_meta/oracle/types/procedure.rb

@@ -14,8 +14,6 @@ module DbMeta
           @source << row[0].to_s
         end
         cursor.close
-      ensure
-        connection.logoff
       end
 
       def extract(args = {})

data/lib/db_meta/oracle/types/queue.rb

@@ -23,8 +23,6 @@ module DbMeta
           @compatible = row["COMPATIBLE"]
         end
         cursor.close
-      ensure
-        connection.logoff
       end
 
       def extract(args = {})

data/lib/db_meta/oracle/types/sequence.rb

@@ -19,8 +19,6 @@ module DbMeta
           @last_number = row[6].to_i
         end
         cursor.close
-      ensure
-        connection.logoff
       end
 
       def extract(args = {})

data/lib/db_meta/oracle/types/synonym.rb

@@ -21,8 +21,6 @@ module DbMeta
           @db_link = row[2].to_s
         end
         cursor.close
-      ensure
-        connection.logoff
       end
 
       def extract(args = {})

data/lib/db_meta/oracle/types/table.rb

@@ -36,8 +36,6 @@ module DbMeta
           @duration = row[3].to_s
         end
         cursor.close
-      rescue
-        connection.logoff
       end
 
       def extract(args = {})
@@ -54,7 +52,7 @@ module DbMeta
         if @iot_type == "IOT"
           constraint = @constraints.find { |c| c.constraint_type == "PRIMARY KEY" }
           buffer[-1] += ","
-          buffer << "  CONSTRAINT #{constraint.name}"
+          buffer << "  CONSTRAINT #{constraint.name}" unless Constraint.system_generated?(constraint.name)
           buffer << "  PRIMARY KEY (#{constraint.columns.join(", ")})"
           buffer << "  ENABLE VALIDATE"
         end

data/lib/db_meta/oracle/types/table_data_collection.rb

@@ -44,8 +44,6 @@ module DbMeta
         buffer << nil
 
         buffer.join("\n")
-      ensure
-        connection.logoff
       end
 
       def ddl_drop

data/lib/db_meta/oracle/types/trigger.rb

@@ -27,8 +27,6 @@ module DbMeta
         parse_trigger_type
 
         cursor.close
-      ensure
-        connection.logoff
       end
 
       def extract(args = {})

data/lib/db_meta/oracle/types/type.rb

@@ -19,8 +19,6 @@ module DbMeta
           @body << row[0].to_s
         end
         cursor.close
-      ensure
-        connection.logoff
       end
 
       def extract(args = {})

data/lib/db_meta/oracle/types/view.rb

@@ -15,13 +15,11 @@ module DbMeta
 
         @source = ""
         connection = Connection.instance.get
-        cursor = Connection.instance.get.exec("select text from user_views where view_name = '#{@name}'")
+        cursor = connection.exec("select text from user_views where view_name = '#{@name}'")
         while (row = cursor.fetch)
           @source << row[0].to_s
         end
         cursor.close
-      ensure
-        connection.logoff
       end
 
       def extract(args = {})
@@ -47,7 +45,7 @@ module DbMeta
 
         # view column comments
         @columns.each do |column|
-          next if column.comment.size == 0
+          next if column.comment.nil? || column.comment.size == 0
           buffer << "COMMENT ON COLUMN #{@name}.#{column.name} IS '#{column.comment.gsub("'", "''")}';"
         end
 

data/lib/db_meta/version.rb

@@ -1,3 +1,3 @@
 module DbMeta
-  VERSION = "0.13.1"
+  VERSION = "0.14.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: db_meta
 version: !ruby/object:Gem::Version
-  version: 0.13.1
+  version: 0.14.0
 platform: ruby
 authors:
 - Thomi
@@ -13,14 +13,14 @@ dependencies:
   name: bundler
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '2.3'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '2.3'
 - !ruby/object:Gem::Dependency
@@ -185,7 +185,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 4.0.6
 specification_version: 4
 summary: Database meta and core data extraction
 test_files: []