diff --git a/.gitignore b/.gitignore index ae81709..de8603f 100644 --- a/.gitignore +++ b/.gitignore @@ -11,4 +11,6 @@ .rspec_status log/ -vendor \ No newline at end of file +vendor +db/ +.DS_Store diff --git a/Gemfile.lock b/Gemfile.lock index 08e0c3d..f3d12d5 100644 --- a/Gemfile.lock +++ b/Gemfile.lock @@ -1,36 +1,71 @@ PATH remote: . specs: - activerecord-duckdb-adapter (0.1.0) - activerecord - duckdb + activerecord-duckdb-adapter (0.2.0) + activerecord (~> 7.1) + duckdb (~> 1.1) GEM remote: https://rubygems.org/ specs: - activemodel (7.0.2.3) - activesupport (= 7.0.2.3) - activerecord (7.0.2.3) - activemodel (= 7.0.2.3) - activesupport (= 7.0.2.3) - activesupport (7.0.2.3) - concurrent-ruby (~> 1.0, >= 1.0.2) + activemodel (7.2.1.1) + activesupport (= 7.2.1.1) + activerecord (7.2.1.1) + activemodel (= 7.2.1.1) + activesupport (= 7.2.1.1) + timeout (>= 0.4.0) + activesupport (7.2.1.1) + base64 + bigdecimal + concurrent-ruby (~> 1.0, >= 1.3.1) + connection_pool (>= 2.2.5) + drb i18n (>= 1.6, < 2) + logger (>= 1.4.2) minitest (>= 5.1) - tzinfo (~> 2.0) - concurrent-ruby (1.1.10) - duckdb (0.3.2.0) - i18n (1.10.0) + securerandom (>= 0.3) + tzinfo (~> 2.0, >= 2.0.5) + base64 (0.2.0) + bigdecimal (3.2.2) + concurrent-ruby (1.3.4) + connection_pool (2.4.1) + diff-lcs (1.6.2) + drb (2.2.1) + duckdb (1.3.0.0) + bigdecimal (>= 3.1.4) + i18n (1.14.6) concurrent-ruby (~> 1.0) - minitest (5.15.0) - tzinfo (2.0.4) + logger (1.6.1) + minitest (5.25.1) + rake (13.2.1) + rspec (3.13.1) + rspec-core (~> 3.13.0) + rspec-expectations (~> 3.13.0) + rspec-mocks (~> 3.13.0) + rspec-core (3.13.4) + rspec-support (~> 3.13.0) + rspec-expectations (3.13.5) + diff-lcs (>= 1.2.0, < 2.0) + rspec-support (~> 3.13.0) + rspec-mocks (3.13.5) + diff-lcs (>= 1.2.0, < 2.0) + rspec-support (~> 3.13.0) + rspec-support (3.13.4) + securerandom (0.3.1) + timeout (0.4.1) + tzinfo (2.0.6) concurrent-ruby (~> 1.0) PLATFORMS arm64-darwin-20 + arm64-darwin-23 + x86_64-linux DEPENDENCIES activerecord-duckdb-adapter! + bundler (~> 2.0) + rake (~> 13.0) + rspec (~> 3.13) BUNDLED WITH - 2.2.22 + 2.5.22 diff --git a/README.md b/README.md index aa1d0a4..bf03e61 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,12 @@ Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/activerecord/duckdb/adapter`. To experiment with that code, run `bin/console` for an interactive prompt. -TODO: Delete this and the text above, and describe your gem + +## Overview + +DuckDB is an embeddable SQL OLAP database used analytical workloads, data science applications, and situations where you need fast analytical queries without the overhead of a separate database server. This adapter allows you to use DuckDB with ActiveRecord and Rails applications. + +The adapter now defaults to **file-based databases** for data persistence, while still supporting in-memory databases as well. ## Installation @@ -20,19 +25,72 @@ Or install it yourself as: $ gem install activerecord-duckdb-adapter +## Dependencies + +This adapter depends on: +- [ruby-duckdb](https://github.com/suketa/ruby-duckdb) - Ruby bindings for DuckDB +- ActiveRecord 7.0+ + ## Usage -TODO: Write usage instructions here +### Basic Configuration + +In your `database.yml`: + +```yaml +development: + adapter: duckdb + # File-based database (default) + database: db/development.duckdb + + # For in-memory database (useful for testing) + # database: ":memory:" +``` + +### Establishing Connection + +```ruby +ActiveRecord::Base.establish_connection( + adapter: 'duckdb', + database: 'db/my_app.duckdb' # or ':memory:' for in-memory database +) +``` + ## Development -After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment. +After checking out the repo, run: + +```bash +bin/setup +``` + +To run the test suite: + +```bash +bundle exec rake test +``` + + +To experiment with the adapter: + +```bash +bin/console +``` + + + +## References +- [ruby-duckdb](https://github.com/suketa/ruby-duckdb): The underlying Ruby DuckDB driver (actively maintained) +- [DuckDB Documentation](https://duckdb.org/docs/) +- [ActiveRecord Adapter Development](https://web.archive.org/web/20230326213337/https://eng.localytics.com/odbc-and-writing-your-own-activerecord-adapter/) +- [Rails Database Adapter Registration](https://github.com/rails/rails/commit/009c7e74117690f0dbe200188a929b345c9306c1) +- [Arel Query Building](https://www.cloudbees.com/blog/creating-advanced-active-record-db-queries-arel) -To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org). ## Contributing -Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/activerecord-duckdb-adapter. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/[USERNAME]/activerecord-duckdb-adapter/blob/master/CODE_OF_CONDUCT.md). +Bug reports and pull requests are welcome on GitHub at https://github.com/red-data-tools/activerecord-duckdb-adapter. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/[USERNAME]/activerecord-duckdb-adapter/blob/master/CODE_OF_CONDUCT.md). ## License @@ -40,4 +98,4 @@ The gem is available as open source under the terms of the [MIT License](https:/ ## Code of Conduct -Everyone interacting in the Activerecord::Duckdb::Adapter project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/[USERNAME]/activerecord-duckdb-adapter/blob/master/CODE_OF_CONDUCT.md). +Everyone interacting in the Activerecord::Duckdb::Adapter project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/red-data-tools/activerecord-duckdb-adapter/blob/master/CODE_OF_CONDUCT.md).