activerecord-duckdb 0.1.0

data/lib/active_record/connection_adapters/duckdb/database_statements.rb

@@ -0,0 +1,303 @@
+# frozen_string_literal: true
+
+# This module provides database statements for the DuckDB adapter.
+module ActiveRecord
+  module ConnectionAdapters
+    module Duckdb
+      module DatabaseStatements
+        # Determines if a SQL query is a write operation
+        # @param _sql [String] The SQL query to check (unused in DuckDB implementation)
+        # @return [Boolean] always returns false for DuckDB
+        def write_query?(_sql)
+          false
+        end
+
+        # Executes a SQL statement against the DuckDB database
+        # @param sql [String] The SQL statement to execute
+        # @param name [String, nil] Optional name for logging purposes
+        # @return [DuckDB::Result] The result of the query execution
+        def execute(sql, name = nil) # :nodoc:
+          # In case a query is being executed before the connection is open, reconnect.
+          reconnect unless raw_connection
+
+          log(sql, name) do
+            ActiveSupport::Dependencies.interlock.permit_concurrent_loads do
+              raw_connection.query(sql)
+            end
+          end
+        end
+
+        # Performs a query with optional bind parameters
+        # @param raw_connection [DuckDB::Connection] The raw database connection
+        # @param sql [String] The SQL query to execute
+        # @param binds [Array] Array of bind parameters
+        # @param type_casted_binds [Array] Type-casted bind parameters
+        # @param prepare [Boolean] Whether to prepare the statement (unused)
+        # @param notification_payload [Hash, nil] Payload for notifications (unused)
+        # @param batch [Boolean] Whether this is a batch operation (unused)
+        # @param async [Boolean] Whether to execute asynchronously (unused)
+        # @param kwargs [Hash] Additional keyword arguments
+        # @return [DuckDB::Result] The query result
+        def perform_query(raw_connection,
+                          sql,
+                          binds,
+                          type_casted_binds,
+                          prepare: false,
+                          notification_payload: nil,
+                          batch: false,
+                          async: false,
+                          **kwargs)
+          result = if binds.any?
+                     # Use the modern parameter binding approach
+                     exec_query_with_binds(sql, binds)
+                   else
+                     # Fallback to direct execution with quoted values
+                     # Your existing quote method will handle any unquoted values
+                     raw_connection.query(sql)
+                   end
+          result
+        end
+
+        # Casts a DuckDB result to ActiveRecord::Result format
+        # @param result [DuckDB::Result, nil] The DuckDB result to cast
+        # @return [ActiveRecord::Result] The ActiveRecord-compatible result
+        def cast_result(result)
+          return ActiveRecord::Result.empty(affected_rows: @affected_rows_before_warnings) if result.nil?
+
+          columns = result.columns.map do |col|
+            if col.respond_to?(:name)
+              col.name
+            elsif col.respond_to?(:column_name)
+              col.column_name
+            else
+              col.to_s
+            end
+          end
+
+          ActiveRecord::Result.new(columns, result.to_a)
+        end
+
+        # Executes a query and returns an ActiveRecord::Result
+        # @param sql [String] The SQL query to execute
+        # @param name [String, nil] Optional name for logging
+        # @param binds [Array] Array of bind parameters
+        # @param prepare [Boolean] Whether to prepare the statement (unused)
+        # @return [ActiveRecord::Result] The query result
+        def exec_query(sql, name = nil, binds = [], prepare: false)
+          reconnect unless raw_connection
+
+          log(sql, name, binds) do
+            result = if binds.any?
+                       # Use the modern parameter binding approach
+                       exec_query_with_binds(sql, binds)
+                     else
+                       # Fallback to direct execution with quoted values
+                       # Your existing quote method will handle any unquoted values
+                       raw_connection.query(sql)
+                     end
+
+            build_result(result)
+          end
+        end
+
+        # Executes a DELETE statement and returns the number of affected rows
+        # @param sql [String] The DELETE SQL statement
+        # @param name [String, nil] Optional name for logging
+        # @param binds [Array] Array of bind parameters
+        # @return [Integer] Number of rows affected by the delete
+        def exec_delete(sql, name = nil, binds = []) # :nodoc:
+          reconnect unless raw_connection
+
+          if binds.any?
+            # For bound queries, handle them with proper logging
+            log(sql, name, binds) do
+              bind_values = binds.map(&:value_for_database)
+              raw_connection.query(sql, *bind_values)
+            end.rows_changed
+          else
+            # For non-bound queries, use execute directly
+            result = execute(sql, name)
+            result.rows_changed
+          end
+        end
+        alias exec_update exec_delete
+
+        # Executes an INSERT statement with optional RETURNING clause
+        # @param sql [String] The INSERT SQL statement
+        # @param name [String, nil] Optional name for logging
+        # @param binds [Array] Array of bind parameters
+        # @param pk [String, nil] Primary key column name
+        # @param sequence_name [String, nil] Sequence name (unused)
+        # @param returning [Array, nil] Columns to return after insert
+        # @return [ActiveRecord::Result] The insert result with returned values
+        def exec_insert(sql, name = nil, binds = [], pk = nil, sequence_name = nil, returning: nil)
+          # Rails 8 will pass returning: [pk] when it wants the ID back
+          if returning&.any?
+            returning_columns = returning.map { |c| quote_column_name(c) }.join(', ')
+            sql = "#{sql} RETURNING #{returning_columns}" unless sql.include?('RETURNING')
+          elsif pk && !sql.include?('RETURNING')
+            # Add RETURNING for the primary key
+            sql = "#{sql} RETURNING #{quote_column_name(pk)}"
+          end
+
+          # Execute the query and return the result
+          # Rails 8 will handle extracting the ID from the result
+          exec_query(sql, name, binds)
+        end
+
+        # Returns columns that should be included in INSERT statements
+        # @param table_name [String] The name of the table
+        # @return [Array<ActiveRecord::ConnectionAdapters::Column>] Columns to include in INSERT
+        def columns_for_insert(table_name)
+          columns(table_name).reject do |column|
+            # Exclude columns that have a default function (like nextval)
+            column.default_function.present?
+          end
+        end
+
+        # Determines if a column value should be returned after insert
+        # This is crucial - it tells Rails which columns should use RETURNING
+        # @param column [ActiveRecord::ConnectionAdapters::Column] The column to check
+        # @return [Boolean] true if column value should be returned after insert
+        def return_value_after_insert?(column)
+          # Return true for any column with a sequence default
+          column.default_function&.include?('nextval') || super
+        end
+
+        # Extracts the last inserted ID from an insert result
+        # @param result [ActiveRecord::Result] The result from an insert operation
+        # @return [Object] The last inserted ID value
+        def last_inserted_id(result)
+          # Handle ActiveRecord::Result from RETURNING clause
+          if result.is_a?(ActiveRecord::Result) && result.rows.any?
+            id_value = result.rows.first.first
+            return id_value
+          end
+          super
+        end
+
+        # Builds an ActiveRecord::Result from a DuckDB result
+        # @param result [DuckDB::Result, nil] The DuckDB result to convert
+        # @return [ActiveRecord::Result] The converted ActiveRecord result
+        def build_result(result)
+          # Handle DuckDB result format
+          return ActiveRecord::Result.empty if result.nil?
+
+          # DuckDB results have .columns and .to_a, not .rows
+          columns = result.columns.map do |col|
+            if col.respond_to?(:name)
+              col.name
+            elsif col.respond_to?(:column_name)
+              col.column_name
+            else
+              col.to_s
+            end
+          end
+
+          rows = result.to_a
+          ActiveRecord::Result.new(columns, rows)
+        end
+
+        # Fetches type metadata for a SQL type string
+        # @param sql_type [String] The SQL type to get metadata for
+        # @return [ActiveRecord::ConnectionAdapters::SqlTypeMetadata] The type metadata
+        def fetch_type_metadata(sql_type)
+          # Parse DuckDB types and map to Rails types
+          type, limit, precision, scale = parse_type_info(sql_type)
+
+          ActiveRecord::ConnectionAdapters::SqlTypeMetadata.new(
+            sql_type: sql_type,
+            type: type.to_sym,
+            limit: limit,
+            precision: precision,
+            scale: scale
+          )
+        end
+
+        private
+
+        # Executes a query with bind parameters using positional parameters
+        # @param sql [String] The SQL query with bind placeholders
+        # @param binds [Array] Array of bind parameters
+        # @return [DuckDB::Result] The query result
+        def exec_query_with_binds(sql, binds)
+          # For DuckDB, use positional parameters instead of named parameters
+          bind_values = binds.map do |bind|
+            if bind.respond_to?(:value_for_database)
+              bind.value_for_database
+            elsif bind.is_a?(Symbol)
+              bind.to_s
+            else
+              bind
+            end
+          end
+          raw_connection.query(sql, *bind_values)
+        end
+
+        # Parses SQL type information to extract Rails type, limit, precision, and scale
+        # @param sql_type [String] The SQL type string to parse
+        # @return [Array] Array containing [type, limit, precision, scale]
+        def parse_type_info(sql_type)
+          case sql_type.to_s.upcase
+          when /^INTEGER(\((\d+),(\d+)\))?/i
+            precision, scale = ::Regexp.last_match(2)&.to_i, ::Regexp.last_match(3)&.to_i
+            [:integer, nil, precision, scale]
+          when /^VARCHAR(\((\d+)\))?/i, /^TEXT/i
+            limit = ::Regexp.last_match(2)&.to_i
+            [:string, limit, nil, nil]
+          when /^DOUBLE/i, /^REAL/i
+            [:float, nil, nil, nil]
+          when /^BOOLEAN/i
+            [:boolean, nil, nil, nil]
+          when /^DATE$/i
+            [:date, nil, nil, nil]
+          when /^TIMESTAMP/i, /^DATETIME/i
+            [:datetime, nil, nil, nil]
+          when /^DECIMAL(\((\d+),(\d+)\))?/i, /^NUMERIC(\((\d+),(\d+)\))?/i
+            precision, scale = ::Regexp.last_match(2)&.to_i, ::Regexp.last_match(3)&.to_i
+            [:decimal, nil, precision, scale]
+          else
+            [:string, nil, nil, nil] # Default fallback
+          end
+        end
+
+        # Extracts and converts default values from DuckDB column defaults
+        # @param default [String, nil] The default value from column definition
+        # @return [Object, nil] The converted default value
+        def extract_value_from_default(default)
+          return nil if default.nil?
+
+          # IMPORTANT: Return nil for sequence defaults so Rails doesn't set id=0
+          return nil if default.to_s.include?('nextval(')
+
+          # Handle DuckDB default value formats
+          case default.to_s
+          when /^'(.*)'$/
+            ::Regexp.last_match(1) # Remove quotes from string defaults
+          when 'NULL'
+            nil
+          when /^\d+$/
+            default.to_i # Integer defaults
+          when /^\d+\.\d+$/
+            default.to_f # Float defaults
+          else
+            default
+          end
+        end
+
+        # Substitutes bind parameters in SQL with quoted values
+        # @param sql [String] The SQL string with bind placeholders
+        # @param binds [Array] Array of bind parameters
+        # @return [String] SQL with substituted values
+        def substitute_binds(sql, binds)
+          bind_index = 0
+          sql.gsub('?') do
+            value = quote(binds[bind_index].value)
+            bind_index += 1
+            value
+          end
+        end
+      end
+    end
+  end
+end

