activerecord-duckdb 0.1.0

data/docs/TABLE_DEFINITION.md

@@ -0,0 +1,322 @@
+# DuckDB TableDefinition Guide
+
+This guide covers the `TableDefinition` class for the ActiveRecord DuckDB adapter, which provides full Rails compatibility plus support for DuckDB-specific data types.
+
+## Overview
+
+The DuckDB adapter's `TableDefinition` follows standard Rails conventions while adding:
+
+- **Rails Compatibility**: All standard Rails table creation patterns work seamlessly
+- **Flexible Primary Keys**: Support for integer, bigint, UUID, and string primary keys using Rails conventions
+- **DuckDB Data Types**: Support for DuckDB-specific types like `HUGEINT`, `UUID`, `LIST`, `STRUCT`, etc.
+- **Automatic Sequences**: Behind-the-scenes sequence management for integer primary keys
+  </text>
+
+<old_text>
+
+### Integer Primary Keys (with Sequences)
+
+```ruby
+# Standard Rails table - automatically creates bigint id with sequence
+create_table :users do |t|
+  t.string :name
+  t.timestamps
+end
+# DuckDB adapter automatically creates users_id_seq sequence
+
+# Explicit integer primary key (Rails 4 style)
+create_table :posts, id: :integer do |t|
+  t.string :title
+  t.timestamps
+end
+# Creates posts_id_seq sequence with integer type
+
+# Explicit bigint primary key (Rails 5+ default)
+create_table :articles, id: :bigint do |t|
+  t.string :title
+  t.timestamps
+end
+# Creates articles_id_seq sequence
+```
+
+## Primary Key Support
+
+### Integer Primary Keys (with Sequences)
+
+```ruby
+# Standard Rails table - automatically creates bigint id with sequence
+create_table :users do |t|
+  t.string :name
+  t.timestamps
+end
+# DuckDB adapter automatically creates users_id_seq sequence
+
+# Explicit integer primary key (Rails 4 style)
+create_table :posts, id: :integer do |t|
+  t.string :title
+  t.timestamps
+end
+# Creates posts_id_seq sequence with integer type
+
+# Explicit bigint primary key (Rails 5+ default)
+create_table :articles, id: :bigint do |t|
+  t.string :title
+  t.timestamps
+end
+# Creates articles_id_seq sequence
+```
+
+### UUID Primary Keys (no sequences needed)
+
+```ruby
+# Rails convention for UUID primary keys
+create_table :sessions, id: :uuid do |t|
+  t.string :session_token
+  t.timestamps
+end
+# No sequence created - UUIDs are generated by the application
+
+# UUID with custom primary key name
+create_table :articles, primary_key: :article_uuid, id: :uuid do |t|
+  t.string :title
+  t.timestamps
+end
+```
+
+### String Primary Keys
+
+```ruby
+# Rails convention for string primary keys
+create_table :categories, id: :string do |t|
+  t.string :name
+end
+# No sequence created - string IDs managed by application
+
+# Custom string primary key name
+create_table :countries, primary_key: :iso_code, id: :string do |t|
+  t.string :name
+end
+```
+
+## Sequence Management
+
+### Advanced Sequence Management
+
+If you need custom sequence behavior, you can use the sequence methods directly:
+
+```ruby
+# Create a custom sequence
+connection.create_sequence('custom_seq', start_with: 1000, increment_by: 10)
+
+# Use in a table (manual approach)
+create_table :invoices do |t|
+  t.bigint :invoice_number, default: -> { "nextval('custom_seq')" }
+  t.decimal :amount
+  t.timestamps
+end
+```
+
+## DuckDB-Specific Column Types
+
+### Integer Variants
+
+```ruby
+create_table :analytics do |t|
+  t.tinyint :small_counter      # 1 byte: -128 to 127
+  t.smallint :medium_counter    # 2 bytes: -32,768 to 32,767
+  t.integer :standard_counter   # 4 bytes (standard)
+  t.bigint :large_counter       # 8 bytes
+  t.hugeint :massive_counter    # 16 bytes: very large integers
+
+  # Unsigned variants
+  t.utinyint :positive_small    # 1 byte: 0 to 255
+  t.usmallint :positive_medium  # 2 bytes: 0 to 65,535
+  t.uinteger :positive_standard # 4 bytes: 0 to 4,294,967,295
+  t.ubigint :positive_large     # 8 bytes
+  t.uhugeint :positive_massive  # 16 bytes
+
+  t.varint :flexible_precision  # Variable precision (up to 1.2M digits)
+end
+```
+
+### Special Data Types
+
+```ruby
+create_table :advanced_types do |t|
+  t.uuid :identifier           # UUID type
+  t.interval :duration          # Time intervals
+  t.bit :flags                  # Bit strings
+end
+```
+
+### Complex/Nested Types
+
+```ruby
+create_table :complex_data do |t|
+  # List/Array columns
+  t.list :tags, element_type: :string
+  t.list :scores, element_type: :integer
+
+  # Struct columns (composite types)
+  t.struct :address, fields: {
+    street: :string,
+    city: :string,
+    zip: :integer,
+    country: :string
+  }
+
+  # Map columns (key-value pairs)
+  t.map :metadata, key_type: :string, value_type: :string
+  t.map :counters, key_type: :string, value_type: :integer
+
+  # Enum columns
+  t.enum :status, values: ['active', 'inactive', 'pending', 'archived']
+  t.enum :priority, values: ['low', 'medium', 'high', 'critical']
+end
+```
+
+## Migration Examples
+
+### Basic Table with Integer Primary Key
+
+```ruby
+class CreateUsers < ActiveRecord::Migration[7.0]
+  def change
+    # Standard Rails migration - works exactly like other databases
+    create_table :users do |t|
+      t.string :email, null: false
+      t.string :name
+      t.timestamps
+    end
+  end
+end
+```
+
+### Table with UUID Primary Key
+
+```ruby
+class CreateSessions < ActiveRecord::Migration[7.0]
+  def change
+    # Rails convention for UUID primary keys
+    create_table :sessions, id: :uuid do |t|
+      t.string :session_token
+      t.references :user, type: :bigint, foreign_key: true
+      t.timestamps
+    end
+  end
+end
+```
+
+### Complex Data Types Example
+
+```ruby
+class CreateProducts < ActiveRecord::Migration[7.0]
+  def change
+    # Standard Rails table with DuckDB-specific types
+    create_table :products do |t|
+      t.string :name, null: false
+      t.decimal :price, precision: 10, scale: 2
+
+      # DuckDB complex data types
+      t.list :tags, element_type: :string
+      t.struct :dimensions, fields: {
+        length: :decimal,
+        width: :decimal,
+        height: :decimal,
+        unit: :string
+      }
+      t.map :attributes, key_type: :string, value_type: :string
+      t.enum :status, values: ['draft', 'active', 'discontinued']
+
+      t.timestamps
+    end
+  end
+end
+```
+
+### Working with Sequences in Existing Tables
+
+```ruby
+class AddAutoIncrementToItems < ActiveRecord::Migration[7.0]
+  def change
+    # Create sequence and add column manually if needed
+    create_sequence 'items_serial_number_seq', start_with: 1
+
+    change_table :items do |t|
+      t.bigint :serial_number, default: -> { "nextval('items_serial_number_seq')" }
+    end
+  end
+end
+```
+
+## Adapter Configuration
+
+### Setting Default Primary Key Type
+
+```ruby
+# In your application configuration or initializer
+# The adapter defaults to :bigint (Rails 5+ convention)
+ActiveRecord::ConnectionAdapters::DuckdbAdapter.primary_key_type = :bigint
+
+# To change default to UUID globally
+ActiveRecord::ConnectionAdapters::DuckdbAdapter.primary_key_type = :uuid
+
+# Individual tables can still override with id: :integer, id: :uuid, etc.
+```
+
+## Sequence Operations
+
+### Working with Sequences in Code
+
+```ruby
+# Get next value from a sequence
+next_id = User.connection.next_sequence_value('users_id_seq')
+
+# Reset sequence to specific value
+User.connection.reset_sequence!('users_id_seq', 1000)
+
+# Check if sequence exists
+if User.connection.sequence_exists?('users_id_seq')
+  # Do something with the sequence
+end
+
+# List all sequences
+sequences = User.connection.sequences
+```
+
+## Best Practices
+
+1. **Follow Rails conventions**: Use standard `create_table` with `id: :uuid` or `id: :bigint` options
+2. **Use appropriate integer types**: Choose the smallest integer type that fits your needs
+3. **Consider UUID for distributed systems**: Use `id: :uuid` for distributed applications
+4. **Leverage complex types**: Use DuckDB's advanced types like `LIST` and `STRUCT` for analytical workloads
+5. **Trust Rails defaults**: The adapter handles sequences automatically for integer primary keys
+6. **Use manual sequences sparingly**: Only create custom sequences when you need specific behavior
+
+## Troubleshooting
+
+### Common Issues
+
+1. **Sequence already exists**: If you get sequence already exists errors, check if the sequence was created from a previous migration
+2. **UUID dependencies**: Make sure your application can generate UUIDs when using UUID primary keys
+3. **Complex type support**: Verify your DuckDB version supports the complex types you're trying to use
+
+### Debugging Sequences
+
+```ruby
+# Check if a sequence exists
+connection.sequence_exists?('users_id_seq')
+# => true
+
+# List all sequences
+connection.sequences
+# => ['users_id_seq', 'products_id_seq', ...]
+
+# Standard Rails way - sequences are handled automatically
+create_table :test_table do |t|
+  t.string :name
+end
+# Sequence creation is managed behind the scenes
+```
+
+This `TableDefinition` provides seamless Rails compatibility plus access to DuckDB's advanced features, making it easy to build both traditional Rails applications and analytical workloads with DuckDB.

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

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module ActiveRecord
+  module ConnectionAdapters
+    module Duckdb
+      class Column < ConnectionAdapters::Column
+        # Initialize a new DuckDB column with DuckDB-specific attributes
+        # @param auto_increment [Boolean, nil] whether this column is auto-incrementing
+        # @param rowid [Boolean, nil] whether this column is a rowid column
+        # @param generated_type [Symbol, nil] the type of generated column (:stored, :virtual)
+        # @param extra [String, nil] extra column definition information
+        def initialize(*, auto_increment: nil, rowid: nil, generated_type: nil, extra: nil, **)
+          super(*, **)
+          @auto_increment = auto_increment
+          @rowid = rowid
+          @generated_type = generated_type
+          @extra = extra
+        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
+
+        # @return [String, nil] extra column definition information
+        attr_reader :extra
+        # @return [Boolean, nil] whether this column is a rowid column
+        attr_reader :rowid
+
+        # Check if this column is a virtual/generated column
+        # https://duckdb.org/docs/stable/sql/statements/create_table#generated-columns
+        # TODO: Implement full virtual column support
+        # @return [Boolean] always returns false until virtual columns are fully implemented
+        def virtual?
+          # /\b(?:VIRTUAL|STORED|GENERATED)\b/.match?(extra)
+          false
+        end
+
+        # def virtual_stored?
+        #   virtual? && @generated_type == :stored
+        # end
+
+        # Check if this column has a default value
+        # @return [Boolean] true if the column has a default value
+        def has_default?
+          # super && !virtual?
+          !!super
+        end
+
+        # Check if this column is auto-incrementing
+        # We probably need to check if the column is a UUID
+        # @return [Boolean] true if the column auto-increments
+        def auto_increment?
+          !!@auto_increment
+        end
+
+        # Check if this column's value is automatically incremented by the database
+        # @return [Boolean] true if the column is auto-incremented by the database
+        def auto_incremented_by_db?
+          auto_increment? || !!rowid
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module ActiveRecord
+  module ConnectionAdapters
+    # DuckDB Limits - https://duckdb.org/docs/stable/operations_manual/limits.html
+    module Duckdb
+      module DatabaseLimits
+        # Since DuckDb is PostgreSQL compatible (64-1), we can use the same limits as PostgreSQL.
+        # In the future want to drop possible PostgreSQL compatibility
+        # we can change the limits to match whatever limits DuckDB may want to impose
+        # https://www.postgresql.org/docs/current/sql-syntax-lexical.html#SQL-SYNTAX-IDENTIFIERS
+        # Returns the maximum length for database identifiers
+        # @return [Integer] The maximum identifier length (63 characters for PostgreSQL compatibility)
+        def max_identifier_length
+          63
+        end
+
+        # Returns the maximum length for table aliases
+        # @return [Integer] The maximum table alias length (delegates to max_identifier_length)
+        def table_alias_length
+          max_identifier_length
+        end
+
+        # Returns the maximum length for table names
+        # @return [Integer] The maximum table name length (delegates to max_identifier_length)
+        def table_name_length
+          max_identifier_length
+        end
+
+        # Returns the maximum length for index names
+        # @return [Integer] The maximum index name length (delegates to max_identifier_length)
+        def index_name_length
+          max_identifier_length
+        end
+
+        private
+
+        # The max number of binds is 1024
+        # Returns the maximum number of bind parameters for queries
+        # @return [Integer] The maximum number of bind parameters (1000)
+        def bind_params_length
+          1_000
+        end
+
+        # https://duckdb.org/docs/stable/data/insert.html
+        # Returns the maximum number of rows that can be inserted in a single operation
+        # @return [Integer] The maximum number of rows for batch inserts (1000)
+        def insert_rows_length
+          1_000
+        end
+      end
+    end
+  end
+end