jackcess-rb 0.1.0-java

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 13808690cb806345d019bc40fbf8dbb4f26219b2671a33df8f8f490b86c02adc
+  data.tar.gz: fe077ca9129c8b22667f5bebc20da22da3312e9e06c4f7be54db368bc6398afc
+SHA512:
+  metadata.gz: d68146bdbbb184ff3b10a854c760abb0cf2d854de97d6a8873837cb16e7d64895c488f7416f1f39e9377748869c3dfee8bbc86aa6d6b70fd2e8b55bb97b29607
+  data.tar.gz: ffae044f60f706949828e838065d319f797be6e1ee32644c8db9921df99ac1f8a2969330998270c95247dd7c790bdcfe0d0df82040e4cfedb968337a7e04fe21

data/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-02-12
+
+### Added
+- Initial release
+- Support for opening and creating Access databases (.mdb and .accdb)
+- CRUD operations on tables and rows
+- Schema inspection (tables, columns, indexes)
+- Type conversion between Java and Ruby types
+- Idiomatic Ruby API wrapping Jackcess Java library
+- Comprehensive test suite
+- Documentation and examples

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Durable Programming LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,435 @@
+# jackcess-rb
+
+A JRuby interface to the Jackcess library for reading and writing Microsoft Access databases.
+
+jackcess-rb provides a Ruby-friendly interface to the powerful [Jackcess](https://jackcess.healthmarketscience.com/) Java library, enabling programmatic interaction with Access database files (`.mdb` and `.accdb`) directly from JRuby. This gem is designed with Durable Programming principles: pragmatic solutions, sustainability, quality, and customer-centric development.
+
+## Features
+
+- **Pure JRuby**: No native dependencies—runs on any platform with JRuby
+- **Read and Write Access Databases**: Full support for both `.mdb` (Jet) and `.accdb` (ACE) formats
+- **Idiomatic Ruby API**: Natural Ruby interface wrapping Jackcess's Java API
+- **Table Operations**: Create, read, update, and delete tables and records
+- **Schema Inspection**: Examine database structure, columns, indexes, and relationships
+- **Type Safety**: Automatic conversion between Java and Ruby types
+
+## Quick Start
+
+```ruby
+require 'jackcess'
+
+# Open an existing database
+db = Jackcess::Database.open('path/to/database.accdb')
+
+# Read from a table
+table = db.table('Customers')
+table.each do |row|
+  puts "#{row['FirstName']} #{row['LastName']}"
+end
+
+# Add a new row
+table.add_row(
+  'FirstName' => 'Alice',
+  'LastName' => 'Smith',
+  'Email' => 'alice@example.com'
+)
+
+# Close the database
+db.close
+```
+
+## Installation
+
+### Requirements
+
+- **JRuby 9.3+**: This gem requires JRuby and will not run on MRI Ruby
+- **Java 8+**: Jackcess requires Java 8 or higher
+
+Verify your JRuby installation:
+
+```bash
+jruby --version
+# Expected: jruby 9.3.x (or higher)
+```
+
+### Install via Bundler (Recommended)
+
+Add to your `Gemfile`:
+
+```ruby
+gem 'jackcess-rb'
+```
+
+Then run:
+
+```bash
+bundle install
+```
+
+### Install via gem
+
+```bash
+gem install jackcess-rb
+```
+
+## Usage
+
+### Opening and Closing Databases
+
+```ruby
+require 'jackcess'
+
+# Open an existing database
+db = Jackcess::Database.open('data/northwind.accdb')
+
+# Work with the database
+# ...
+
+# Always close when done
+db.close
+
+# Or use block form for automatic cleanup
+Jackcess::Database.open('data/northwind.accdb') do |db|
+  # Database automatically closed when block exits
+end
+```
+
+### Reading Data
+
+```ruby
+# Access a table
+table = db.table('Products')
+
+# Iterate through all rows
+table.each do |row|
+  puts "Product: #{row['ProductName']}, Price: #{row['UnitPrice']}"
+end
+
+# Get specific row by ID
+row = table.find_by_id(42)
+
+# Access column values
+name = row['ProductName']
+price = row['UnitPrice']
+```
+
+### Writing Data
+
+```ruby
+table = db.table('Products')
+
+# Add a new row
+table.add_row(
+  'ProductName' => 'Widget',
+  'UnitPrice' => 19.99,
+  'UnitsInStock' => 100
+)
+
+# Update an existing row
+row = table.find_by_id(42)
+row['UnitPrice'] = 24.99
+row.save
+
+# Delete a row
+row.delete
+```
+
+### Creating Tables
+
+```ruby
+# Create a new table with columns
+db.create_table('Orders') do |t|
+  t.column 'OrderID', :long, auto_number: true
+  t.column 'CustomerID', :long
+  t.column 'OrderDate', :date_time
+  t.column 'ShipAddress', :text, length: 255
+  t.column 'Total', :double
+
+  t.primary_key 'OrderID'
+end
+```
+
+### Schema Inspection
+
+```ruby
+# List all tables
+db.table_names.each do |name|
+  puts "Table: #{name}"
+end
+
+# Inspect table structure
+table = db.table('Customers')
+
+puts "Columns:"
+table.columns.each do |col|
+  puts "  #{col.name} (#{col.type})"
+end
+
+puts "Indexes:"
+table.indexes.each do |idx|
+  puts "  #{idx.name}: #{idx.columns.join(', ')}"
+end
+```
+
+### Transaction Management
+
+```ruby
+# Explicit transaction control
+db.transaction do
+  table = db.table('Accounts')
+
+  from_account = table.find_by_id(1)
+  to_account = table.find_by_id(2)
+
+  from_account['Balance'] -= 100
+  to_account['Balance'] += 100
+
+  from_account.save
+  to_account.save
+
+  # Automatically committed if no exception
+  # Automatically rolled back on exception
+end
+```
+
+## API Documentation
+
+### `Jackcess::Database`
+
+Main entry point for database operations.
+
+#### Class Methods
+
+- `Database.open(path, options = {})` → `Database`
+  - Opens an existing database file
+  - Options:
+    - `:readonly` (Boolean): Open in read-only mode (default: `false`)
+    - `:auto_sync` (Boolean): Auto-sync changes to disk (default: `true`)
+  - Returns: `Database` instance
+  - Block form: Automatically closes database when block exits
+
+- `Database.create(path, format = :v2000)` → `Database`
+  - Creates a new database file
+  - Formats: `:v2000` (.mdb), `:v2003` (.mdb), `:v2007` (.accdb), `:v2010` (.accdb)
+
+#### Instance Methods
+
+- `#table(name)` → `Table`
+  - Access a table by name
+
+- `#table_names` → `Array<String>`
+  - Returns array of all table names
+
+- `#create_table(name, &block)` → `Table`
+  - Create a new table with schema defined in block
+
+- `#close`
+  - Close the database connection
+
+### `Jackcess::Table`
+
+Represents a table in the database.
+
+#### Instance Methods
+
+- `#each(&block)` → `Enumerator`
+  - Iterate through all rows
+
+- `#find_by_id(id)` → `Row`
+  - Find row by primary key value
+
+- `#add_row(data)` → `Row`
+  - Add a new row with given data (Hash)
+
+- `#columns` → `Array<Column>`
+  - Returns array of column definitions
+
+- `#indexes` → `Array<Index>`
+  - Returns array of indexes
+
+### `Jackcess::Row`
+
+Represents a single row/record in a table.
+
+#### Instance Methods
+
+- `#[](column_name)` → `Object`
+  - Get column value
+
+- `#[]=(column_name, value)`
+  - Set column value
+
+- `#save`
+  - Save changes to the database
+
+- `#delete`
+  - Delete this row from the table
+
+See [API Documentation](https://rubydoc.info/gems/jackcess-rb) for complete reference.
+
+## Type Mapping
+
+jackcess-rb automatically converts between Access/Java types and Ruby types:
+
+| Access Type | Ruby Type | Notes |
+|-------------|-----------|-------|
+| TEXT | String | Variable length text |
+| MEMO | String | Long text fields |
+| BYTE | Integer | 8-bit integer |
+| INT | Integer | 16-bit integer |
+| LONG | Integer | 32-bit integer |
+| FLOAT | Float | Single precision |
+| DOUBLE | Float | Double precision |
+| CURRENCY | BigDecimal | Fixed-point decimal |
+| DATE_TIME | Time | Date and time |
+| BOOLEAN | Boolean | true/false |
+| BINARY | String (binary) | Binary data |
+| GUID | String | UUID/GUID strings |
+
+## Design Principles
+
+jackcess-rb is built following Durable Programming principles:
+
+### Pragmatic Problem-Solving
+
+- Solves real-world need: accessing Access databases without Windows
+- Focuses on common use cases first
+- Provides escape hatches to underlying Jackcess API when needed
+- No unnecessary abstractions—just enough Ruby idioms for comfort
+
+### Sustainability and Longevity
+
+- Built on mature, well-maintained Jackcess library
+- Minimal dependencies (JRuby + Jackcess only)
+- Clear separation between Ruby API and Java interop
+- Designed for long-term maintenance
+
+### Quality and Reliability
+
+- Comprehensive test coverage
+- Type-safe conversions between Ruby and Java
+- Proper resource management (automatic cleanup)
+- Error handling with meaningful messages
+
+### Customer-Centric
+
+- Developer experience prioritized
+- Idiomatic Ruby API
+- Clear documentation with practical examples
+- Progressive disclosure: simple things simple, complex things possible
+
+### Transparency
+
+- Open source (MIT license)
+- Clear documentation of capabilities and limitations
+- Honest about JRuby requirement
+- Links to underlying Jackcess documentation
+
+## Architecture
+
+jackcess-rb provides a thin Ruby wrapper around the Jackcess Java library:
+
+```
+┌─────────────────────────────────────┐
+│   Ruby Application Code             │
+├─────────────────────────────────────┤
+│   jackcess-rb (Ruby API)            │
+│   - Idiomatic Ruby interface        │
+│   - Type conversions                │
+│   - Resource management             │
+├─────────────────────────────────────┤
+│   JRuby Bridge                      │
+├─────────────────────────────────────┤
+│   Jackcess Java Library             │
+│   - Access file format handling     │
+│   - Database operations             │
+├─────────────────────────────────────┤
+│   Access Database Files             │
+│   (.mdb, .accdb)                    │
+└─────────────────────────────────────┘
+```
+
+The gem focuses on:
+- Ruby-friendly method names and conventions
+- Automatic type conversions
+- Block-based resource management
+- Iterator patterns for large datasets
+
+## Performance Considerations
+
+- **Memory**: Large tables are iterated lazily—only current row in memory
+- **Transactions**: Batch operations in transactions for better performance
+- **Indexes**: Use indexed columns for lookups when possible
+- **File Format**: `.accdb` (v2007+) generally faster than `.mdb` for large databases
+
+## Limitations
+
+- **JRuby Only**: This gem requires JRuby and will not work with MRI Ruby
+- **File-Based**: Jackcess works with Access files directly, not via ODBC/ADO
+- **Access Features**: Some advanced Access features (forms, reports, VBA) are not accessible
+- **Concurrent Access**: Limited support for multiple processes accessing same file simultaneously
+
+## Contributing
+
+We welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for:
+- Development setup
+- Running tests
+- Code style guidelines
+- Pull request process
+
+## Testing
+
+```bash
+# Run the test suite
+bundle exec rake test
+
+# Run specific test file
+bundle exec ruby test/database_test.rb
+```
+
+## Troubleshooting
+
+### "Java::JavaLang::UnsupportedClassVersionError"
+
+Your Java version is too old. Jackcess requires Java 8+.
+
+```bash
+java -version
+# Should show 1.8.0 or higher
+```
+
+### "Cannot find Java library 'jackcess'"
+
+The Jackcess JAR is missing. Reinstall the gem:
+
+```bash
+gem uninstall jackcess-rb
+gem install jackcess-rb
+```
+
+### "Database format not supported"
+
+The Access file format may be too old or corrupted. Try:
+- Opening in Access and saving as newer format (.accdb)
+- Using Access's "Compact and Repair Database" feature
+
+## License
+
+[MIT License](LICENSE)
+
+## Support
+
+- **Documentation**: [https://rubydoc.info/gems/jackcess-rb](https://rubydoc.info/gems/jackcess-rb)
+- **Issues**: [GitHub Issues](https://github.com/durableprogramming/jackcess-rb/issues)
+- **Jackcess Documentation**: [https://jackcess.healthmarketscience.com/](https://jackcess.healthmarketscience.com/)
+- **Email**: commercial@durableprogramming.com
+
+## Credits
+
+jackcess-rb is developed by [Durable Programming LLC](https://durableprogramming.com).
+
+Built on the [Jackcess](https://jackcess.healthmarketscience.com/) library by Health Market Science.
+
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md) for version history and release notes.

data/lib/jackcess/column.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Jackcess
+  class Column
+    attr_reader :java_column
+
+    def initialize(java_column)
+      @java_column = java_column
+    end
+
+    # Get column name
+    def name
+      @java_column.get_name
+    end
+
+    # Get column type as Ruby symbol
+    def type
+      TypeConverter.data_type_to_ruby_type(@java_column.get_type)
+    end
+
+    # Get column SQL type
+    def sql_type
+      @java_column.get_sql_type
+    end
+
+    # Get column length
+    def length
+      @java_column.get_length
+    end
+
+    # Check if column is auto-number
+    def auto_number?
+      @java_column.is_auto_number
+    end
+
+    # Check if column is variable length
+    def variable_length?
+      @java_column.is_variable_length
+    end
+
+    # Get column properties
+    def properties
+      {
+        name: name,
+        type: type,
+        sql_type: sql_type,
+        length: length,
+        auto_number: auto_number?,
+        variable_length: variable_length?
+      }
+    end
+
+    def inspect
+      "#<Jackcess::Column name=#{name.inspect} type=#{type.inspect}>"
+    end
+
+    def to_s
+      "#{name} (#{type})"
+    end
+  end
+end