data/lib/active_record/connection_adapters/duckdb/database_tasks.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module ActiveRecord
+  module ConnectionAdapters
+    module Duckdb
+      # DuckDB-specific database tasks for database lifecycle management
+      # Provides stub implementations for database creation and destruction operations
+      module DatabaseTasks
+        # Creates a DuckDB database (stub implementation)
+        # @param database [String] The database name or path
+        # @param options [Hash] Additional options for database creation (unused)
+        # @return [void]
+        def create_database(database, options = {}); end
+
+        # Drops a DuckDB database (stub implementation)
+        # @param database [String] The database name or path
+        # @return [void]
+        def drop_database(database); end
+      end
+    end
+  end
+end

data/lib/active_record/connection_adapters/duckdb/quoting.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module ActiveRecord
+  module ConnectionAdapters
+    module Duckdb
+      module Quoting
+        extend ActiveSupport::Concern
+
+        module ClassMethods
+          # Quotes a column name for use in SQL statements
+          # @param name [String, Symbol] The column name to quote
+          # @return [String] The quoted column name wrapped in double quotes
+          def quote_column_name(name)
+            %("#{name}")
+          end
+        end
+
+        # Quotes a table name for use in SQL statements
+        # @param name [String, Symbol] The table name to quote
+        # @return [String] The quoted table name (delegates to quote_column_name)
+
+        def quote_table_name(name)
+          quote_column_name(name)
+        end
+
+        # Quotes a column name for use in SQL statements
+        # @param name [String, Symbol] The column name to quote
+        # @return [String] The quoted column name wrapped in double quotes
+        def quote_column_name(name)
+          %("#{name}")
+        end
+
+        # Quotes a value for safe inclusion in SQL statements
+        # @param value [Object] The value to quote
+        # @return [String] The appropriately quoted value for SQL
+        def quote(value)
+          case value
+          when String
+            "'#{value.gsub("'", "''")}'"
+          when nil
+            'NULL'
+          when true
+            'TRUE'
+          when false
+            'FALSE'
+          when Numeric
+            value.to_s
+          when Time, DateTime
+            "'#{value.utc.strftime("%Y-%m-%d %H:%M:%S")}'"
+          when Date
+            "'#{value.strftime("%Y-%m-%d")}'"
+          else
+            "'#{value.to_s.gsub("'", "''")}'"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/active_record/connection_adapters/duckdb/schema_creation.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module ActiveRecord
+  module ConnectionAdapters
+    module Duckdb
+      # DuckDB-specific schema creation functionality
+      # Extends Rails' SchemaCreation to handle DuckDB-specific SQL generation
+      class SchemaCreation < SchemaCreation
+        private
+
+        # Indicates whether DuckDB supports USING clause in index creation
+        # No USING clause is supported - DuckDB automatically determines the appropriate index type.
+        # https://duckdb.org/docs/stable/sql/statements/create_index.html
+        # https://duckdb.org/docs/stable/sql/indexes.html
+        # @return [Boolean] always returns false as DuckDB doesn't support USING clause
+        def supports_index_using?
+          false
+        end
+
+        # Adds column options to SQL, with special handling for DuckDB sequence defaults
+        # Override to handle nextval() defaults properly for DuckDB sequences
+        # @param sql [String] The SQL string being built
+        # @param options [Hash] Column options hash
+        # @return [void]
+        def add_column_options!(sql, options)
+          # Handle nextval() function calls - don't quote them
+          if options[:default]&.to_s&.include?('nextval(')
+            # Extract the sequence name and add it properly
+            default_value = options[:default].to_s
+            # Remove any extra quotes that might have been added
+            default_value = default_value.gsub(/^['"]|['"]$/, '')
+            sql << " DEFAULT #{default_value}"
+            # Create a copy of options without the default to prevent Rails from processing it again
+            options = options.except(:default)
+          end
+
+          # Let Rails handle all other column options normally
+          super
+        end
+      end
+    end
+  end
+end

data/lib/active_record/connection_adapters/duckdb/schema_definitions.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+require 'active_record/connection_adapters/abstract/schema_definitions'
+
+module ActiveRecord
+  module ConnectionAdapters
+    module Duckdb
+      # DuckDB-specific column method definitions for table creation
+      # Provides both standard Rails column types and DuckDB-specific data types
+      module ColumnMethods
+        extend ActiveSupport::Concern
+        extend ConnectionAdapters::ColumnMethods::ClassMethods
+
+        define_column_methods(
+          # binary
+          :blob,
+          # Integer variants
+          :tinyint,           # TINYINT (1 byte: -128 to 127)
+          :smallint,          # SMALLINT (2 bytes: -32,768 to 32,767)
+          :hugeint,           # HUGEINT (16 bytes: very large integers)
+          :varint,            # VARINT (variable precision integer, up to 1.2M digits)
+          # Unsigned integer variants
+          :utinyint,          # UTINYINT (1 byte: 0 to 255)
+          :usmallint,         # USMALLINT (2 bytes: 0 to 65,535)
+          :uinteger,          # UINTEGER (4 bytes: 0 to 4,294,967,295)
+          :ubigint,           # UBIGINT (8 bytes: 0 to 18,446,744,073,709,551,615)
+          :uhugeint,          # UHUGEINT (16 bytes: 0 to 2^128-1)
+          # Special data types
+          :uuid,              # UUID type for unique identifiers
+          :interval,          # INTERVAL for time periods
+          :bit,               # BIT for bit strings
+          # Complex/nested types
+          :list,              # LIST (variable-length array)
+          :struct,            # STRUCT (composite type with named fields)
+          :map,               # MAP (key-value pairs)
+          :union,             # UNION (value can be one of several types)
+          :enum # ENUM (predefined set of values)
+          # JSON can't be a column type, but can be a queried type of data
+          # :json # JSON documents (check DuckDB version compatibility)
+        )
+
+        alias binary blob
+
+        # Creates a LIST column with specified element type
+        # @param name [String, Symbol] The column name
+        # @param element_type [Symbol] The type of elements in the list (default: :string)
+        # @return [void]
+        # @example Create a list of strings
+        #   t.list :tags, element_type: :string
+        def list(name, element_type: :string, **)
+          column(name, "#{element_type.to_s.upcase}[]", **)
+        end
+
+        # Creates a STRUCT column with named fields
+        # @param name [String, Symbol] The column name
+        # @param fields [Hash] Hash mapping field names to their types (default: {})
+        # @return [void]
+        # @example Create an address struct
+        #   t.struct :address, fields: { street: :string, city: :string, zip: :integer }
+        def struct(name, fields: {}, **)
+          field_definitions = fields.map { |field_name, field_type| "#{field_name} #{field_type.to_s.upcase}" }
+          column(name, "STRUCT(#{field_definitions.join(", ")})", **)
+        end
+
+        # Creates a MAP column with specified key and value types
+        # @param name [String, Symbol] The column name
+        # @param key_type [Symbol] The type of map keys (default: :string)
+        # @param value_type [Symbol] The type of map values (default: :string)
+        # @return [void]
+        # @example Create a string-to-string map
+        #   t.map :metadata, key_type: :string, value_type: :string
+        def map(name, key_type: :string, value_type: :string, **)
+          column(name, "MAP(#{key_type.to_s.upcase}, #{value_type.to_s.upcase})", **)
+        end
+
+        # Creates an ENUM column with predefined values
+        # @param name [String, Symbol] The column name
+        # @param values [Array] Array of allowed enum values (default: [])
+        # @return [void]
+        # @example Create a status enum
+        #   t.enum :status, values: ['active', 'inactive', 'pending']
+        def enum(name, values: [], **)
+          enum_values = values.map { |v| "'#{v}'" }.join(', ')
+          column(name, "ENUM(#{enum_values})", **)
+        end
+      end
+
+      # DuckDB-specific table definition for CREATE TABLE statements
+      # Extends Rails' TableDefinition with DuckDB column types and features
+      class TableDefinition < ActiveRecord::ConnectionAdapters::TableDefinition
+        include Duckdb::ColumnMethods
+
+        # Initialize a new DuckDB table definition
+        # @param conn [ActiveRecord::ConnectionAdapters::DuckdbAdapter] The database adapter
+        # @param name [String, Symbol] The table name
+        # @param temporary [Boolean] Whether this is a temporary table
+        # @param if_not_exists [Boolean] Whether to use IF NOT EXISTS clause
+        # @param options [Hash, nil] Additional table options
+        # @param as [String, nil] SELECT statement for CREATE TABLE AS
+        # @param comment [String, nil] Table comment
+        # @param table_options [Hash] Additional keyword table options
+        def initialize(conn, name, temporary: false, if_not_exists: false,
+                       options: nil, as: nil, comment: nil, **table_options)
+          super
+          @conn = conn
+          @table_name = name
+        end
+
+        # Creates a column definition for the table
+        # Note: sequence defaults are handled by ALTER TABLE after table creation
+        # @param name [String, Symbol] The column name
+        # @param type [Symbol] The column type
+        # @param index [Boolean, Hash, nil] Whether to create an index on this column
+        # @param options [Hash] Additional column options
+        # @return [void]
+        def column(name, type, index: nil, **options)
+          # Don't set sequence defaults here - they're handled in create_table via ALTER TABLE
+          super
+        end
+
+        # Creates a primary key column definition
+        # Note: sequence defaults are handled by ALTER TABLE after table creation
+        # @param name [String, Symbol] The primary key column name
+        # @param type [Symbol] The primary key column type (default: :primary_key)
+        # @param options [Hash] Additional column options
+        # @return [void]
+        def primary_key(name, type = :primary_key, **options)
+          # Don't set sequence defaults here - they're handled in create_table via ALTER TABLE
+          super
+        end
+      end
+
+      # DuckDB-specific table modification for ALTER TABLE statements
+      # Extends Rails' Table with DuckDB column types and features
+      class Table < ActiveRecord::ConnectionAdapters::Table
+        include Duckdb::ColumnMethods
+      end
+
+      # DuckDB-specific table alteration functionality
+      # Extends Rails' AlterTable for DuckDB-specific schema changes
+      class AlterTable < ActiveRecord::ConnectionAdapters::AlterTable
+      end
+    end
+  end
+end