schema-evolution-manager 0.9.74 → 0.9.75

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 547c6eb4a33514444b83da617c79fecfff22ffe1afbb1133853525ac119a603f
-  data.tar.gz: 5ea3f1f9e021af98a52fae4a02ddd26cd978b5eb2e08c8698f39e02f003610fc
+  metadata.gz: ab56a47b14bfc595e3cdad6ba15edef70ea02b50dbdb1c4b43a72e832937ca20
+  data.tar.gz: d035c43de9a7e0de1d12ff1f95fcc9acde7fdf0916b2827f5f1bbb604c317260
 SHA512:
-  metadata.gz: 66660ad71948a70a7da979229af57e8a2da0c0934658adc4d24c0c4287039607257a37ff9ceacae82216611279e8667f09761fb213448deb3ee3297a8043d638
-  data.tar.gz: 2aec0f7a2c10ffe7a3d7725de4f9825df921b173bd98f85f95d004569ae24fa102ae879031097462774d6fce05a06b733c4870bc01e7fa2917bd52ad7a8678f5
+  metadata.gz: 6f1eb21b2c631d38a38806274f2f7e87d6ad15e74f28b742842a3a746a3e0c2ecf4e4e517fd2494c61fbc15c9d2b3f7917fd13d201778d1b129147e909f27200
+  data.tar.gz: 3c24490ba5ee1e285c8e28dbb36cb79f0a441f9a9d9efa02ff3cca8f3027ed2d64b0356033826e4e0b99db0ef73a00c907afa2b4e812f560817d6a4945b0bc01

data/README.md

@@ -149,7 +149,7 @@ There are three ways to install schema evolution manager:
 
         git clone git@github.com:mbryzek/schema-evolution-manager.git
         cd schema-evolution-manager
-        git checkout 0.9.74
+        git checkout 0.9.75
         ruby ./configure.rb
         sudo ./install.rb
 
@@ -244,7 +244,13 @@ deploy process.
 
     sem-apply --url postgresql://postgres@localhost/sample --dry_run
 
-You will likely see a number of create table statements (see data model section below). You should also see:
+A dry run writes nothing to the database: not your scripts, and not sem's own
+schema either. On a database sem has not yet installed itself in, it lists the
+bootstrap scripts that would create that schema (see data model section below):
+
+      [DRY RUN] Bootstrapping 20130318-105434.sql
+
+You should also see:
 
       [DRY RUN] Applying 20130318-214407.sql
 
