pg-ephemeral 0.2.2

Ephemeral PostgreSQL instances for testing
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144

# 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.

## 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+