sequelizer 0.1.4 → 0.2.0

data/.overcommit.yml

@@ -0,0 +1,73 @@
+# Overcommit configuration for Sequelizer
+# See https://github.com/sds/overcommit for documentation
+
+PreCommit:
+  # Run RuboCop to check for style violations and auto-fix when possible
+  RuboCop:
+    enabled: true
+    command: ['bundle', 'exec', 'rubocop']
+    flags: ['--autocorrect']
+    include:
+      - '**/*.rb'
+      - '**/*.rake'
+      - '**/Rakefile'
+      - '**/Gemfile'
+      - '**/*.gemspec'
+
+  # Run tests to ensure nothing is broken
+  RakeTarget:
+    enabled: true
+    targets: ['test']
+    description: 'Run test suite'
+
+  # Check for potential security issues (if bundler-audit is available)
+  BundleAudit:
+    enabled: false  # Disabled by default, enable if you add bundler-audit gem
+
+  # Check for trailing whitespace
+  TrailingWhitespace:
+    enabled: true
+    exclude:
+      - '**/db/structure.sql' # Database dumps may have trailing whitespace
+      - '**/*.md'             # Markdown may intentionally have trailing spaces
+
+  # Check for merge conflict markers
+  MergeConflicts:
+    enabled: true
+
+  # Check YAML syntax
+  YamlSyntax:
+    enabled: true
+
+  # Check JSON syntax
+  JsonSyntax:
+    enabled: true
+
+  # Check for hard tabs (prefer spaces)
+  HardTabs:
+    enabled: true
+    exclude:
+      - '**/Makefile*'
+      - '**/*.mk'
+
+CommitMsg:
+  # Ensure commit messages are properly formatted
+  TextWidth:
+    enabled: true
+    max_subject_width: 60
+    max_body_width: 72
+
+PostCheckout:
+  # Bundle install when Gemfile changes
+  BundleCheck:
+    enabled: true
+
+PostMerge:
+  # Bundle install after merging changes to Gemfile
+  BundleCheck:
+    enabled: true
+
+PostRewrite:
+  # Bundle install after rebasing with Gemfile changes
+  BundleCheck:
+    enabled: true

data/.rubocop.yml

