Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/yegor256/pgtk
PostgreSQL ToolKit for Ruby apps: Liquibase + Rake + Connection Pool
https://github.com/yegor256/pgtk
connection-pool liquibase postgresql rake-task rakefile ruby
Last synced: about 2 months ago
JSON representation
PostgreSQL ToolKit for Ruby apps: Liquibase + Rake + Connection Pool
- Host: GitHub
- URL: https://github.com/yegor256/pgtk
- Owner: yegor256
- License: mit
- Created: 2019-04-14T15:49:45.000Z (over 5 years ago)
- Default Branch: master
- Last Pushed: 2024-05-22T10:38:17.000Z (7 months ago)
- Last Synced: 2024-05-22T23:37:59.917Z (7 months ago)
- Topics: connection-pool, liquibase, postgresql, rake-task, rakefile, ruby
- Language: Ruby
- Homepage: https://rubygems.org/gems/pgtk
- Size: 160 KB
- Stars: 7
- Watchers: 4
- Forks: 1
- Open Issues: 7
-
Metadata Files:
- Readme: README.md
- License: LICENSE.txt
Awesome Lists containing this project
README
# Ruby + PostgreSQL + Liquibase + Rake
[](https://www.elegantobjects.org)
[](http://www.rultor.com/p/yegor256/pgtk)
[](https://www.jetbrains.com/ruby/)
[](https://github.com/yegor256/pgtk/actions/workflows/rake.yml)
[](http://www.0pdd.com/p?name=yegor256/pgtk)
[](http://badge.fury.io/rb/pgtk)
[](https://codeclimate.com/github/yegor256/pgtk/maintainability)
[](https://github.com/yegor256/pgtk/blob/master/LICENSE.txt)
[](https://codecov.io/github/yegor256/pgtk?branch=master)
[](https://hitsofcode.com/view/github/yegor256/pgtk)
This small Ruby gem helps you integrate
[PostgreSQL](https://www.postgresql.org/) with your Ruby
web app, through [Liquibase](https://www.liquibase.org/).
It also adds a simple connection pool
and query processor, to make SQL manipulation simpler.
First of all, on top of
[Ruby](https://www.ruby-lang.org/en/) and
[Bundler](https://bundler.io/)
you need to have
[PostgreSQL](https://www.postgresql.org/),
[Java 8+](https://java.com/en/download/), and
[Maven 3.2+](https://maven.apache.org/) installed.
In Ubuntu 16+ this should be enough:
```bash
sudo apt-get install -y postgresql-10 postgresql-client-10
sudo apt-get install -y default-jre maven
```
Then, add this to your [`Gemfile`](https://bundler.io/gemfile.html):
```ruby
gem 'pgtk'
```
Then, add this to your
[`Rakefile`](https://github.com/ruby/rake/blob/master/doc/rakefile.rdoc):
```ruby
require 'pgtk/pgsql_task'
Pgtk::PgsqlTask.new :pgsql do |t|
t.dir = 'target/pgsql' # Temp directory with PostgreSQL files
t.fresh_start = true # To delete the directory on every start
t.user = 'test'
t.password = 'test'
t.dbname = 'test'
t.yaml = 'target/pgsql-config.yml' # YAML file to be created with connection details
end
```
And this too
([org.postgresql:postgresql][plugin-1]
and [org.liquibase:liquibase-maven-plugin][plugin-2]
are used inside):
```ruby
require 'pgtk/liquibase_task'
Pgtk::LiquibaseTask.new liquibase: :pgsql do |t|
t.master = 'liquibase/master.xml' # Master XML file path
t.yaml = ['target/pgsql-config.yml', 'config.yml'] # YAML files with connection details
t.quiet = false # TRUE by default
t.postgresql_version = '42.7.0' # overwriting default version
t.liquibase_version = '3.2.2' # overwriting default version
end
```
The config.yml file should be in this format:
```yaml
pgsql:
url: jdbc:postgresql://:/?user=
host: ...
port: ...
dbname: ...
user: ...
password: ...
```
You should create that `liquibase/master.xml` file in your repository,
and a number of other XML files with Liquibase changes. This
[example](https://github.com/zold-io/wts.zold.io/tree/master/liquibase)
will help you understand them.
Now, you can do this:
```bash
bundle exec rake pgsql liquibase
```
A temporary PostgreSQL server will be started and the entire set of
Liquibase SQL changes will be applied. You will be able to connect
to it from your application, using the file `target/config.yml`.
From inside your app you may find this class useful:
```ruby
require 'pgtk/pool'
pgsql = Pgtk::Pool.new(Pgtk::Wire::Yaml.new('config.yml'))
pgsql.start(5) # Start it with five simultaneous connections
```
You can also let it pick the connection parameters from the environment
variable `DATABASE_URL`, formatted like
`postgres://user:password@host:5432/dbname`:
```ruby
pgsql = Pgtk::Pool.new(Pgtk::Wire::Env.new)
```
Now you can fetch some data from the DB:
```ruby
name = pgsql.exec('SELECT name FROM user WHERE id = $1', [id])[0]['name']
```
You may also use it if you need to run a transaction:
```ruby
pgsql.transaction do |t|
t.exec('DELETE FROM user WHERE id = $1', [id])
t.exec('INSERT INTO user (name, phone) VALUES ($1, $2)', [name, phone])
end
```
To make your PostgreSQL database visible in your unit test, I would
recommend you create a method `test_pgsql` in your `test__helper.rb` file
(which is `required` in all unit tests) and implement it like this:
```ruby
require 'yaml'
require 'minitest/autorun'
require 'pgtk/pool'
module Minitest
class Test
def test_pgsql
config = YAML.load_file()
@@test_pgsql ||= Pgtk::Pool.new(
Pgtk::Wire::Yaml.new('target/pgsql-config.yml')
).start
end
end
end
```
Should work.
Well, it works in
[netbout.com](https://github.com/yegor256/netbout),
[wts.zold.io](https://github.com/zold-io/wts.zold.io),
[mailanes.com](https://github.com/yegor256/mailanes), and
[0rsk.com](https://github.com/yegor256/0rsk).
They are all open source, you can see how they use `pgtk`.
## How to contribute
Read
[these guidelines](https://www.yegor256.com/2014/04/15/github-guidelines.html).
Make sure your build is green before you contribute
your pull request. You will need to have
[Ruby](https://www.ruby-lang.org/en/) 2.3+ and
[Bundler](https://bundler.io/) installed. Then:
```bash
bundle update
bundle exec rake
```
If it's clean and you don't see any error messages, submit your pull request.
To run a single test, do this:
```bash
bundle exec ruby test/test_pool.rb -n test_basic
```
[plugin-1]: https://mvnrepository.com/artifact/org.postgresql/postgresql
[plugin-2]: https://mvnrepository.com/artifact/org.liquibase/liquibase-maven-plugin