Add a bit more documentation, and add the Optimize::DEFAULT constant

Author: flavorjones

CHANGELOG.md

@@ -1,5 +1,12 @@
 # sqlite3-ruby Changelog
 
+## next / unreleased
+
+### Added
+
+- `Database#optimize` which wraps the `pragma optimize;` statement. Also added `Constants::Optimize` to allow advanced users to pass a bitmask of options. See https://www.sqlite.org/pragma.html#pragma_optimize. [#572] @alexcwatt @flavorjones
+
+
 ## 2.2.0 / 2024-10-30
 
 ### Added

lib/sqlite3/constants.rb

@@ -172,19 +172,27 @@ module Status
     end
 
     module Optimize
-      # Debugging mode. Do not actually perform any optimizations but instead return one line of text
-      # for each optimization that would have been done.
+      # Debugging mode. Do not actually perform any optimizations but instead return one line of
+      # text for each optimization that would have been done. Off by default.
       DEBUG = 0x00001
 
-      # Run ANALYZE on tables that might benefit.
+      # Run ANALYZE on tables that might benefit. On by default.
       ANALYZE_TABLES = 0x00002
 
-      # When running ANALYZE, set a temporary PRAGMA analysis_limit to prevent excess run-time.
+      # When running ANALYZE, set a temporary PRAGMA analysis_limit to prevent excess run-time. On
+      # by default.
       LIMIT_ANALYZE = 0x00010
 
       # Check the size of all tables, not just tables that have not been recently used, to see if
-      # any have grown and shrunk significantly and hence might benefit from being re-analyzed.
+      # any have grown and shrunk significantly and hence might benefit from being re-analyzed. Off
+      # by default.
       CHECK_ALL_TABLES = 0x10000
+
+      # Useful for adding a bit to the default behavior, for example
+      #
+      #     db.optimize(Optimize::DEFAULT | Optimize::CHECK_ALL_TABLES)
+      #
+      DEFAULT = ANALYZE_TABLES | LIMIT_ANALYZE
     end
   end
 end

lib/sqlite3/pragmas.rb

@@ -342,6 +342,8 @@ def mmap_size=(size)
     #
     # To customize the optimization options, pass +bitmask+ with a combination
     # of the Constants::Optimize masks.
+    #
+    # See https://www.sqlite.org/pragma.html#pragma_optimize for more information.
     def optimize(bitmask = nil)
       if bitmask
         set_int_pragma "optimize", bitmask