sequel-duckdb 0.1.0

data/.kiro/specs/sql-expression-handling-fix/design.md

@@ -0,0 +1,298 @@
+# Design Document: SQL Expression Handling Fix
+
+## Overview
+
+This design addresses critical SQL expression handling issues in the sequel-duckdb adapter where SQL expressions, functions, and literal strings are incorrectly treated as regular string literals and quoted when they should be rendered as raw SQL. The fix involves implementing proper type detection and handling in the `literal_append` method to distinguish between different SQL object types.
+
+The core issue is that the current adapter implementation doesn't properly handle Sequel's expression objects (`Sequel::LiteralString`, `Sequel::SQL::Function`, etc.) and treats them as regular Ruby strings, causing them to be quoted inappropriately in the generated SQL.
+
+## Architecture
+
+### Current Problem
+
+The existing `literal_append` method in the DuckDB adapter handles `String` objects without first checking if they are `Sequel::LiteralString` objects. This causes `LiteralString` objects (created by `Sequel.lit()`) to be treated as regular strings and quoted inappropriately. The method correctly handles `Time` and `DateTime` objects but falls through to `literal_string_append` for all `String` objects, including `LiteralString`.
+
+### Solution Architecture
+
+The solution follows Sequel core's established pattern by checking for `LiteralString` as a special case of `String` before applying string quoting:
+
+1. **Sequel Core Pattern Compliance**: Follows the exact pattern used in Sequel core's `literal_append` method
+2. **LiteralString Special Handling**: Checks for `LiteralString` before regular `String` processing
+3. **Minimal Change**: Only adds the missing `LiteralString` check to existing logic
+4. **Parent Delegation**: Continues to delegate `SQL::Function` and other expressions to parent class
+
+### Design Pattern
+
+Following Sequel's adapter pattern, the fix will be implemented in the `DatasetMethods` module within `lib/sequel/adapters/shared/duckdb.rb`, allowing the main `Dataset` class to inherit the corrected behavior through the include mechanism.
+
+## Components and Interfaces
+
+### Core Component: Enhanced literal_append Method
+
+**Location**: `Sequel::DuckDB::DatasetMethods` module
+
+**Interface**:
+```ruby
+def literal_append(sql, v)
+  case v
+  when Time
+    literal_datetime_append(sql, v)
+  when DateTime
+    literal_datetime_append(sql, v)
+  when String
+    case v
+    when LiteralString
+      sql << v  # Append directly without quoting
+    else
+      if v.encoding == Encoding::ASCII_8BIT
+        literal_blob_append(sql, v)
+      else
+        literal_string_append(sql, v)
+      end
+    end
+  else
+    super
+  end
+end
+```
+
+### Type Handling Components
+
+#### 1. LiteralString Handler
+- **Purpose**: Process `Sequel.lit()` expressions as raw SQL following Sequel core pattern
+- **Behavior**: Append string content directly without quoting (`sql << v`)
+- **Input**: `Sequel::LiteralString` objects (subclass of `String`)
+- **Output**: Raw SQL string appended to query
+
+#### 2. Regular String Handler
+- **Purpose**: Process regular Ruby strings with appropriate encoding handling
+- **Behavior**: Apply existing binary/text string logic
+- **Input**: Regular `String` objects (excluding `LiteralString`)
+- **Output**: Properly quoted and escaped string literals
+
+#### 3. Parent Class Delegation
+- **Purpose**: Handle all other data types including `SQL::Function`
+- **Behavior**: Delegate to parent class implementation (which already works correctly)
+- **Input**: All other Ruby/Sequel objects including `SQL::Expression` subclasses
+- **Output**: Appropriately formatted literals using Sequel core logic
+
+### Integration Points
+
+#### Dataset Class Integration
+The enhanced `literal_append` method integrates with:
+- **SQL Generation Pipeline**: Core Sequel SQL building process
+- **Query Context Handling**: SELECT, WHERE, ORDER BY, GROUP BY, HAVING clauses
+- **Expression Composition**: Nested and complex expressions
+
+#### Sequel Framework Integration
+- **Parent Class Delegation**: Leverages existing Sequel functionality
+- **Type System Compatibility**: Works with Sequel's expression type hierarchy
+- **Error Handling**: Integrates with Sequel's error reporting system
+
+## Data Models
+
+### Input Data Types
+
+#### Sequel::LiteralString
+```ruby
+# Created by: Sequel.lit("YEAR(created_at)")
+# Properties:
+#   - Contains raw SQL string
+#   - Should not be quoted
+#   - Used for expressions, functions, literals
+```
+
+#### Sequel::SQL::Function
+```ruby
+# Created by: Sequel.function(:count, :*)
+# Properties:
+#   - Function name and arguments
+#   - Requires special rendering logic
+#   - May contain nested expressions
+```
+
+#### Regular Data Types
+```ruby
+# String, Integer, Float, Date, Time, etc.
+# Properties:
+#   - Standard Ruby types
+#   - Require appropriate SQL formatting
+#   - Should be quoted/escaped as needed
+```
+
+### Output Data Model
+
+#### SQL String Buffer
+- **Type**: String (mutable)
+- **Content**: Accumulated SQL query text
+- **Modification**: Appended to by `literal_append`
+
+## Error Handling
+
+### Error Categories
+
+#### 1. Unsupported Expression Types
+- **Scenario**: Unknown SQL expression object encountered
+- **Response**: Clear error message with object type information
+- **Error Type**: `Sequel::Error` or subclass
+
+#### 2. Expression Rendering Failures
+- **Scenario**: Function or expression rendering fails
+- **Response**: Context-aware error with failing expression details
+- **Error Type**: `Sequel::DatabaseError`
+
+#### 3. SQL Generation Failures
+- **Scenario**: Overall SQL generation fails due to expression issues
+- **Response**: Categorized error with query context
+- **Error Type**: `Sequel::DatabaseError`
+
+### Error Handling Strategy
+
+```ruby
+def literal_append(sql, v)
+  case v
+  when Time
+    literal_datetime_append(sql, v)
+  when DateTime
+    literal_datetime_append(sql, v)
+  when String
+    case v
+    when LiteralString
+      sql << v
+    else
+      if v.encoding == Encoding::ASCII_8BIT
+        literal_blob_append(sql, v)
+      else
+        literal_string_append(sql, v)
+      end
+    end
+  else
+    super
+  end
+rescue => e
+  raise Sequel::DatabaseError, "Failed to render SQL literal: #{e.message}"
+end
+```
+
+## Testing Strategy
+
+### Test Categories
+
+#### 1. Unit Tests - SQL Generation
+- **Framework**: Sequel mock database
+- **Purpose**: Test SQL generation without database connections
+- **Coverage**: All expression types and combinations
+- **Location**: `test/sql_test.rb`
+
+#### 2. Integration Tests - Database Operations
+- **Framework**: Real DuckDB in-memory databases
+- **Purpose**: End-to-end expression functionality
+- **Coverage**: Query execution with expressions
+- **Location**: `test/dataset_test.rb`
+
+#### 3. Regression Tests
+- **Purpose**: Ensure backward compatibility
+- **Coverage**: Existing functionality continues working
+- **Location**: Multiple test files
+
+### Test Implementation Approach
+
+#### Test-Driven Development
+1. **Write failing tests** for each expression type
+2. **Implement minimal fix** to make tests pass
+3. **Refactor** while maintaining green tests
+4. **Add edge case tests** and handle them
+
+#### Test Structure
+```ruby
+def test_literal_string_handling
+  # Test Sequel.lit() expressions
+  dataset = @db[:users].select(Sequel.lit("YEAR(created_at)"))
+  assert_equal "SELECT YEAR(created_at) FROM users", dataset.sql
+end
+
+def test_function_handling_still_works
+  # Test that Sequel.function() calls continue to work (already working)
+  dataset = @db[:users].select(Sequel.function(:count, :*))
+  assert_equal "SELECT count(*) FROM users", dataset.sql
+end
+
+def test_regular_string_still_quoted
+  # Test that regular strings are still properly quoted
+  dataset = @db[:users].where(name: "John's")
+  assert_equal "SELECT * FROM users WHERE (name = 'John''s')", dataset.sql
+end
+```
+
+### Coverage Requirements
+- **100% line coverage** for new `literal_append` method
+- **Branch coverage** for all case statements
+- **Edge case coverage** for error conditions
+- **Integration coverage** for all SQL clause types
+
+## Design Decisions and Rationales
+
+### Decision 1: Follow Sequel Core Pattern Exactly
+**Rationale**: Sequel core already has the correct pattern for handling `LiteralString` as a special case of `String`. Following this established pattern ensures compatibility and maintainability.
+
+**Evidence**: Sequel core's `literal_append` method in `/sequel/dataset/sql.rb` shows the exact pattern:
+```ruby
+when String
+  case v
+  when LiteralString
+    sql << v
+  when SQL::Blob
+    literal_blob_append(sql, v)
+  else
+    literal_string_append(sql, v)
+  end
+```
+
+### Decision 2: Minimal Modification Approach
+**Rationale**: The current implementation already works correctly for most types. Only the `LiteralString` handling is missing, so we add the minimal necessary check.
+
+**Alternatives Considered**:
+- Complete rewrite of literal_append (rejected - unnecessary and risky)
+- Separate method for LiteralString (rejected - doesn't follow Sequel patterns)
+
+### Decision 3: No Changes to Function Handling
+**Rationale**: Testing revealed that `SQL::Function` objects already work correctly through parent class delegation. The issue is specifically with `LiteralString` objects being treated as regular strings.
+
+**Evidence**:
+- `db[:test].select(Sequel.function(:count, :*)).sql` produces correct `"SELECT count(*) FROM test"`
+- `db[:test].select(Sequel.lit('YEAR(created_at)')).sql` incorrectly produces `"SELECT 'YEAR(created_at)' FROM test"`
+
+### Decision 4: Preserve Existing Time/DateTime/Binary Handling
+**Rationale**: The current implementation correctly handles `Time`, `DateTime`, and binary string encoding. These should remain unchanged.
+
+**Benefits**:
+- Maintains backward compatibility for existing functionality
+- Focuses fix on the specific problem area
+- Reduces risk of regression in working features
+
+### Decision 5: Integration in DatasetMethods Module
+**Rationale**: Following the established sequel-duckdb pattern where shared functionality is implemented in modules and included in main classes.
+
+**Benefits**:
+- Consistent with existing codebase architecture
+- Allows for easy testing and maintenance
+- Follows Sequel adapter conventions
+
+## Implementation Phases
+
+### Phase 1: Fix LiteralString Handling
+- Modify existing `literal_append` method to check for `LiteralString` before regular `String`
+- Add comprehensive unit tests for `LiteralString` handling
+- Verify existing functionality remains intact
+
+### Phase 2: Comprehensive Testing
+- Add integration tests with real database operations
+- Test all SQL clause contexts (SELECT, WHERE, ORDER BY, etc.)
+- Add regression tests to ensure no existing functionality breaks
+
+### Phase 3: Edge Cases and Error Handling
+- Test complex nested expressions
+- Verify error handling for malformed expressions
+- Performance verification with existing benchmarks
+
+This design provides a focused, low-risk solution that addresses the core SQL expression handling issues while maintaining full backward compatibility and following established Sequel adapter patterns.

data/.kiro/specs/sql-expression-handling-fix/requirements.md

@@ -0,0 +1,86 @@
+# Requirements Document
+
+## Introduction
+
+This specification addresses critical SQL expression handling issues in the sequel-duckdb adapter. The adapter is currently incorrectly treating SQL expressions, functions, and literal strings as regular string literals, causing them to be quoted when they should be rendered as raw SQL. This breaks fundamental SQL generation functionality and prevents proper use of database functions, expressions, and literal SQL.
+
+## Requirements
+
+### Requirement 1: Sequel::LiteralString Handling
+
+**User Story:** As a developer using Sequel with DuckDB, I want to use `Sequel.lit()` to include raw SQL expressions in my queries, so that I can use database functions and complex expressions without them being quoted as strings.
+
+#### Acceptance Criteria
+
+1. WHEN I use `Sequel.lit("YEAR(created_at)")` in a SELECT clause THEN the generated SQL SHALL contain `YEAR(created_at)` without quotes
+2. WHEN I use `Sequel.lit("LENGTH(name) > 5")` in a WHERE clause THEN the generated SQL SHALL contain `LENGTH(name) > 5` without quotes
+3. WHEN I use `Sequel.lit("CURRENT_TIMESTAMP")` in an UPDATE clause THEN the generated SQL SHALL contain `CURRENT_TIMESTAMP` without quotes
+4. WHEN I use `Sequel.lit("name || ' ' || email AS full_info")` in a SELECT clause THEN the generated SQL SHALL contain the expression without quotes
+
+### Requirement 2: Sequel::SQL::Function Handling
+
+**User Story:** As a developer using Sequel with DuckDB, I want to use `Sequel.function()` to call database functions, so that function calls are properly generated in SQL without being quoted as strings.
+
+#### Acceptance Criteria
+
+1. WHEN I use `Sequel.function(:count, :*)` THEN the generated SQL SHALL contain `count(*)`
+2. WHEN I use `Sequel.function(:sum, :amount)` THEN the generated SQL SHALL contain `sum(amount)`
+3. WHEN I use `Sequel.function(:year, :created_at)` THEN the generated SQL SHALL contain `year(created_at)`
+4. WHEN I use nested functions like `Sequel.function(:count, Sequel.function(:distinct, :name))` THEN the generated SQL SHALL contain `count(distinct(name))`
+
+### Requirement 3: Complex Expression Handling
+
+**User Story:** As a developer using Sequel with DuckDB, I want to use complex SQL expressions with operators and functions, so that they are properly rendered as SQL without being quoted.
+
+#### Acceptance Criteria
+
+1. WHEN I use expressions with mathematical operators THEN they SHALL be rendered as raw SQL
+2. WHEN I use expressions with string concatenation operators THEN they SHALL be rendered as raw SQL
+3. WHEN I use expressions with comparison operators THEN they SHALL be rendered as raw SQL
+4. WHEN I use expressions with logical operators THEN they SHALL be rendered as raw SQL
+
+### Requirement 4: Literal Append Method Override
+
+**User Story:** As a developer maintaining the sequel-duckdb adapter, I want the `literal_append` method to properly distinguish between different types of SQL objects, so that each type is handled appropriately.
+
+#### Acceptance Criteria
+
+1. WHEN `literal_append` receives a `Sequel::LiteralString` object THEN it SHALL append the string content without quotes
+2. WHEN `literal_append` receives a `Sequel::SQL::Function` object THEN it SHALL delegate to the appropriate function rendering method
+3. WHEN `literal_append` receives a regular String object THEN it SHALL quote it as a string literal
+4. WHEN `literal_append` receives other SQL expression objects THEN it SHALL delegate to the parent class method
+
+### Requirement 5: Expression Context Preservation
+
+**User Story:** As a developer using Sequel with DuckDB, I want SQL expressions to maintain their context when used in different parts of queries, so that they work correctly in SELECT, WHERE, ORDER BY, GROUP BY, and HAVING clauses.
+
+#### Acceptance Criteria
+
+1. WHEN I use expressions in SELECT clauses THEN they SHALL be rendered as raw SQL
+2. WHEN I use expressions in WHERE clauses THEN they SHALL be rendered as raw SQL
+3. WHEN I use expressions in ORDER BY clauses THEN they SHALL be rendered as raw SQL
+4. WHEN I use expressions in GROUP BY clauses THEN they SHALL be rendered as raw SQL
+5. WHEN I use expressions in HAVING clauses THEN they SHALL be rendered as raw SQL
+6. WHEN I use expressions in UPDATE SET clauses THEN they SHALL be rendered as raw SQL
+
+### Requirement 6: Backward Compatibility
+
+**User Story:** As a developer using the sequel-duckdb adapter, I want existing functionality to continue working after expression handling is fixed, so that my current code doesn't break.
+
+#### Acceptance Criteria
+
+1. WHEN I use regular string values in queries THEN they SHALL still be properly quoted as string literals
+2. WHEN I use numeric values in queries THEN they SHALL still be rendered as numeric literals
+3. WHEN I use boolean values in queries THEN they SHALL still be rendered as boolean literals
+4. WHEN I use date/time values in queries THEN they SHALL still be rendered with proper formatting
+5. WHEN I use binary data in queries THEN it SHALL still be rendered as hex literals
+
+### Requirement 7: Error Handling
+
+**User Story:** As a developer using the sequel-duckdb adapter, I want clear error messages when expression handling fails, so that I can debug issues effectively.
+
+#### Acceptance Criteria
+
+1. WHEN an unsupported expression type is encountered THEN a clear error message SHALL be provided
+2. WHEN expression rendering fails THEN the error SHALL include context about the failing expression
+3. WHEN SQL generation fails due to expression issues THEN the error SHALL be properly categorized as a DatabaseError

data/.kiro/specs/sql-expression-handling-fix/tasks.md

@@ -0,0 +1,22 @@
+# Implementation Plan
+
+- [x] 1. Write tests for LiteralString handling
+  - Add test in `test/sql_test.rb` to verify `Sequel.lit()` expressions are not quoted
+  - Test LiteralString in SELECT clause: `db[:test].select(Sequel.lit('YEAR(created_at)')).sql`
+  - Test LiteralString in WHERE clause: `db[:test].where(Sequel.lit('age > 18')).sql`
+  - Add regression test to ensure regular strings are still quoted properly
+  - Add test to ensure SQL::Function continues working (should be unchanged)
+  - _Requirements: 1.1, 1.2, 4.1, 6.1_
+
+- [x] 2. Fix literal_append method to handle LiteralString
+  - Modify existing `literal_append` method in `lib/sequel/adapters/shared/duckdb.rb`
+  - Add `LiteralString` check as special case of `String` following Sequel core pattern
+  - Change `when String` to nested case with `when LiteralString` that does `sql << v`
+  - Preserve all existing logic for Time, DateTime, and binary strings
+  - _Requirements: 1.1, 4.1, 4.2, 4.4, 6.1_
+
+- [x] 3. Add integration test with real database
+  - Add test in `test/dataset_test.rb` using real DuckDB database
+  - Test that LiteralString expressions actually execute correctly
+  - Verify no regression in existing database operations
+  - _Requirements: 1.2, 5.1, 6.1_

data/.kiro/specs/test-infrastructure-improvements/requirements.md

@@ -0,0 +1,106 @@
+# Requirements Document
+
+## Introduction
+
+This specification addresses test infrastructure issues in the sequel-duckdb adapter test suite. Many tests are failing due to incorrect assertions, wrong expectations about dataset types, and improper test setup rather than actual functionality problems. The test infrastructure needs to be improved to properly test the adapter's functionality while being flexible about implementation details.
+
+## Requirements
+
+### Requirement 1: Dataset Type Assertion Fixes
+
+**User Story:** As a developer maintaining the sequel-duckdb adapter, I want tests to check functionality rather than exact class types, so that tests pass when the adapter works correctly regardless of internal Sequel implementation details.
+
+#### Acceptance Criteria
+
+1. WHEN tests check dataset types THEN they SHALL use `respond_to?` or duck typing instead of exact class matching
+2. WHEN Sequel creates dataset subclasses THEN tests SHALL accept them as valid datasets
+3. WHEN tests verify dataset functionality THEN they SHALL test behavior rather than class hierarchy
+4. WHEN new Sequel versions change internal class structures THEN tests SHALL continue to pass
+
+### Requirement 2: Mock Database Configuration
+
+**User Story:** As a developer running tests for the sequel-duckdb adapter, I want the mock database to properly simulate DuckDB behavior, so that SQL generation tests accurately reflect real adapter behavior.
+
+#### Acceptance Criteria
+
+1. WHEN mock database is created THEN it SHALL include DuckDB-specific dataset methods
+2. WHEN mock database generates SQL THEN it SHALL use DuckDB syntax rules
+3. WHEN mock database handles identifiers THEN it SHALL use DuckDB quoting rules
+4. WHEN mock database processes expressions THEN it SHALL use DuckDB literal handling
+
+### Requirement 3: Test Helper Method Improvements
+
+**User Story:** As a developer writing tests for the sequel-duckdb adapter, I want test helper methods that work correctly with DuckDB's SQL syntax variations, so that I can write reliable tests without worrying about syntax differences.
+
+#### Acceptance Criteria
+
+1. WHEN `assert_sql` helper is used THEN it SHALL handle DuckDB syntax variations gracefully
+2. WHEN SQL comparison is needed THEN helper methods SHALL normalize minor syntax differences
+3. WHEN testing SQL patterns THEN helper methods SHALL support flexible matching
+4. WHEN debugging test failures THEN helper methods SHALL provide clear error messages
+
+### Requirement 4: Integration Test Setup
+
+**User Story:** As a developer running integration tests for the sequel-duckdb adapter, I want proper test database setup and teardown, so that integration tests run reliably and don't interfere with each other.
+
+#### Acceptance Criteria
+
+1. WHEN integration tests run THEN each test SHALL have a clean database state
+2. WHEN tests create tables THEN they SHALL be properly cleaned up after the test
+3. WHEN tests insert data THEN it SHALL not affect other tests
+4. WHEN tests fail THEN database state SHALL be properly reset for subsequent tests
+
+### Requirement 5: Test Data Management
+
+**User Story:** As a developer writing tests for the sequel-duckdb adapter, I want consistent test data setup utilities, so that I can focus on testing functionality rather than data preparation.
+
+#### Acceptance Criteria
+
+1. WHEN tests need sample data THEN standardized helper methods SHALL be available
+2. WHEN tests need specific table schemas THEN reusable setup methods SHALL be provided
+3. WHEN tests need to verify data integrity THEN helper methods SHALL validate expected state
+4. WHEN tests need to clean up data THEN helper methods SHALL ensure complete cleanup
+
+### Requirement 6: Error Message Improvements
+
+**User Story:** As a developer debugging failing tests in the sequel-duckdb adapter, I want clear and informative error messages, so that I can quickly identify and fix issues.
+
+#### Acceptance Criteria
+
+1. WHEN SQL assertion fails THEN the error message SHALL show both expected and actual SQL clearly
+2. WHEN dataset type assertion fails THEN the error message SHALL explain what was expected and why
+3. WHEN database operation fails THEN the error message SHALL include relevant context
+4. WHEN test setup fails THEN the error message SHALL indicate the specific setup step that failed
+
+### Requirement 7: Test Organization and Naming
+
+**User Story:** As a developer maintaining the sequel-duckdb adapter test suite, I want tests to be well-organized and clearly named, so that I can easily understand what each test covers and find relevant tests when debugging.
+
+#### Acceptance Criteria
+
+1. WHEN tests are grouped by functionality THEN the grouping SHALL be logical and consistent
+2. WHEN test methods are named THEN the names SHALL clearly describe what is being tested
+3. WHEN tests cover edge cases THEN they SHALL be clearly identified as such
+4. WHEN tests are added THEN they SHALL follow established naming and organization patterns
+
+### Requirement 8: Test Performance Optimization
+
+**User Story:** As a developer running the sequel-duckdb adapter test suite, I want tests to run quickly and efficiently, so that I can get fast feedback during development.
+
+#### Acceptance Criteria
+
+1. WHEN unit tests run THEN they SHALL complete quickly without database connections
+2. WHEN integration tests run THEN they SHALL use efficient database operations
+3. WHEN test suite runs THEN it SHALL minimize redundant setup and teardown operations
+4. WHEN tests are parallelized THEN they SHALL not interfere with each other
+
+### Requirement 9: Test Coverage Validation
+
+**User Story:** As a developer maintaining the sequel-duckdb adapter, I want to ensure comprehensive test coverage, so that all functionality is properly tested and regressions are caught early.
+
+#### Acceptance Criteria
+
+1. WHEN new functionality is added THEN corresponding tests SHALL be required
+2. WHEN tests are removed THEN coverage impact SHALL be evaluated
+3. WHEN test coverage is measured THEN it SHALL include both unit and integration tests
+4. WHEN coverage gaps are identified THEN they SHALL be prioritized for additional testing

data/.kiro/steering/product.md

@@ -0,0 +1,22 @@
+# Product Overview
+
+sequel-duckdb is a Ruby gem that provides a complete database adapter for the Sequel toolkit to work with DuckDB. This gem enables Ruby applications to connect to and interact with DuckDB databases through Sequel's comprehensive ORM and database abstraction interface.
+
+## Key Features
+- Full DuckDB database adapter for Sequel
+- Ruby 3.1+ compatibility
+- Complete SQL generation and query support
+- Connection management via ruby-duckdb gem
+- Comprehensive test coverage for all SQL operations
+
+## Reference Projects
+- **jeremyevans/sequel**: Official Sequel repository for coding conventions
+- **sequel-hexspace**: Secondary reference for adapter structure
+- **sequel_impala**: Tertiary reference for implementation patterns
+
+## Target Users
+- Ruby developers using Sequel ORM
+- Applications requiring DuckDB integration
+
+## Implementation Approach
+This project follows the proven patterns from existing Sequel adapters, with implementation order guided by git history analysis of reference projects. All development is designed to be AI-agent friendly with thorough documentation and incremental implementation.

data/.kiro/steering/structure.md

@@ -0,0 +1,88 @@
+# Project Structure
+
+## Root Directory
+
+- **Gemfile**: Dependency specification
+- **Rakefile**: Build tasks and automation
+- **sequel-duckdb.gemspec**: Gem specification
+- **.rubocop.yml**: Code style configuration
+- **README.md**: Project documentation
+- **CHANGELOG.md**: Version history
+
+## Core Library Structure (Following sequel-hexspace Pattern)
+
+```text
+lib/
+└── sequel/
+    └── adapters/
+        ├── duckdb.rb              # Main adapter file (Database & Dataset classes)
+        └── shared/
+            └── duckdb.rb          # Shared DuckDB-specific functionality
+```
+
+## Organization Patterns
+
+- **Namespace**: `Sequel::DuckDB` - follows Sequel's adapter pattern exactly like sequel-hexspace
+- **Adapter Structure**: Main adapter in `lib/sequel/adapters/duckdb.rb` with Database and Dataset classes
+- **Shared Functionality**: Common methods in `lib/sequel/adapters/shared/duckdb.rb` with DatabaseMethods and DatasetMethods modules
+- **Database Class**: `Sequel::DuckDB::Database` includes `Sequel::DuckDB::DatabaseMethods` for connection management
+- **Dataset Class**: `Sequel::DuckDB::Dataset` includes `Sequel::DuckDB::DatasetMethods` for SQL generation
+- **Module Pattern**: Use include pattern exactly like sequel-hexspace to separate concerns between main classes and shared functionality
+
+## Development Structure
+
+- **bin/**: Development executables (console, setup)
+- **test/**: Comprehensive test suite following sequel-hexspace pattern
+- **sig/**: RBS type signatures for Ruby 3+ type checking
+- **.kiro/**: AI assistant configuration and steering rules
+
+## File Naming Conventions
+
+- Use snake_case for file names
+- Match file names to adapter names (duckdb.rb for DuckDB adapter)
+- Follow sequel-hexspace directory structure exactly
+- Standard Ruby gem layout with adapter-specific organization
+
+## Key Architectural Decisions
+
+- **Database Adapter Pattern**: Full Sequel database adapter implementation following sequel-hexspace
+- **Reference-Driven Design**: Mirror sequel-hexspace structure and patterns exactly
+- **Test-First Development**: Comprehensive test coverage before implementation
+- **Incremental Implementation**: Small, clearly defined implementation pieces
+- **AI-Agent Friendly**: Thorough documentation for autonomous development
+
+## Implementation Order (based on sequel-hexspace git history)
+
+1. **Connection Management**: Database connection and basic connectivity
+2. **Schema Operations**: Table creation, modification, introspection
+3. **Basic SQL Generation**: SELECT, INSERT, UPDATE, DELETE operations
+4. **Advanced SQL Features**: JOINs, subqueries, window functions
+5. **DuckDB-Specific Features**: Specialized functions and optimizations
+6. **Performance Optimizations**: Bulk operations, prepared statements
+
+## Adding New Features
+
+- **Research First**: Study sequel-hexspace implementation patterns directly
+- **Document Thoroughly**: Create detailed specifications before coding
+- **Test-Driven**: Write comprehensive tests first
+- **Incremental**: Implement in small, testable pieces
+- **Follow Conventions**: Adhere to sequel-hexspace coding standards exactly
+- Place main Database and Dataset classes in `lib/sequel/adapters/duckdb.rb`
+- Place DatabaseMethods and DatasetMethods modules in `lib/sequel/adapters/shared/duckdb.rb`
+- Use include pattern to mix shared functionality into main classes
+- Mirror sequel-hexspace file organization and module structure exactly
+
+## Testing Structure (Following sequel-hexspace Pattern)
+
+- **test/all.rb**: Test runner
+- **test/spec_helper.rb**: Test configuration and setup
+- **test/database_test.rb**: Database connection and basic functionality tests
+- **test/dataset_test.rb**: Comprehensive SQL generation tests
+- **test/schema_test.rb**: Schema operations and introspection tests
+- **test/prepared_statement_test.rb**: Prepared statement functionality
+- **test/sql_test.rb**: SQL generation and syntax tests
+- **test/type_test.rb**: Data type handling tests
+- Mirror sequel-hexspace test organization exactly
+- Test all SQL generation comprehensively
+- Include integration tests with actual DuckDB instances
+- Follow TDD methodology throughout development