@@ -0,0 +1,167 @@
+plugins:
+  - rubocop-minitest
+
+AllCops:
+  TargetRubyVersion: 3.2
+  NewCops: enable
+  Exclude:
+    - 'vendor/**/*'
+    - 'bin/**/*'
+    - 'tmp/**/*'
+
+# Style Configuration to match existing project standards
+
+# Indentation: 2 spaces (matches existing code)
+Layout/IndentationWidth:
+  Width: 2
+
+# String quotes: prefer single quotes (matches existing code)
+Style/StringLiterals:
+  EnforcedStyle: single_quotes
+
+# Allow both single and double quotes in string interpolation contexts
+Style/StringLiteralsInInterpolation:
+  EnforcedStyle: double_quotes
+
+# Method definitions: allow no parentheses for no arguments (matches existing code)
+Style/DefWithParentheses:
+  Enabled: false
+
+# Method calls: allow no parentheses for no arguments (matches existing code)
+Style/MethodCallWithoutArgsParentheses:
+  Enabled: true
+
+# Hash syntax: prefer symbols (matches existing code)
+
+# Line length: be reasonable but not too strict for a Ruby gem
+Layout/LineLength:
+  Max: 120
+  AllowedPatterns: ['\A\s*#']
+  Exclude:
+    - '*.gemspec'
+    - 'test/**/*'
+
+# Documentation: don't require class/module documentation for this gem type
+Style/Documentation:
+  Enabled: false
+
+# Frozen string literal: don't enforce for compatibility
+Style/FrozenStringLiteralComment:
+  Enabled: false
+
+# Allow both proc and lambda
+Style/Lambda:
+  Enabled: false
+
+# Allow multiple assignment
+Style/ParallelAssignment:
+  Enabled: false
+
+# Allow guard clauses
+Style/GuardClause:
+  Enabled: true
+
+# Allow both if and unless modifiers
+Style/IfUnlessModifier:
+  Enabled: true
+
+# Method length: be reasonable for small gem
+Metrics/MethodLength:
+  Max: 25
+
+# Class length: be reasonable for small gem
+Metrics/ClassLength:
+  Max: 200
+
+# Module length: be reasonable for small gem
+Metrics/ModuleLength:
+  Max: 200
+
+# Block length: allow longer blocks for tests and configuration
+Metrics/BlockLength:
+  Max: 50
+  Exclude:
+    - 'test/**/*'
+    - '*.gemspec'
+    - 'Rakefile'
+
+# Allow both foo.empty? and foo.size == 0
+Style/ZeroLengthPredicate:
+  Enabled: false
+
+# Allow memoized variables with different names (e.g., @_sequelizer_db for @db)
+Naming/MemoizedInstanceVariableName:
+  Enabled: false
+
+# Allow short parameter names (common in Ruby for simple methods)
+Naming/MethodParameterName:
+  MinNameLength: 1
+
+# Allow multi-line block chains (common in Ruby data processing)
+Style/MultilineBlockChain:
+  Enabled: false
+
+# Relax complexity metrics for existing code
+Metrics/AbcSize:
+  Max: 35
+  Exclude:
+    - 'test/**/*'
+
+Metrics/CyclomaticComplexity:
+  Max: 15
+
+Metrics/PerceivedComplexity:
+  Max: 12
+
+Metrics/BlockNesting:
+  Max: 4
+
+# Allow set_ prefixed methods (common pattern)
+Naming/AccessorMethodName:
+  Enabled: false
+
+# Allow both string and symbol keys in same hash for configuration
+Style/HashSyntax:
+  EnforcedStyle: ruby19
+  EnforcedShorthandSyntax: either
+
+# Minitest specific rules
+Minitest/AssertEqual:
+  Enabled: true
+
+Minitest/RefuteEqual:
+  Enabled: true
+
+# Layout rules that match existing code
+Layout/EmptyLinesAroundClassBody:
+  EnforcedStyle: empty_lines_except_namespace
+
+Layout/EmptyLinesAroundModuleBody:
+  EnforcedStyle: empty_lines_except_namespace
+
+# Allow trailing commas in multiline structures
+Style/TrailingCommaInArguments:
+  EnforcedStyleForMultiline: comma
+
+Style/TrailingCommaInArrayLiteral:
+  EnforcedStyleForMultiline: comma
+
+Style/TrailingCommaInHashLiteral:
+  EnforcedStyleForMultiline: comma
+
+# Disable gemspec-specific rules that don't apply to this project
+Gemspec/DevelopmentDependencies:
+  Enabled: false
+
+# Disable some style rules for tests to allow more flexibility
+Style/HashLikeCase:
+  Exclude:
+    - 'test/**/*'
+
+Lint/DuplicateBranch:
+  Exclude:
+    - 'test/**/*'
+
+Style/StringConcatenation:
+  Exclude:
+    - 'test/**/*'

data/AGENTS.md

