pgdice 0.2.0 → 0.2.1
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +4 -4
- data/CHANGELOG.md +8 -9
- data/README.md +49 -43
- data/lib/pgdice/partition_manager.rb +1 -1
- data/lib/pgdice/version.rb +1 -1
- metadata +1 -1
checksums.yaml
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
---
|
2
2
|
SHA256:
|
3
|
-
metadata.gz:
|
4
|
-
data.tar.gz:
|
3
|
+
metadata.gz: f3fb2d5818d5b0042ad5509989c68728bc4cf308a6776d2e4e86f098e54f0eca
|
4
|
+
data.tar.gz: 878e00f3882170077962bbd486164f529ffe03cfb3a90a3c82fbb93ad4f91062
|
5
5
|
SHA512:
|
6
|
-
metadata.gz:
|
7
|
-
data.tar.gz:
|
6
|
+
metadata.gz: 391d851ca34559bae050ce7a3e4ea5d980fa85c215438252c08842af2d409535170e14951538d665168851260cf182a2705901682b5adad9b9b30928d054e49d
|
7
|
+
data.tar.gz: bab98688c55400ff18ea5f94a0fc29ad94752c13fa5fcf410a058c71c4c82bcb588df0ccf97f1bc1447e9e59f4d9877ffff00ef2aea67c016a66a2fa8995979a
|
data/CHANGELOG.md
CHANGED
@@ -2,13 +2,12 @@
|
|
2
2
|
All notable changes to this project will be documented in this file.
|
3
3
|
This project adheres to [Semantic Versioning](http://semver.org/).
|
4
4
|
|
5
|
-
## [v0.2.0] : 2018-09-17
|
6
|
-
### Changelog added
|
7
5
|
|
8
|
-
|
9
|
-
|
10
|
-
|
11
|
-
|
12
|
-
|
13
|
-
|
14
|
-
|
6
|
+
## [v0.2.1] : 2018-10-21
|
7
|
+
### Changes
|
8
|
+
- Renamed `PartitionManager.list_batched_droppable_partitions` to
|
9
|
+
`PartitionManager.list_droppable_partitions_by_batch_size`
|
10
|
+
- Readme updated
|
11
|
+
|
12
|
+
## [v0.2.0] : 2018-10-21
|
13
|
+
- Changelog added
|
data/README.md
CHANGED
@@ -25,7 +25,7 @@ maintainers and any affiliated parties CANNOT BE HELD LIABLE FOR DATA LOSS OR LO
|
|
25
25
|
See the [LICENSE](LICENSE) for more information.
|
26
26
|
|
27
27
|
|
28
|
-
|
28
|
+
# Installation
|
29
29
|
|
30
30
|
Add this line to your application's Gemfile:
|
31
31
|
|
@@ -41,9 +41,9 @@ Or install it yourself as:
|
|
41
41
|
|
42
42
|
$ gem install pgdice
|
43
43
|
|
44
|
-
|
44
|
+
# Usage
|
45
45
|
|
46
|
-
|
46
|
+
## Configuration
|
47
47
|
|
48
48
|
You must configure `PgDice` before you can use it, otherwise you won't be able to perform any manipulation actions
|
49
49
|
on tables.
|
@@ -67,7 +67,7 @@ end
|
|
67
67
|
```
|
68
68
|
|
69
69
|
|
70
|
-
|
70
|
+
### Configuration Parameters
|
71
71
|
|
72
72
|
- `database_url` - Required: The postgres database url to connect to.
|
73
73
|
- This is required since `pgslice` requires a postgres `url`.
|
@@ -80,14 +80,16 @@ end
|
|
80
80
|
- See the [Approved Tables Configuration](#approved-tables-configuration) section for more.
|
81
81
|
|
82
82
|
- `dry_run` - Optional: Boolean value to control whether changes are executed on the database.
|
83
|
-
-
|
84
|
-
|
83
|
+
- Defaults to `false`
|
84
|
+
- `true` will make PgDice log out the commands but not execute them.
|
85
85
|
|
86
86
|
- `batch_size` - Optional: Maximum number of tables you can drop in one `drop_old_partitions` call.
|
87
87
|
- Defaults to 7.
|
88
|
+
- Keep in mind the size of your tables, drop operations are done in one command. Large tables
|
89
|
+
will take longer to drop per table and could time out if there is activity on the parent table.
|
88
90
|
|
89
91
|
|
90
|
-
|
92
|
+
### Advanced Configuration Parameters
|
91
93
|
|
92
94
|
All of the following parameters are optional and honestly you probably will never need to mess with these.
|
93
95
|
|
@@ -97,7 +99,7 @@ All of the following parameters are optional and honestly you probably will neve
|
|
97
99
|
so this feature may not be very useful if you are trying to only use one connection for this utility.
|
98
100
|
|
99
101
|
|
100
|
-
|
102
|
+
## Approved Tables Configuration
|
101
103
|
|
102
104
|
In order to maintain the correct number of partitions over time you must configure a
|
103
105
|
[PgDice::Table](lib/pgdice/table.rb).
|
@@ -105,7 +107,7 @@ In order to maintain the correct number of partitions over time you must configu
|
|
105
107
|
An example configuration file has been provided at [config.yml](examples/config.yml) if you would rather
|
106
108
|
declare your `approved_tables` in yaml.
|
107
109
|
|
108
|
-
|
110
|
+
### Alternative Approved Tables Configuration
|
109
111
|
|
110
112
|
If you want to declare your [PgDice::ApprovedTables](lib/pgdice/approved_tables.rb) in your configuration
|
111
113
|
block instead, you can build them like so:
|
@@ -128,7 +130,7 @@ end
|
|
128
130
|
It is possible to use both the configuration block and a file if you so choose.
|
129
131
|
The block will take precedence over the values in the file.
|
130
132
|
|
131
|
-
|
133
|
+
## Converting existing tables to partitioned tables
|
132
134
|
|
133
135
|
__This should only be used on smallish tables and ONLY after you have tested it on a non-production copy of your
|
134
136
|
production database.__
|
@@ -136,7 +138,8 @@ In fact, you should just not do this in production. Schedule downtime or somethi
|
|
136
138
|
a copy of your database. Then practice restoring your database some more.
|
137
139
|
|
138
140
|
|
139
|
-
This command will convert
|
141
|
+
This command will convert the existing `comments` table into 98 partitioned tables
|
142
|
+
(90 past, 7 future, and one for today).
|
140
143
|
|
141
144
|
For more information on what's going on in the background see
|
142
145
|
[https://github.com/ankane/pgslice](https://github.com/ankane/pgslice)
|
@@ -146,30 +149,27 @@ For more information on what's going on in the background see
|
|
146
149
|
PgDice.partition_helper.partition_table('comments')
|
147
150
|
```
|
148
151
|
|
149
|
-
If you mess up (again you shouldn't use this in production). These two methods are useful for writing tests
|
150
|
-
that work with partitions.
|
151
152
|
|
152
|
-
|
153
|
+
### Notes on partition_table
|
153
154
|
|
154
155
|
- You can override values configured in the `PgDice::Table` by passing them in as a hash.
|
155
156
|
- For example if you wanted to create `30` future tables instead of the configured `7` for the `comments` table
|
156
157
|
you could pass in `future: 30`.
|
157
158
|
|
159
|
+
|
160
|
+
If you mess up, again you shouldn't use this in production, you can call:
|
161
|
+
|
158
162
|
```ruby
|
159
163
|
PgDice.partition_helper.undo_partitioning!('comments')
|
160
164
|
```
|
161
165
|
|
162
|
-
|
163
|
-
|
164
|
-
- In `partition_helper` there are versions of the methods that will throw exceptions (ending in `!`) and others
|
165
|
-
that will return a truthy value or `false` if there is a failure.
|
166
|
+
This method will revert the changes made by partitioning a table. Don't rely on this
|
167
|
+
in production if you mess up; you need to test everything thoroughly.
|
166
168
|
|
167
|
-
- `period` can be set to one of these values: `:day`, `:month`, `:year`
|
168
169
|
|
170
|
+
## Maintaining partitioned tables
|
169
171
|
|
170
|
-
###
|
171
|
-
|
172
|
-
#### Adding more tables
|
172
|
+
### Adding more tables
|
173
173
|
|
174
174
|
If you have existing tables that need to periodically have more tables added you can run:
|
175
175
|
|
@@ -177,14 +177,14 @@ If you have existing tables that need to periodically have more tables added you
|
|
177
177
|
PgDice.partition_manager.add_new_partitions('comments')
|
178
178
|
```
|
179
179
|
|
180
|
-
|
180
|
+
#### Notes on `add_new_partitions`
|
181
181
|
|
182
|
-
- The above command would add `7` new tables and their associated indexes all based on the `period`
|
183
|
-
partitioned table was defined with.
|
184
|
-
|
182
|
+
- The above command would add up to `7` new tables and their associated indexes all based on the `period`
|
183
|
+
that the partitioned table was defined with.
|
184
|
+
- The example `comments` table we have been using was configured to always keep `7` future partitions above.
|
185
185
|
|
186
186
|
|
187
|
-
|
187
|
+
### Listing droppable partitions
|
188
188
|
|
189
189
|
Sometimes you just want to know what's out there and if there are tables ready to be dropped.
|
190
190
|
|
@@ -193,12 +193,20 @@ To list all eligible tables for dropping you can run:
|
|
193
193
|
PgDice.partition_manager.list_droppable_partitions('comments')
|
194
194
|
```
|
195
195
|
|
196
|
-
|
196
|
+
If you want to know _exactly_ which partitions will be dropped you can call:
|
197
|
+
```ruby
|
198
|
+
PgDice.partition_manager.list_droppable_partitions_by_batch_size('comments')
|
199
|
+
```
|
200
|
+
|
201
|
+
This method will show partitions that are within the configured `batch_size`.
|
197
202
|
|
198
|
-
- This method uses the `past` value from the `PgDice::Table` to determine which tables are eligible for dropping.
|
199
203
|
|
204
|
+
#### Notes on `list_droppable_partitions`
|
205
|
+
|
206
|
+
- This method uses the `past` value from the `PgDice::Table` to determine which tables are eligible for dropping.
|
207
|
+
- Like most commands, if you want to override the values it will use to check just pass them in.
|
200
208
|
|
201
|
-
|
209
|
+
### Dropping old tables
|
202
210
|
|
203
211
|
_Dropping tables is irreversible! Do this at your own risk!!_
|
204
212
|
|
@@ -208,7 +216,7 @@ If you want to drop old tables (after backing them up of course) you can run:
|
|
208
216
|
PgDice.partition_manager.drop_old_partitions(table_name: 'comments')
|
209
217
|
```
|
210
218
|
|
211
|
-
|
219
|
+
#### Notes on `drop_old_partitions`
|
212
220
|
|
213
221
|
- The above example command would drop partitions that exceed the configured `past` table count
|
214
222
|
for the `PgDice::Table`.
|
@@ -216,24 +224,23 @@ for the `PgDice::Table`.
|
|
216
224
|
So if there were 100 tables older than `today` it would drop up to `batch_size` tables.
|
217
225
|
|
218
226
|
|
219
|
-
|
227
|
+
# Validation
|
220
228
|
|
221
229
|
If you've got background jobs creating and dropping tables you're going to want to
|
222
230
|
ensure they are actually working correctly.
|
223
231
|
|
224
232
|
To validate that your expected number of tables exist, you can run:
|
225
233
|
```ruby
|
226
|
-
PgDice.validation.assert_tables('comments'
|
234
|
+
PgDice.validation.assert_tables('comments')
|
227
235
|
```
|
228
236
|
|
229
237
|
An [InsufficientTablesError](lib/pgdice.rb) will be raised if any conditions are not met.
|
230
238
|
|
231
|
-
This will check that
|
232
|
-
|
233
|
-
by day.
|
239
|
+
This will check that there are 7 future tables from now and that there are 90 past tables
|
240
|
+
per our configuration above.
|
234
241
|
|
235
242
|
|
236
|
-
|
243
|
+
# FAQ
|
237
244
|
|
238
245
|
1. How do I get a postgres url if I'm running in Rails?
|
239
246
|
```ruby
|
@@ -255,11 +262,10 @@ end
|
|
255
262
|
## Planned Features
|
256
263
|
|
257
264
|
1. Full `PG::Connection` support (no more database URLs).
|
258
|
-
1.
|
259
|
-
1. Non time-range based partitioning.
|
265
|
+
1. Non time-range based partitioning. [PgParty](https://github.com/rkrage/pg_party) might be a good option!
|
260
266
|
|
261
267
|
|
262
|
-
|
268
|
+
# Development
|
263
269
|
|
264
270
|
After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests.
|
265
271
|
You can also run `bin/console` for an interactive prompt that will allow you to experiment.
|
@@ -267,7 +273,7 @@ You can also run `bin/console` for an interactive prompt that will allow you to
|
|
267
273
|
To install this gem onto your local machine, run `bundle exec rake install`.
|
268
274
|
|
269
275
|
|
270
|
-
|
276
|
+
## Running tests
|
271
277
|
|
272
278
|
You're going to need to have postgres 10 or greater installed.
|
273
279
|
|
@@ -286,12 +292,12 @@ to be a safe, welcoming space for collaboration, and contributors are expected t
|
|
286
292
|
the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
|
287
293
|
|
288
294
|
|
289
|
-
|
295
|
+
# License
|
290
296
|
|
291
297
|
The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
|
292
298
|
|
293
299
|
|
294
|
-
|
300
|
+
# Code of Conduct
|
295
301
|
|
296
302
|
Everyone interacting in the Pgdice project’s codebases, issue trackers, chat rooms and mailing lists is expected
|
297
303
|
to follow the [code of conduct](https://github.com/IlluminusLimited/pgdice/blob/master/CODE_OF_CONDUCT.md).
|
@@ -49,7 +49,7 @@ module PgDice
|
|
49
49
|
droppable_partitions(all_params)
|
50
50
|
end
|
51
51
|
|
52
|
-
def
|
52
|
+
def list_droppable_partitions_by_batch_size(table_name, params = {})
|
53
53
|
all_params = approved_tables.smash(table_name, params)
|
54
54
|
validation.validate_parameters(all_params)
|
55
55
|
droppable_tables = batched_droppable_partitions(all_params)
|
data/lib/pgdice/version.rb
CHANGED