@@ -259,7 +265,7 @@ There are two recommended ways in which to pass user passwords to psql:
     file](http://www.postgresql.org/docs/9.4/static/libpq-pgpass.html)
     with the appropriate credentials</li>
 
- 2. Specify a [--password] flag when running sem-apply. You will
+ 2. Specify a [--password] flag when running sem-apply or sem-baseline. You will
     then be prompted to enter your password once. sem will create a
     temporary file to store your password, using that file during the
     duration of the command and ensuring the file is deleted after sem

data/bin/sem-add

@@ -13,12 +13,11 @@ load File.join(File.dirname(__FILE__), 'sem-config')
 
 file = ARGV.shift
 if file.to_s.strip == ""
-  puts "**** ERROR: Need file path"
-  SchemaEvolutionManager::RdocUsage.printAndExit(1)
+  SchemaEvolutionManager::RdocUsage.error!("Missing file path", SchemaEvolutionManager::RdocUsage::MISSING_INPUT, :usage => true)
 end
 
 SchemaEvolutionManager::Preconditions.check_state(File.exist?(file), "File[#{file}] could not be found")
-SchemaEvolutionManager::Preconditions.check_state(file.match(/\.sql/i), "File[#{file}] must end with .sql")
+SchemaEvolutionManager::Preconditions.check_state(file.match?(/\.sql\z/i), "File[#{file}] must end with .sql")
 
 scripts_dir = SchemaEvolutionManager::Config.load.scripts_dir
 SchemaEvolutionManager::Library.ensure_dir!(scripts_dir)

data/bin/sem-apply

@@ -15,20 +15,14 @@ require 'tempfile'
 
 load File.join(File.dirname(__FILE__), 'sem-config')
 
-args = SchemaEvolutionManager::Args.from_stdin(:optional => %w(url host port name user dry_run password set))
-
-password = if args.password
-             SchemaEvolutionManager::Ask.for_password("Please enter your password: ")
-           else
-             nil
-           end
+args = SchemaEvolutionManager::Args.from_stdin(:optional => SchemaEvolutionManager::Db::CONNECTION_FLAGS + %w(dry_run password))
+db = SchemaEvolutionManager::Db.from_command_line(args)
 
 config = SchemaEvolutionManager::Config.load
-db = SchemaEvolutionManager::Db.from_args(args, :password => password)
 util = SchemaEvolutionManager::ApplyUtil.new(db, :dry_run => args.dry_run || false)
 
 begin
-  db.bootstrap!
+  db.bootstrap!(:dry_run => util.dry_run?)
 
   puts "Upgrading schema for #{db.sanitized_url}"
   count = util.apply!(config.scripts_dir)
@@ -59,7 +53,11 @@ rescue SchemaEvolutionManager::ScriptError => e
   end
 
   puts ""
-  puts "If this script has previously been applied to this database, you can record it as having been applied by:"
+  if e.applied?
+    puts "This script was applied, but recording it as applied failed. Record it before the next apply, which would otherwise run it again:"
+  else
+    puts "If this script has previously been applied to this database, you can record it as having been applied by:"
+  end
   puts "  " + e.dml
   puts ""
   exit(1)

data/bin/sem-baseline

@@ -1,5 +1,5 @@
 #!/usr/bin/env ruby
-# == Makes sure that sem is bootstapped, and then adds all existing scripts to the sem-database without applying
+# == Makes sure that sem is bootstrapped, and then adds all existing scripts to the sem-database without applying
 #    Useful for migration to sem
 #
 # == Usage
@@ -9,19 +9,19 @@
 #
 # == Examples
 #  sem-baseline --url postgresql://postgres@localhost/sample
-#  sem-apply --host localhost --user web --name test
+#  sem-baseline --host localhost --user web --name test
 #
 
 
 load File.join(File.dirname(__FILE__), 'sem-config')
 
-args = SchemaEvolutionManager::Args.from_stdin(:optional => %w(url host port name user dry_run))
+args = SchemaEvolutionManager::Args.from_stdin(:optional => SchemaEvolutionManager::Db::CONNECTION_FLAGS + %w(dry_run password))
+db = SchemaEvolutionManager::Db.from_command_line(args)
 
 config = SchemaEvolutionManager::Config.load
-db = SchemaEvolutionManager::Db.from_args(args)
-db.bootstrap!
 
 dry_run = args.dry_run.nil? ? false : args.dry_run
+db.bootstrap!(:dry_run => dry_run)
 
 util = SchemaEvolutionManager::BaselineUtil.new(db, :dry_run => dry_run)
 

data/bin/sem-info

@@ -29,6 +29,13 @@
 #   libraries. Initially designed to help with wrapper scripts that
 #   needed information (like the next minor tag)
 #
+# Exit status
+#
+#   Errors go to stderr only, so stdout holds nothing but the answer.
+#   1: the command failed (e.g. the database could not be read)
+#   3: missing input (a command, subcommand, tag or connection)
+#   4: invalid input (an unrecognized value or a malformed --url)
+#
 
 load File.join(File.dirname(__FILE__), 'sem-config')
 
@@ -43,10 +50,9 @@ elsif command == "db"
 elsif command == "version"
   puts SchemaEvolutionManager::SemInfo.version(ARGV)
 
+elsif command == ""
+  SchemaEvolutionManager::RdocUsage.error!("Missing command", SchemaEvolutionManager::RdocUsage::MISSING_INPUT, :usage => true)
+
 else
-  if command != ""
-    puts "ERROR: Unrecognized command[%s]" % command
-    puts ""
-  end
-  SchemaEvolutionManager::RdocUsage.printAndExit(1)
+  SchemaEvolutionManager::RdocUsage.error!("Unrecognized command[%s]" % command, SchemaEvolutionManager::RdocUsage::INVALID_INPUT, :usage => true)
 end

data/bin/sem-init

@@ -21,15 +21,9 @@
 load File.join(File.dirname(__FILE__), 'sem-config')
 SchemaEvolutionManager::Library.set_verbose(true)
 
-args = SchemaEvolutionManager::Args.from_stdin(:required => %w(dir), :optional => %w(url host port name user scripts_dir))
+args = SchemaEvolutionManager::Args.from_stdin(:required => %w(dir), :optional => SchemaEvolutionManager::Db::CONNECTION_FLAGS + %w(scripts_dir))
 SchemaEvolutionManager::Preconditions.check_state(File.directory?(args.dir), "Dir[%s] does not exist" % args.dir)
-
-if args.url.nil? && args.name.nil?
-  puts "Must specify either url or name"
-  exit(1)
-end
-
-db = SchemaEvolutionManager::Db.from_args(args)
+db = SchemaEvolutionManager::Db.from_command_line(args)
 
 def copy_file(source, target, substitutions)
   template = SchemaEvolutionManager::Template.new
@@ -72,14 +66,6 @@ Dir.chdir(args.dir) do
     SchemaEvolutionManager::Library.system_or_error(["git", "commit", "-m", "Add schema-evolution-manager wrapper scripts", "--"] + wrappers)
   end
 
-  readme = "README.md"
-  if !File.exist?(readme)
-    puts "Creating #{readme}"
-    copy_file("schema-evolution-manager/template/README.md", "README.md", subs)
-    SchemaEvolutionManager::Library.system_or_error(["git", "add", "--", readme])
-    SchemaEvolutionManager::Library.system_or_error(["git", "commit", "-m", "Adding README.md", "--", readme])
-  end
-
   if args.scripts_dir
     config_file = SchemaEvolutionManager::Config::FILENAME
     if File.exist?(config_file)
@@ -104,8 +90,7 @@ Dir.chdir(args.dir) do
   end
 
   # Create the first git tag if necessary
-  tags = SchemaEvolutionManager::Library.system_or_error(["git", "tag", "-l"])
-  if tags.nil? || tags == ""
+  if SchemaEvolutionManager::Library.git_tags.empty?
     puts "Creating initial git tag (0.0.1)"
     SchemaEvolutionManager::Library.git_create_tag("0.0.1")
   end

data/lib/schema-evolution-manager/apply_util.rb

@@ -1,41 +1,15 @@
 module SchemaEvolutionManager
 
-  class ApplyUtil
+  # Runs each pending script and records it as run.
+  class ApplyUtil < PendingScriptsUtil
 
-    def initialize(db, opts={})
-      @dry_run = opts.delete(:dry_run)
-      if @dry_run.nil?
-        @dry_run = true
-      end
-
-      @db = Preconditions.assert_class(db, Db)
-      @scripts = Scripts.new(@db, Scripts::SCRIPTS)
-    end
-
-    def dry_run?
-      @dry_run
+    private
+    def label
+      "Applying"
     end
 
-    # Applies scripts in order, returning number of scripts applied
-    def apply!(dir)
-      Preconditions.check_state(File.directory?(dir),
-                                "Dir[%s] does not exist" % dir)
-
-      count = 0
-      @scripts.each_pending(dir) do |filename, path|
-        count += 1
-        if @dry_run
-          puts "[DRY RUN] Applying #{filename}"
-          puts path
-          puts ""
-        else
-          print "Applying #{filename}"
-          @db.psql_file(filename, path)
-          @scripts.record_as_run!(filename)
-          puts " Done"
-        end
-      end
-      count
+    def execute?
+      true
     end
 
   end

data/lib/schema-evolution-manager/args.rb

@@ -61,6 +61,10 @@ module SchemaEvolutionManager
       end
 
       found_arguments = parse_string_arguments(args)
+      not_accepted = found_arguments.keys - required - optional
+      Preconditions.check_state(not_accepted.empty?,
+                                "Flag[%s] is not accepted by this command. Accepted: %s" %
+                                [not_accepted.map { |f| "--#{f}" }.join(" "), (required + optional).map { |f| "--#{f}" }.join(" ")])
       missing = required.select { |field| blank?(found_arguments[field]) }
 
       @artifact_name = found_arguments.delete(:artifact_name)
@@ -76,7 +80,7 @@ module SchemaEvolutionManager
       @set = found_arguments.delete(:set) || []
 
       @dry_run = found_arguments.delete(:dry_run)
-      @non_interactice = found_arguments.delete(:non_interactive)
+      @non_interactive = found_arguments.delete(:non_interactive)
       @password = found_arguments.delete(:password)
       @help = found_arguments.delete(:help)
       @verbose = found_arguments.delete(:verbose)
@@ -120,12 +124,8 @@ module SchemaEvolutionManager
       title = fields.size == 1 ? "Missing parameter" : "Missing parameters"
       sorted = fields.sort_by { |f| f.to_s }
 
-      puts "**************************************************"
-      puts "ERROR: #{title}: #{sorted.join(", ")}"
-      puts "**************************************************"
-      puts help_parameters("Required parameters", required)
-      puts help_parameters("Optional parameters", optional)
-      exit(1)
+      details = [help_parameters("Required parameters", required), help_parameters("Optional parameters", optional)]
+      RdocUsage.error!("#{title}: #{sorted.join(", ")}", RdocUsage::MISSING_INPUT, :details => details)
     end
 
     def help_parameters(title, parameters)
@@ -155,6 +155,7 @@ module SchemaEvolutionManager
         index += 1
 
         if FLAGS_WITH_ARGUMENTS.has_key?(flag)
+          Preconditions.check_state(index < values.length, "Flag[--%s] needs a value" % flag)
           if ARRAY_FLAGS.include?(flag)
             found[flag] ||= []
             found[flag] << values[index]

data/lib/schema-evolution-manager/ask.rb

@@ -13,7 +13,7 @@ module SchemaEvolutionManager
     #        to the screen. If false, we do NOT echo.
     def Ask.for_string(message, opts={})
       default = opts.delete(:default)
-      echo = opts[:echo].nil? ? true : opts.delete(:echo)
+      echo = opts.has_key?(:echo) ? opts.delete(:echo) : true
       Preconditions.assert_empty_opts(opts)
 
       final_message = message.dup
@@ -24,9 +24,15 @@ module SchemaEvolutionManager
       value = nil
       while value.to_s == ""
         print final_message
-        value = get_input(echo).to_s.strip
+        input = get_input(echo)
+        value = input.to_s.strip
         if value.to_s == "" && default
           value = default.to_s.strip
+        elsif input.nil?
+          # Standard input is closed (a pipe, /dev/null, a CI job): asking
+          # again reads nothing again, forever.
+          puts ""
+          raise "No input for[%s]: standard input is closed" % message.strip
         end
       end
       value

data/lib/schema-evolution-manager/baseline_util.rb

@@ -1,48 +1,15 @@
 module SchemaEvolutionManager
 
-  class BaselineUtil
-
-    def initialize(db, opts={})
-      @dry_run = opts.delete(:dry_run)
-      if @dry_run.nil?
-        @dry_run = true
-      end
-
-      @db = Preconditions.assert_class(db, Db)
-      @scripts = Scripts.new(@db, Scripts::SCRIPTS)
-    end
-
-    def dry_run?
-      @dry_run
-    end
-
-    # Applies scripts in order, returning number of scripts applied
-    def apply!(dir)
-      Preconditions.check_state(File.directory?(dir),
-                                "Dir[%s] does not exist" % dir)
-
-      count = 0
-      @scripts.each_pending(dir) do |filename, path|
-        count += 1
-        if @dry_run
-          puts "[DRY RUN] Baselining #{filename}"
-          apply_dry_run(filename, path)
-        else
-          puts "Baselining #{filename}"
-          apply_real(filename, path)
-        end
-      end
-      count
-    end
+  # Records each pending script as run without running it.
+  class BaselineUtil < PendingScriptsUtil
 
     private
-    def apply_dry_run(filename, path)
-      puts path
-      puts ""
+    def label
+      "Baselining"
     end
 
-    def apply_real(filename, path)
-      @scripts.record_as_run!(filename)
+    def execute?
+      false
     end
 
   end

data/lib/schema-evolution-manager/db.rb

@@ -2,6 +2,17 @@ module SchemaEvolutionManager
 
   class Db
 
+    # Every flag that names a database connection. A command that opens a
+    # Db accepts these plus its own flags (dry_run, password, scripts_dir)
+    CONNECTION_FLAGS = %w(url host port name user set) unless defined?(CONNECTION_FLAGS)
+
+    # The connection flags do not name a database: neither --url nor
+    # --name, or a --url that is not a connection string
+    class InvalidConnection < RuntimeError; end
+
+    # Neither --url nor --name was given
+    class MissingConnection < InvalidConnection; end
+
     # psql_args: the psql executable and its global options, as an argv
     attr_reader :url, :psql_args
 
@@ -36,22 +47,43 @@ module SchemaEvolutionManager
     end
 
     # Installs schema_evolution_manager. Automatically upgrades schema_evolution_manager.
-    def bootstrap!
+    #
+    # @param dry_run: When true, prints each bootstrap script that would run
+    # and writes nothing: the schema is neither created nor upgraded. The
+    # pending-script reads answer for an absent schema, so a dry run of the
+    # scripts that follow needs no bootstrap. Returns the number of
+    # bootstrap scripts run (or, in a dry run, that would run).
+    def bootstrap!(opts={})
+      dry_run = opts.delete(:dry_run) || false
+      Preconditions.assert_empty_opts(opts)
+
       scripts = Scripts.new(self, Scripts::BOOTSTRAP_SCRIPTS)
       dir = File.join(Library.base_dir, "scripts")
+      count = 0
       scripts.each_pending(dir) do |filename, path|
-        psql_file(filename, path)
-        scripts.record_as_run!(filename)
+        count += 1
+        if dry_run
+          puts "[DRY RUN] Bootstrapping #{filename}"
+        else
+          psql_file(filename, path, scripts)
+          scripts.record_as_run!(filename)
+        end
       end
+      count
     end
 
     # executes a simple sql command.
     def psql_command(sql_command)
-      Preconditions.assert_class(sql_command, String)
-      command = @psql_args + PSQL_ISOLATION_OPTIONS + ["--no-align", "--tuples-only", "--command", sql_command]
+      command = psql_command_args(sql_command)
       Library.system_or_error(command + [@url], :log => command + [sanitized_url])
     end
 
+    # The psql argv psql_command runs for sql_command, without the url.
+    def psql_command_args(sql_command)
+      Preconditions.assert_class(sql_command, String)
+      @psql_args + PSQL_ISOLATION_OPTIONS + ["--no-align", "--tuples-only", "--command", sql_command]
+    end
+
     def Db.attribute_values(path)
       Preconditions.assert_class(path, String)
 
@@ -78,26 +110,55 @@ module SchemaEvolutionManager
       options
     end
 
-    # executes sql commands from a file in a single transaction.
-    # psql reads the original file, so the line numbers and path in
-    # any psql error match the file in git.
-    def psql_file(filename, path)
+    # Applies the sql file at path and records filename as run in
+    # scripts. psql reads the original file, so the line numbers and path
+    # in any psql error match the file in git.
+    #
+    # A file applied in a single transaction (the default) is recorded by
+    # the same psql invocation, inside that transaction: the script and
+    # its record commit together or not at all, so no interruption can
+    # leave a script applied but unrecorded for the next run to repeat.
+    #
+    # A transaction = none file has no transaction to record it in. It is
+    # recorded afterwards on a connection of its own, and a failure of
+    # that record raises a ScriptError whose applied? is true: the script
+    # ran, and its dml is the one statement left to run.
+    #
+    # @param scripts The Scripts instance that records filename as run;
+    # a failure's ScriptError prints the command that records it there.
+    def psql_file(filename, path, scripts)
       Preconditions.assert_class(path, String)
+      Preconditions.assert_class(scripts, Scripts)
       Preconditions.check_state(File.exist?(path), "File[%s] not found" % path)
 
-      command = psql_file_command(path)
+      single = MigrationFile.new(path).single_transaction?
+      record_sql = scripts.record_as_run_sql(filename)
+      command = psql_file_command(path, single ? record_sql : nil)
 
       output, status = Open3.capture2e(*command)
       if !status.success?
-        raise ScriptError.new(self, filename, path, output)
+        raise ScriptError.new(scripts, filename, path, output)
+      end
+
+      if !single
+        begin
+          scripts.record_as_run!(filename)
+        rescue RuntimeError => e
+          raise ScriptError.new(scripts, filename, path, e.message, :applied => true)
+        end
       end
     end
 
     # The psql argv psql_file runs. ON_ERROR_STOP is set on the
     # command line, after any --set the caller passed, so it is in
     # effect before the first line of the file is read.
-    def psql_file_command(path)
-      @psql_args + PSQL_ISOLATION_OPTIONS + ["--set", "ON_ERROR_STOP=1", "--file", path] + Db.attribute_values(path) + [@url]
+    #
+    # @param record_sql: When given, run by the same psql after the file
+    # (a --command after the --file), so --single-transaction wraps both
+    # in one BEGIN ... COMMIT.
+    def psql_file_command(path, record_sql=nil)
+      record = record_sql ? ["--command", record_sql] : []
+      @psql_args + PSQL_ISOLATION_OPTIONS + ["--set", "ON_ERROR_STOP=1", "--file", path] + record + Db.attribute_values(path) + [@url]
     end
 
     # True if the specific schema exists; false otherwise. Once seen the
@@ -111,26 +172,57 @@ module SchemaEvolutionManager
     end
 
     # Parses command line arguments returning an instance of
-    # Db. Exists if invalid config.
+    # Db. Raises InvalidConnection if they name no database.
     def Db.parse_command_line_config(arg_string)
       Preconditions.assert_class(arg_string, String)
-      args = Args.new(arg_string, :optional => ['url', 'host', 'user', 'name', 'port', 'set'])
+      args = Args.new(arg_string, :optional => CONNECTION_FLAGS)
       Db.from_args(args)
     end
 
+    # The Db a command's connection flags name. Prompts for a password
+    # when --password was given. A connection the flags do not name is
+    # one ERROR line on stderr: exit RdocUsage::MISSING_INPUT when no
+    # database is named, RdocUsage::INVALID_INPUT when --url is malformed.
+    def Db.from_command_line(args)
+      Preconditions.assert_class(args, Args)
+      password = args.password ? Ask.for_password("Please enter your password: ") : nil
+      begin
+        Db.from_args(args, :password => password)
+      rescue MissingConnection => e
+        RdocUsage.error!(e.message, RdocUsage::MISSING_INPUT)
+      rescue InvalidConnection => e
+        RdocUsage.error!(e.message, RdocUsage::INVALID_INPUT)
+      end
+    end
+
     # @param password: Optional password to use when connecting to the database.
+    # Raises InvalidConnection unless args name a database: a --url
+    # that is a connection string, or a --name.
     def Db.from_args(args, opts={})
       Preconditions.assert_class(args, Args)
       password = opts.delete(:password)
       Preconditions.assert_empty_opts(opts)
 
-      options = { :password => password, :set => args.set }
-      if args.url
-        Db.new(args.url, options)
+      Db.new(Db.connection_url(args), :password => password, :set => args.set)
+    end
+
+    # The url args name: --url as given, else one built from --host,
+    # --port, --name and --user
+    def Db.connection_url(args)
+      url = args.url.to_s.strip
+      name = args.name.to_s.strip
+
+      if !url.empty?
+        # A bare database name passed to --url is the common mistake
+        if !url.include?("://")
+          raise InvalidConnection.new("--url must be a full connection string (e.g. postgres://localhost:5432/%s). To connect by database name, use --name %s." % [url, url])
+        end
+        url
+      elsif name.empty?
+        raise MissingConnection.new("Missing database connection. Provide --url <postgres url> or --host/--name.")
       else
-        base = "%s:%s/%s" % [args.host || "localhost", args.port || ConnectionData::DEFAULT_PORT, args.name]
-        url = args.user ? "%s@%s" % [args.user, base] : base
-        Db.new("postgres://" + url, options)
+        base = "%s:%s/%s" % [args.host || "localhost", args.port || ConnectionData::DEFAULT_PORT, name]
+        "postgres://" + (args.user ? "%s@%s" % [args.user, base] : base)
       end
     end
 

data/lib/schema-evolution-manager/library.rb

@@ -38,14 +38,8 @@ module SchemaEvolutionManager
     end
 
     def Library.git_assert_tag_exists(tag)
-      command = ["git", "tag", "-l"]
-      results = Library.system_or_error(command)
-      if results.nil?
-        raise "No git tags found"
-      end
-
       if !Library.tag_exists?(tag)
-        raise "Tag[#{tag}] not found. Check #{Shellwords.join(command)}"
+        raise "Tag[#{tag}] not found. Check git tag -l"
       end
     end
 
@@ -61,7 +55,13 @@ module SchemaEvolutionManager
     # no tags, otherwise returns an instance of Version. Only searches for
     # tags matching x.x.x (e.g. 1.0.2)
     def Library.latest_tag
-      Library.git_tags.select { |tag| Version.is_valid?(tag) }.map { |tag| Version.parse(tag) }.sort.last
+      Library.release_tags.last
+    end
+
+    # The release tags among +tags+ (x.y.z, optionally prefixed) as
+    # Versions, oldest first. Defaults to every tag in the repository.
+    def Library.release_tags(tags=Library.git_tags)
+      tags.select { |tag| Version.is_valid?(tag) }.map { |tag| Version.parse(tag) }.sort
     end
 
     # True only when a tag with exactly this name exists - 1.0.10 does
@@ -70,11 +70,14 @@ module SchemaEvolutionManager
       Library.git_tags.include?(tag)
     end
 
+    # Every tag in the repository. Raises when git fails (outside a
+    # checkout, git missing), so a failure never reads as "no tags".
     def Library.git_tags
-      `git tag -l`.strip.split
+      Library.system_or_error(["git", "tag", "-l"]).split
     end
 
     # Ex: Library.git_create_tag("0.0.1")
+    # Pushes only the tag it creates, never the checkout's other local tags.
     def Library.git_create_tag(tag)
       Library.assert_valid_tag(tag)
       has_remote = Library.git_has_remote?
@@ -83,7 +86,7 @@ module SchemaEvolutionManager
       end
       Library.system_or_error(["git", "tag", "-a", "-m", tag, tag])
       if has_remote
-        Library.system_or_error(["git", "push", "--tags", "origin"])
+        Library.system_or_error(["git", "push", "origin", "refs/tags/%s" % tag])
       end
     end
 

data/lib/schema-evolution-manager/migration_file.rb

@@ -53,6 +53,12 @@ module SchemaEvolutionManager
       @attribute_values = parse_attribute_values
     end
 
+    # True when psql applies the whole file in one transaction
+    # (transaction = single, the default)
+    def single_transaction?
+      @attribute_values.any? { |v| v.attribute.name == "transaction" && v.value == "single" }
+    end
+
     private
 
     # Returns a list of AttributeValues from the file itself,

data/lib/schema-evolution-manager/pending_scripts_util.rb

@@ -0,0 +1,30 @@
+module SchemaEvolutionManager
+
+  # Applies the pending scripts of a directory to the scripts table, with
+  # a dry run by default. Subclasses name the action (label) and whether
+  # each script body is executed (execute?); Scripts#apply_pending! is the
+  # loop.
+  class PendingScriptsUtil
+
+    def initialize(db, opts={})
+      @dry_run = opts.delete(:dry_run)
+      if @dry_run.nil?
+        @dry_run = true
+      end
+
+      @db = Preconditions.assert_class(db, Db)
+      @scripts = Scripts.new(@db, Scripts::SCRIPTS)
+    end
+
+    def dry_run?
+      @dry_run
+    end
+
+    # Applies scripts in order, returning number of scripts applied
+    def apply!(dir)
+      @scripts.apply_pending!(dir, :execute => execute?, :dry_run => @dry_run, :label => label)
+    end
+
+  end
+
+end

data/lib/schema-evolution-manager/rdoc_usage.rb

@@ -26,6 +26,35 @@ module SchemaEvolutionManager
       exit(exit_code)
     end
 
+    # Exit codes for a command-line fault, one per kind of fault
+    unless defined?(MISSING_INPUT)
+      # A required argument, subcommand or connection was not given
+      MISSING_INPUT = 3
+      # An argument was given that the command does not accept
+      INVALID_INPUT = 4
+      # The input was well formed and running it failed
+      FAILED = 1
+    end
+
+    # A command-line fault: one "ERROR: <message>" line on stderr, then
+    # any detail lines (and the command's usage, with :usage => true),
+    # then exit with exit_code. Never writes to stdout, so a wrapper that
+    # captures stdout (TAG=$(sem-info tag next minor)) captures no error.
+    def RdocUsage.error!(message, exit_code, opts={})
+      details = opts.delete(:details) || []
+      usage = opts.delete(:usage)
+      Preconditions.assert_empty_opts(opts)
+      Preconditions.check_state([MISSING_INPUT, INVALID_INPUT, FAILED].include?(exit_code), "Invalid exit_code[%s]" % exit_code)
+
+      $stderr.puts "ERROR: %s" % message
+      details.each { |line| $stderr.puts line }
+      if usage
+        $stderr.puts ""
+        $stderr.puts RdocUsage.message
+      end
+      exit(exit_code)
+    end
+
     private
     def RdocUsage.program_name
       $0

data/lib/schema-evolution-manager/script_error.rb

@@ -4,16 +4,31 @@ module SchemaEvolutionManager
 
     attr_reader :path, :output
 
-    def initialize(db, filename, path, output)
-      @db = Preconditions.assert_class(db, Db)
+    # @param scripts The Scripts instance that records filename as run
+    # @param applied: true when the script ran to completion and only
+    #        recording it as run failed (a transaction = none script,
+    #        whose record cannot share its transaction)
+    def initialize(scripts, filename, path, output, opts={})
+      @scripts = Preconditions.assert_class(scripts, Scripts)
       @filename = Preconditions.assert_class(filename, String)
       @path = Preconditions.assert_class(path, String)
       @output = Preconditions.assert_class(output, String)
+      @applied = opts.delete(:applied) || false
+      Preconditions.assert_empty_opts(opts)
     end
 
+    # True when the script was applied and is not recorded as run: its
+    # dml must be run before the next apply, or that apply runs it again
+    def applied?
+      @applied
+    end
+
+    # The psql command that records this script as applied: the statement
+    # Scripts#record_as_run! executes, in the argv Db#psql_command runs.
     def dml
-      sql_command = "insert into %s.%s (filename) values ('%s')" % [Db.schema_name, Scripts::SCRIPTS, @filename]
-      "psql --command \"%s\" %s" % [sql_command, @db.sanitized_url]
+      db = @scripts.db
+      command = db.psql_command_args(@scripts.record_as_run_sql(@filename)) + [db.sanitized_url]
+      Library.command_to_s(command)
     end
 
   end

data/lib/schema-evolution-manager/scripts.rb

@@ -2,6 +2,8 @@ module SchemaEvolutionManager
 
   class Scripts
 
+    attr_reader :db, :table_name
+
     if !defined?(SCRIPTS)
       SCRIPTS = "scripts"
       BOOTSTRAP_SCRIPTS = "bootstrap_scripts"
@@ -72,6 +74,45 @@ module SchemaEvolutionManager
       end
     end
 
+    # Walks the pending scripts of dir in order and records each as run,
+    # returning how many were pending.
+    #
+    # @param execute: true applies each script with Db#psql_file, which
+    #        records it too (inside the script's own transaction unless it
+    #        is transaction = none); false only records it (a baseline)
+    # @param dry_run: true prints each pending script and its path and
+    #        changes nothing
+    # @param label: The action printed per script ("Applying",
+    #        "Baselining", "Bootstrapping")
+    # @param quiet: true prints nothing outside a dry run
+    def apply_pending!(dir, opts={})
+      execute = opts.delete(:execute)
+      dry_run = opts.delete(:dry_run)
+      label = Preconditions.assert_class(opts.delete(:label), String)
+      quiet = opts.delete(:quiet) || false
+      Preconditions.assert_empty_opts(opts)
+      Preconditions.check_state(File.directory?(dir),
+                                "Dir[%s] does not exist" % dir)
+
+      count = 0
+      each_pending(dir) do |filename, path|
+        count += 1
+        if dry_run
+          puts "[DRY RUN] #{label} #{filename}"
+          puts path
+          puts ""
+        elsif execute
+          print "#{label} #{filename}" unless quiet
+          @db.psql_file(filename, path, self)
+          puts " Done" unless quiet
+        else
+          puts "#{label} #{filename}" unless quiet
+          record_as_run!(filename)
+        end
+      end
+      count
+    end
+
     # True if this script has already been applied to the db. False
     # otherwise.
     def has_run?(filename)
@@ -86,9 +127,15 @@ module SchemaEvolutionManager
 
     # Inserts a record to indiciate that we have loaded the specified file.
     def record_as_run!(filename)
+      @db.psql_command(record_as_run_sql(filename))
+    end
+
+    # The statement record_as_run! executes: an idempotent insert of
+    # filename into this instance's table. ScriptError#dml prints it as
+    # the recovery command, so the hint and the write are one statement.
+    def record_as_run_sql(filename)
       literal = Db.quote_literal(Scripts.assert_valid_filename!(filename))
-      command = "insert into %s.%s (filename) select %s where not exists (select 1 from %s.%s where filename = %s)" % [Db.schema_name, @table_name, literal, Db.schema_name, @table_name, literal]
-      @db.psql_command(command)
+      "insert into %s.%s (filename) select %s where not exists (select 1 from %s.%s where filename = %s)" % [Db.schema_name, @table_name, literal, Db.schema_name, @table_name, literal]
     end
 
     # Returns the sorted list of filenames already applied to this database.

data/lib/schema-evolution-manager/sem_info.rb

@@ -10,31 +10,16 @@ module SchemaEvolutionManager
       valid = ['version', 'scripts']
       subcommand = args.shift.to_s.strip
 
-      if !valid.include?(subcommand)
-        if subcommand.empty?
-          $stderr.puts "ERROR: Missing db subcommand. Must be one of: %s" % valid.join(", ")
-        else
-          $stderr.puts "ERROR: Invalid db subcommand[%s]. Must be one of: %s" % [subcommand, valid.join(", ")]
-        end
-        exit(4)
-      end
-
-      db_args = SchemaEvolutionManager::Args.new(args, :optional => ['url', 'host', 'user', 'name', 'port', 'set'])
-
-      if db_args.url.to_s.strip.empty? && db_args.name.to_s.strip.empty?
-        $stderr.puts "ERROR: Missing database connection. Provide --url <postgres url> or --host/--name."
-        exit(3)
+      if subcommand.empty?
+        RdocUsage.error!("Missing db subcommand. Must be one of: %s" % valid.join(", "), RdocUsage::MISSING_INPUT)
+      elsif !valid.include?(subcommand)
+        RdocUsage.error!("Invalid db subcommand[%s]. Must be one of: %s" % [subcommand, valid.join(", ")], RdocUsage::INVALID_INPUT)
       end
 
-      # A common mistake is passing a bare database name to --url. Catch it with
-      # an actionable hint instead of letting parse_url raise a raw backtrace.
-      if db_args.url && !db_args.url.include?("://")
-        $stderr.puts "ERROR: --url must be a full connection string (e.g. postgres://localhost:5432/%s). To connect by database name, use --name %s." % [db_args.url, db_args.url]
-        exit(3)
-      end
+      db_args = SchemaEvolutionManager::Args.new(args, :optional => SchemaEvolutionManager::Db::CONNECTION_FLAGS)
 
       begin
-        db = SchemaEvolutionManager::Db.from_args(db_args)
+        db = SchemaEvolutionManager::Db.from_command_line(db_args)
         if subcommand == "version"
           version = SchemaEvolutionManager::Versions.new(db).latest
           if version.nil?
@@ -53,8 +38,7 @@ module SchemaEvolutionManager
       rescue => e
         # Surface a single clean line (e.g. bad url, unreachable host, missing
         # database) rather than a Ruby stack trace.
-        $stderr.puts "ERROR: %s" % e.message.to_s.split("\n").first
-        exit(3)
+        RdocUsage.error!(e.message.to_s.split("\n").first, RdocUsage::FAILED)
       end
     end
 
@@ -66,8 +50,7 @@ module SchemaEvolutionManager
       if subcommand == "exists"
         tag = args.shift.to_s.strip
         if tag.empty?
-          puts "ERROR: Missing tag."
-          exit(3)
+          RdocUsage.error!("Missing tag.", RdocUsage::MISSING_INPUT)
         elsif ::SchemaEvolutionManager::Library.tag_exists?(tag)
           puts "true"
         else
@@ -85,12 +68,10 @@ module SchemaEvolutionManager
         ::SchemaEvolutionManager::SemInfo::Tag.next(args).to_version_string
 
       elsif subcommand.empty?
-        puts "ERROR: Missing tag subcommand. Must be one of: %s" % valid.join(", ")
-        exit(3)
+        RdocUsage.error!("Missing tag subcommand. Must be one of: %s" % valid.join(", "), RdocUsage::MISSING_INPUT)
 
       else
-        puts "ERROR: Invalid tag subcommand[%s]. Must be one of: %s" % [subcommand, valid.join(", ")]
-        exit(4)
+        RdocUsage.error!("Invalid tag subcommand[%s]. Must be one of: %s" % [subcommand, valid.join(", ")], RdocUsage::INVALID_INPUT)
       end
     end
 
@@ -112,8 +93,7 @@ module SchemaEvolutionManager
         if valid.include?(component)
           latest.send("next_%s" % component)
         else
-          puts "ERROR: Invalid component[%s]. Must be one of: %s" % [component, valid.join(", ")]
-          exit(4)
+          RdocUsage.error!("Invalid component[%s]. Must be one of: %s" % [component, valid.join(", ")], RdocUsage::INVALID_INPUT)
         end
       end
 

data/lib/schema-evolution-manager/sem_version.rb

@@ -3,7 +3,7 @@ module SchemaEvolutionManager
 
 module SemVersion
 
-VERSION ||= '0.9.74'
+VERSION ||= '0.9.75'
 
 end
 

data/lib/schema-evolution-manager/version.rb

@@ -2,7 +2,13 @@ module SchemaEvolutionManager
 
   class Version
 
-    VERSION_FILE = File.join(Library.base_dir, "VERSION") unless defined?(VERSION_FILE)
+    unless defined?(VERSION_FILE)
+      VERSION_FILE = File.join(Library.base_dir, "VERSION")
+      # An optional prefix (v1.2.3, r1.2.3) then major.minor.micro. The
+      # prefix is lazy so it never takes a leading digit of the major
+      # version: 10.2.3 is major 10, not prefix "1" and major 0.
+      PATTERN = /\A(\w*?)(\d+)\.(\d+)\.(\d+)\z/
+    end
 
     attr_reader :major, :minor, :micro
 
@@ -11,15 +17,13 @@ module SchemaEvolutionManager
       @minor = minor.to_i
       @micro = micro.to_i
       @prefix = opts.delete(:prefix) || nil
-      if !opts.empty?
-        raise "Invalid keys: " + opts.keys
-      end
+      Preconditions.assert_empty_opts(opts)
     end
 
     def Version.parse(version_string)
       Preconditions.check_not_blank(version_string, "version_string cannot be blank")
       Library.assert_valid_tag(version_string)
-      if md = version_string.match(/^(\w*)(\d+)\.(\d+)\.(\d+)$/)
+      if md = version_string.match(PATTERN)
         Version.new(md[2], md[3], md[4], :prefix => md[1])
       else
         raise "ERROR: Bug in version string parser for version[%s]" % version_string
@@ -74,7 +78,7 @@ module SchemaEvolutionManager
 
     def Version.is_valid?(version_string)
       Preconditions.check_not_blank(version_string, "version_string cannot be blank")
-      version_string.match(/^\w*\d+\.\d+\.\d+$/) ? true : false
+      PATTERN.match?(version_string)
     end
 
   end

data/lib/schema-evolution-manager.rb

@@ -23,6 +23,7 @@ load File.join(lib_dir, 'scripts.rb')
 load File.join(lib_dir, 'versions.rb')
 load File.join(lib_dir, 'connection_data.rb')
 load File.join(lib_dir, 'db.rb')
+load File.join(lib_dir, 'pending_scripts_util.rb')
 load File.join(lib_dir, 'apply_util.rb')
 load File.join(lib_dir, 'baseline_util.rb')
 load File.join(lib_dir, 'template.rb')

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: schema-evolution-manager
 version: !ruby/object:Gem::Version
-  version: 0.9.74
+  version: 0.9.75
 platform: ruby
 authors:
 - Michael Bryzek
 bindir: bin
 cert_chain: []
-date: 2026-11-07 00:00:00.000000000 Z
+date: 2026-11-11 00:00:00.000000000 Z
 dependencies: []
 description: '["Michael Bryzek"]'
 email: mbryzek@alum.mit.edu
@@ -41,6 +41,7 @@ files:
 - lib/schema-evolution-manager/install_template.rb
 - lib/schema-evolution-manager/library.rb
 - lib/schema-evolution-manager/migration_file.rb
+- lib/schema-evolution-manager/pending_scripts_util.rb
 - lib/schema-evolution-manager/preconditions.rb
 - lib/schema-evolution-manager/rdoc_usage.rb
 - lib/schema-evolution-manager/script_error.rb