@@ -0,0 +1,126 @@
+# Agent Instructions
+
+This project uses **bd** (beads) for issue tracking. Run `bd onboard` to get started.
+
+## Quick Reference
+
+```bash
+bd ready              # Find available work
+bd show <id>          # View issue details
+bd update <id> --status in_progress  # Claim work
+bd close <id>         # Complete work
+bd sync               # Sync with git
+```
+
+<!-- BEGIN BEADS INTEGRATION -->
+## Issue Tracking with bd (beads)
+
+**IMPORTANT**: This project uses **bd (beads)** for ALL issue tracking. Do NOT use markdown TODOs, task lists, or other tracking methods.
+
+### Why bd?
+
+- Dependency-aware: Track blockers and relationships between issues
+- Git-friendly: Auto-syncs to JSONL for version control
+- Agent-optimized: JSON output, ready work detection, discovered-from links
+- Prevents duplicate tracking systems and confusion
+
+### Quick Start
+
+**Check for ready work:**
+
+```bash
+bd ready --json
+```
+
+**Create new issues:**
+
+```bash
+bd create "Issue title" --description="Detailed context" -t bug|feature|task -p 0-4 --json
+bd create "Issue title" --description="What this issue is about" -p 1 --deps discovered-from:bd-123 --json
+```
+
+**Claim and update:**
+
+```bash
+bd update bd-42 --status in_progress --json
+bd update bd-42 --priority 1 --json
+```
+
+**Complete work:**
+
+```bash
+bd close bd-42 --reason "Completed" --json
+```
+
+### Issue Types
+
+- `bug` - Something broken
+- `feature` - New functionality
+- `task` - Work item (tests, docs, refactoring)
+- `epic` - Large feature with subtasks
+- `chore` - Maintenance (dependencies, tooling)
+
+### Priorities
+
+- `0` - Critical (security, data loss, broken builds)
+- `1` - High (major features, important bugs)
+- `2` - Medium (default, nice-to-have)
+- `3` - Low (polish, optimization)
+- `4` - Backlog (future ideas)
+
+### Workflow for AI Agents
+
+1. **Check ready work**: `bd ready` shows unblocked issues
+2. **Claim your task**: `bd update <id> --status in_progress`
+3. **Work on it**: Implement, test, document
+4. **Discover new work?** Create linked issue:
+   - `bd create "Found bug" --description="Details about what was found" -p 1 --deps discovered-from:<parent-id>`
+5. **Complete**: `bd close <id> --reason "Done"`
+
+### Auto-Sync
+
+bd automatically syncs with git:
+
+- Exports to `.beads/issues.jsonl` after changes (5s debounce)
+- Imports from JSONL when newer (e.g., after `git pull`)
+- No manual export/import needed!
+
+### Important Rules
+
+- ✅ Use bd for ALL task tracking
+- ✅ Always use `--json` flag for programmatic use
+- ✅ Link discovered work with `discovered-from` dependencies
+- ✅ Check `bd ready` before asking "what should I work on?"
+- ❌ Do NOT create markdown TODO lists
+- ❌ Do NOT use external issue trackers
+- ❌ Do NOT duplicate tracking systems
+
+For more details, see README.md and docs/QUICKSTART.md.
+
+<!-- END BEADS INTEGRATION -->
+
+## Landing the Plane (Session Completion)
+
+**When ending a work session**, you MUST complete ALL steps below. Work is NOT complete until `git push` succeeds.
+
+**MANDATORY WORKFLOW:**
+
+1. **File issues for remaining work** - Create issues for anything that needs follow-up
+2. **Run quality gates** (if code changed) - Tests, linters, builds
+3. **Update issue status** - Close finished work, update in-progress items
+4. **PUSH TO REMOTE** - This is MANDATORY:
+   ```bash
+   git pull --rebase
+   bd sync
+   git push
+   git status  # MUST show "up to date with origin"
+   ```
+5. **Clean up** - Clear stashes, prune remote branches
+6. **Verify** - All changes committed AND pushed
+7. **Hand off** - Provide context for next session
+
+**CRITICAL RULES:**
+- Work is NOT complete until `git push` succeeds
+- NEVER stop before pushing - that leaves work stranded locally
+- NEVER say "ready to push when you are" - YOU must push
+- If push fails, resolve and retry until it succeeds

data/CHANGELOG.md

@@ -1,6 +1,47 @@
 # Changelog
+
 All notable changes to this project will be documented in this file.
 
+## 0.2.0
+
+### Added
+- funky Sequel extension for database-specific function abstraction
+- kvcsv as a runtime dependency
+- Platform configuration fixtures in config/platforms/
+
+### Changed
+- Broadened activesupport dependency from ~> 7.0 to >= 7, < 9
+- Broadened hashie dependency from ~> 3.2 to >= 3.2, < 6.0
+- Broadened dotenv dependency from ~> 2.1 to >= 2.1, < 4.0
+- Bumped sequel from 5.93.0 to 5.101.0
+- Added multi-Ruby CI matrix (3.2, 3.3, 3.4, 4.0) with separate lint job
+
+### Fixed
+- Adapter extraction from URL scheme for search_path processing
+
+## 0.1.6
+
+### Removed
+- JDBC adapter support (jdbc_hive2, jdbc_impala, jdbc_postgres) - not needed for foreseeable future
+- Native Impala adapter support - not needed for foreseeable future
+- Kerberos authentication functionality for enterprise databases
+- CGI dependency used for URL escaping in JDBC connections
+- 16 test methods related to JDBC and Impala adapters
+
+### Added
+- pg gem as development dependency to support PostgreSQL testing
+
+### Changed
+- Simplified ConnectionMaker class by removing adapter-specific configuration methods
+- Improved test coverage from 84.95% to 93.54% by removing unused code paths
+- Updated documentation to reflect focus on standard Sequel adapters
+
+## 0.1.5
+
+### Changed
+
+- Better handling of multiple directories of files for make_ready
+
 ## [0.1.0] - 2016-11-08
 
 ### Added

data/CLAUDE.md

