pg-ephemeral 0.2.2-aarch64-linux → 0.2.3-aarch64-linux

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 247530b9babf7e4766d8f58091f88b626ac92d939c70c842eeca6ee6956e7f84
-  data.tar.gz: 8a67754dfc39828b2017ec6b67e71067eeb61443f50b7a91632ceda70279f775
+  metadata.gz: 30827d60bff661ffab35406253c1154ab6d2a9cc3a8b845e2fbde4aabaad33e3
+  data.tar.gz: 413fc8d945038b6848d8d80d0536e8a272cdf3a101dc2436b3f6fa8738e51e0c
 SHA512:
-  metadata.gz: 8859521e992c50c14710b680b2aa8b1605c74c5ca4afb32f6f894f277959b48e4bef37f280b81362fcf3b737a38913e518e47908efd93347e4cbc80d02d32348
-  data.tar.gz: 2efc222be64eef6654a82f4e5011b7cee8f75be747c80f19b6fba9c0e88b0153e69f4be643f7d5cc67a73aa162f7b7b6306de95efa599389433dc589abcca9a5
+  metadata.gz: f36ca8fbad77763cf4ff64990a19cae7e0445bddcdbb43e59fd592916cd6be4284e814421714d2ab780e14bf233c08b5d366ca905562dfe8f2ff9768e7a346b0
+  data.tar.gz: 730edec285df9579c9865567c6d87fb7ee1ae1e475717d8cefae771bf793f60a61b622a096d69daecfba11fb720c9ac23069dea5e5f0a6b6a4f27045df27a620

data/README.md

@@ -0,0 +1,146 @@
+# pg-ephemeral Ruby Gem
+
+Ruby wrapper for [pg-ephemeral](https://github.com/mbj/mrs/tree/main/pg-ephemeral). Bundles the platform-specific binary
+and provides a native API for ephemeral PostgreSQL instances.
+
+Published on RubyGems: [pg-ephemeral](https://rubygems.org/gems/pg-ephemeral)
+
+## Installation
+
+```ruby
+gem 'pg-ephemeral'
+```
+
+The gem ships with prebuilt binaries for `x86_64-linux`, `aarch64-linux`, and `arm64-darwin`.
+
+## Usage
+
+### Direct connection
+
+```ruby
+PgEphemeral.with_connection do |conn|
+  conn.exec("SELECT 1 AS value")
+end
+```
+
+`with_connection` yields a `PG::Connection` and closes it after the block.
+
+### Server handle
+
+```ruby
+PgEphemeral.with_server do |server|
+  puts server.url  # => "postgres://postgres:...@127.0.0.1:54321/postgres"
+end
+```
+
+`with_server` yields a `Server` with a `.url` accessor. The container shuts down
+after the block.
+
+### Options
+
+Both `with_connection` and `with_server` accept:
+
+| Option          | Description                                      | Default    |
+|-----------------|--------------------------------------------------|------------|
+| `instance_name` | Target instance from `database.toml`             | `"main"`   |
+| `config`        | Path to a `database.toml` config file            | auto-detect |
+
+```ruby
+PgEphemeral.with_connection(instance_name: "analytics", config: "path/to/database.toml") do |conn|
+  conn.exec("SELECT 1")
+end
+```
+
+### Manual lifecycle
+
+For cases where the block form doesn't fit:
+
+```ruby
+server = PgEphemeral.start
+connection = PG.connect(server.url)
+# ...
+connection.close
+server.shutdown
+```
+
+### Utilities
+
+```ruby
+PgEphemeral.version             # => "0.2.0"
+PgEphemeral.platform_supported? # => true
+PgEphemeral.binary_path         # => "/path/to/pg-ephemeral"
+```
+
+## Test Framework Integration
+
+### RSpec
+
+```ruby
+RSpec.describe UserRepository do
+  before(:all) do
+    @server = PgEphemeral.start
+    @connection = PG.connect(@server.url)
+  end
+
+  after(:all) do
+    @connection.close
+    @server.shutdown
+  end
+
+  it 'inserts a user' do
+    @connection.exec("INSERT INTO users (name) VALUES ('alice')")
+    result = @connection.exec("SELECT name FROM users")
+    expect(result.first['name']).to eq('alice')
+  end
+end
+```
+
+### Rails
+
+Configure pg-ephemeral in `spec/support/pg_ephemeral.rb` so ActiveRecord
+connects to the ephemeral instance:
+
+```ruby
+RSpec.configure do |config|
+  config.before(:suite) do
+    @server = PgEphemeral.start
+    ENV['DATABASE_URL'] = @server.url
+    ActiveRecord::Base.establish_connection
+  end
+
+  config.after(:suite) do
+    @server.shutdown
+  end
+end
+```
+
+Schema and seed data are applied via `database.toml` seeds, so the database
+is ready before the suite starts.
+
+### Minitest
+
+```ruby
+# test/test_helper.rb
+SERVER = PgEphemeral.start
+CONNECTION = PG.connect(SERVER.url)
+
+Minitest.after_run do
+  CONNECTION.close
+  SERVER.shutdown
+end
+```
+
+```ruby
+class UserRepositoryTest < Minitest::Test
+  def test_inserts_a_user
+    CONNECTION.exec("INSERT INTO users (name) VALUES ('alice')")
+    result = CONNECTION.exec("SELECT name FROM users")
+    assert_equal 'alice', result.first['name']
+  end
+end
+```
+
+## Requirements
+
+- Ruby >= 3.3
+- Docker Engine 20.10+ / Docker Desktop 4.34+, or Podman 5.3+

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pg-ephemeral
 version: !ruby/object:Gem::Version
-  version: 0.2.2
+  version: 0.2.3
 platform: aarch64-linux
 authors:
 - Markus Schirp
@@ -32,6 +32,7 @@ extensions: []
 extra_rdoc_files: []
 files:
 - LICENSE.txt
+- README.md
 - bin/pg-ephemeral
 - lib/pg_ephemeral.rb
 homepage: https://github.com/mbj/mrs/tree/main/pg-ephemeral