README.md in grumlin-1.0.0.rc7 vs README.md in grumlin-1.0.0
- old
+ new
@@ -1,8 +1,8 @@
# Grumlin
-[](https://github.com/zhulik/grumlin/actions/workflows/main.yml)
+[](https://github.com/babbel/grumlin/actions/workflows/main.yml)
[](https://github.com/RichardLitt/standard-readme)
[](https://lbesson.mit-license.org/)
Grumlin is a [Gremlin](https://tinkerpop.apache.org/gremlin.html) graph traversal language DSL and client for Ruby.
Suitable for and tested with [gremlin-server](http://tinkerpop.apache.org/) and [AWS Neptune](https://aws.amazon.com/neptune/).
@@ -284,10 +284,58 @@
#### IRB
Please check out [bin/console](bin/console) for inspiration. A similar trick may be applied to PRY.
+Then you need to reference it in your application.rb:
+```ruby
+config.console = MyRailsConsole
+```
+
+#### Testing
+
+Grumlin provides a couple of helpers to simplify testing code written with it.
+
+##### RSpec
+
+Make sure you have [async-rspec](https://github.com/socketry/async-rspec) installed.
+
+`spec_helper.rb` or `rails_helper.rb`:
+```ruby
+require 'async/rspec'
+require require "grumlin/test/rspec"
+...
+config.include_context(Async::RSpec::Reactor) # Runs async reactor
+config.include_context(Grumlin::Test::RSpec::GremlinContext) # Injects `g`, `__` and expressions, makes sure client is closed after every test
+config.include_context(Grumlin::Test::RSpec::DBCleanerContext) # Cleans the database before every test
+...
+```
+
+It is highly recommended to use `Grumlin::Repository` and not trying to use lower level APIs as they are subject to
+change.
+
+#### Using in a web app
+
+As previously mentioned, `Grumlin` is built on top of the [async stack](https://github.com/socketry/async).
+This basically means you'd either have to use [Falcon](https://github.com/socketry/falcon) as you application server,
+or you'd need to wrap every place where you use `Grumlin` into an `Async` block:
+
+```ruby
+Async do
+ MyGrumlinRepository.some_query
+ensure
+ Grumlin.close
+end
+```
+
+`Falcon` is preferred because it can keep connections to your Gremlin server open between requests. The only downside
+is that `ActiveRecord` currently does not play well with ruby's fiber scheduler so far, and it can block the event loop.
+When using `Falcon` you don't need explicit `Async` blocks.
+
+Currently it's not recommended to use `ActiveRecord` with `Falcon`. If you still need access to a SQL database from your app,
+consider using [socketry/db](https://github.com/socketry/db)
+
#### Rails console
In order to make it possible to execute gremlin queries from the rails console you need to define
a custom console class. It should look somewhat like
@@ -323,37 +371,18 @@
inspect
end
end
```
-Then you need to reference it in your application.rb:
-```ruby
-config.console = MyRailsConsole
-```
+#### AWS Neptune
-#### Testing
+See [docs/neptune.md](./docs/neptune.md)
-Grumlin provides a couple of helpers to simplify testing code written with it.
+#### Sidekiq
-##### RSpec
+See [docs/neptune.md](./docs/sidekiq.md)
-Make sure you have [async-rspec](https://github.com/socketry/async-rspec) installed.
-
-`spec_helper.rb` or `rails_helper.rb`:
-```ruby
-require 'async/rspec'
-require require "grumlin/test/rspec"
-...
-config.include_context(Async::RSpec::Reactor) # Runs async reactor
-config.include_context(Grumlin::Test::RSpec::GremlinContext) # Injects `g`, `__` and expressions, makes sure client is closed after every test
-config.include_context(Grumlin::Test::RSpec::DBCleanerContext) # Cleans the database before every test
-...
-```
-
-It is highly recommended to use `Grumlin::Repository` and not trying to use lower level APIs as they are subject to
-change.
-
## Development
Before running tests make sure you have gremlin-server running on your computer. The simplest way to run it is using
[docker-compose](https://docs.docker.com/compose/) and provided `docker-compose.yml` and `gremlin_server/Dockerfile`:
@@ -370,12 +399,12 @@
To add a new step or an expression simple put it to the corresponding list in [definitions.yml](lib/definitions.yml)
and run `rake definitions:format`. You don't need to properly sort the lists manually, the rake task will do it for you.
## Contributing
-Bug reports and pull requests are welcome on GitHub at https://github.com/zhulik/grumlin. This project is intended to
+Bug reports and pull requests are welcome on GitHub at https://github.com/babbel/grumlin. 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/zhulik/grumlin/blob/master/CODE_OF_CONDUCT.md).
+[code of conduct](https://github.com/babbel/grumlin/blob/master/CODE_OF_CONDUCT.md).
## License
The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).