@@ -0,0 +1,230 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+Sequelizer is a Ruby gem that simplifies database connections using Sequel. It allows users to configure database connections via config/database.yml or .env files, providing an easy-to-use interface for establishing database connections without hardcoding sensitive information.
+
+The gem includes:
+
+- A main module that provides `db` (cached connection) and `new_db` (fresh connection) methods
+- CLI commands for configuration management and Gemfile updating
+- Support for multiple database adapters including PostgreSQL, Impala, and Hive2
+- Sequel extensions for enhanced functionality
+
+## Development Commands
+
+### Testing
+
+```bash
+# Run all tests
+bundle exec rake test
+
+# Run tests with coverage report (generates coverage/index.html)
+bundle exec rake coverage
+
+# Run specific test file
+bundle exec ruby -I lib test/lib/sequelizer/test_connection_maker.rb
+```
+
+### Linting and Formatting
+
+```bash
+# Check code style and lint issues
+bundle exec rake lint
+bundle exec rubocop
+
+# Auto-fix safe linting issues  
+bundle exec rake lint_fix
+bundle exec rubocop --auto-correct
+
+# Auto-fix all issues (including unsafe corrections)
+bundle exec rake format
+bundle exec rubocop --auto-correct-all
+
+# Run linter on specific files
+bundle exec rubocop lib/sequelizer.rb
+```
+
+### Pre-commit Hooks
+
+```bash
+# Install pre-commit hooks (done automatically after bundle install)
+bundle exec overcommit --install
+
+# Sign configuration (if you modify .overcommit.yml)
+bundle exec overcommit --sign
+
+# Run pre-commit hooks manually
+bundle exec overcommit --run
+
+# Skip hooks for a specific commit (use sparingly)
+git commit --no-verify -m "commit message"
+```
+
+The pre-commit hooks automatically run:
+
+- RuboCop linting with auto-correction
+- Full test suite
+- YAML/JSON syntax validation
+- Trailing whitespace and merge conflict checks
+- Commit message formatting validation
+
+### Build and Release
+
+```bash
+# Build gem
+bundle exec rake build
+
+# Release gem
+bundle exec rake release
+```
+
+### CLI Commands
+
+```bash
+# Show current configuration
+bundle exec sequelizer config
+
+# Update Gemfile with database adapter
+bundle exec sequelizer update_gemfile
+
+# Initialize .env file
+bundle exec sequelizer init_env --adapter postgres --host localhost --database mydb
+```
+
+## Architecture
+
+### Core Components
+
+- **Sequelizer module** (`lib/sequelizer.rb`): Main interface providing `db` and `new_db` methods
+- **ConnectionMaker** (`lib/sequelizer/connection_maker.rb`): Handles database connection logic and adapter-specific configurations
+- **Options** (`lib/sequelizer/options.rb`): Manages configuration from multiple sources with precedence order
+- **CLI** (`lib/sequelizer/cli.rb`): Thor-based command line interface
+
+### Configuration Sources (in precedence order)
+
+1. Passed options
+2. .env file
+3. Environment variables
+4. config/database.yml
+5. ~/.config/sequelizer/database.yml
+
+### Sequel Extensions
+
+Located in `lib/sequel/extensions/`:
+
+- **db_opts**: Database-specific options handling
+- **make_readyable**: Readiness checking functionality
+- **settable**: Dynamic property setting
+- **sqls**: SQL statement management
+- **usable**: Connection usability features
+
+### Database Support
+
+The gem supports various database adapters with special handling for:
+
+- PostgreSQL (including search_path/schema management)
+- JDBC-based connections (Hive2, Impala, PostgreSQL)
+- Kerberos authentication for enterprise databases
+
+### Test Structure
+
+- Tests use Minitest framework
+- Located in `test/` directory with subdirectories mirroring `lib/` structure
+- Helper utilities in `test_helper.rb` including constant stubbing for testing
+
+## Coding Standards
+
+This project follows standard Ruby community conventions enforced by RuboCop, emphasizing readability, consistency, and Ruby idioms.
+
+### Style Conventions
+
+**Indentation & Formatting:**
+
+- 2-space indentation (no tabs)
+- Single-line method definitions when appropriate: `def e(v)`
+- Method parameters without parentheses when no arguments: `def connection`
+- Method parameters with parentheses when there are arguments: `def initialize(options = nil)`
+
+**Naming:**
+
+- Module/Class names: PascalCase (`Sequelizer`, `ConnectionMaker`)
+- Method names: snake_case (`new_db`, `find_cached`, `after_connect`)
+- Variable names: snake_case (`sequelizer_options`, `db_config`)
+- Instance variables: snake_case with `@` prefix (`@options`, `@_sequelizer_db`)
+- Constants: SCREAMING_SNAKE_CASE (`VERSION`)
+
+**Strings:**
+
+- Single quotes for simple strings: `'postgres'`, `'mock'`
+- Double quotes for interpolation: `"SET #{key}=#{value}"`
+
+### Code Organization
+
+**File Structure:**
+
+- One main class/module per file
+- Nested modules follow directory structure: `lib/sequelizer/connection_maker.rb`
+- Private methods grouped at bottom with `private` keyword
+
+**Dependencies:**
+
+- Use `require_relative` for internal dependencies: `require_relative 'sequelizer/version'`
+- Use `require` for external gems: `require 'sequel'`, `require 'thor'`
+- Group requires at top of files
+
+### Documentation
+
+**Comments:**
+
+- Use `#` for single-line comments
+- Extensive method documentation with parameter descriptions
+- Minimal inline comments, used for clarification of complex logic
+
+### Ruby Idioms
+
+**Patterns Used:**
+
+- Memoization: `@_sequelizer_db ||= new_db(options)`
+- Conditional assignment: `||=` for defaults
+- Metaprogramming with `define_method` for dynamic method creation
+- Symbol keys in hashes: `{ adapter: 'postgres' }`
+- Method chaining kept readable
+
+**Testing Patterns:**
+
+- Test methods prefixed with `test_`: `def test_accepts_options_as_params`
+- Extensive use of stubbing and mocking for isolated testing
+- Custom helper methods for common setup patterns
+
+## Ruby Sequel as Lodestone
+
+- Refer frequently to GitHub's jeremyevans/sequel repository for:
+  - Examples of great documenation
+  - Good code organization
+  - Great commit messages
+  - Wonderful changelog messages
+
+## Platform Abstraction Project (In Planning)
+
+There is a separate, planned evolution of this gem documented in `oimnibus/projects/in-development/sequelizer/` with 31 ADRs. That project would add a `Platform` object to `Sequel::Database` instances with `supports_*?`/`prefers_*?` methods for abstracting RDBMS-specific behavior across Postgres, Spark, Athena, and Snowflake. **This is NOT yet implemented in this gem** — the current gem is DB-connection-only. The platform abstraction is entirely in planning documents.
+
+## Agent Rules
+
+1. **NEVER skip, hide, or conditionally disable tests to avoid failures.** If a test fails because a dependency is missing, add the dependency. If a test fails because fixture data is missing, create the fixtures. Wrapping a `require` in `rescue LoadError` and returning early is just as bad as deleting the test. Fix the root cause.
+2. **NEVER exclude files from coverage to dodge SimpleCov thresholds.** If coverage is low because tests aren't running, make the tests run.
+3. **Always test locally across all supported Ruby versions before pushing.** Use `MISE_RUBY_VERSION=X.Y mise exec -- bundle exec rake test` for each version in the CI matrix (3.2, 3.3, 3.4, 4.0).
+4. **Run both `bundle exec rubocop` and `bundle exec rake test` before every push.** No exceptions.
+
+## Development Memories
+
+- Ensure that bundler is used for all ruby/rake related cli invocations
+- Read-only operations (exploration, testing) can be done in main directory
+- Refer to Ruby Sequel for code style, test frameworks, and general guidance
+- To test CLI, just call bundle exec bin/sequelizer without installing binstubs
+- **IMPORTANT**: Commands like `docker build`, `devcontainer build`, and `bundle install` can take more than 10 minutes to complete and should be run with extended timeout (e.g., 20 minutes / 1200000ms)
+- **Wait for explicit instructions before reading files or creating plans - do not be proactive**
+- When pushing to github or making pull requests, remember you have a PAT in GITHUB_TOKEN you can use for authentication
+- When making a pull request, push to the "github" remote

data/Gemfile

@@ -3,6 +3,10 @@ source 'https://rubygems.org'
 # Specify your gem's dependencies in sequelizer.gemspec
 gemspec
 
+group :development do
+  gem 'overcommit', '~> 0.68'
+end
+
 group :test do
-  gem "sequel-hexspace", github: "outcomesinsights/sequel-hexspace", branch: "master"
-end
+  gem 'sequel-hexspace', github: 'outcomesinsights/sequel-hexspace', branch: 'master'
+end