psql-cm 0.0.4 → 0.0.5

data/History.md

@@ -1,3 +1,10 @@
+# 0.0.5 - 2012-04-18
+
+Added git repository feature to sql-path for dump action, a commit per run of
+the dump action occurs.
+
+Bugfix: do not write pgpass line multiple times to the file.
+
 # 0.0.4 - 2012-04-18
 
 'restore' action functional.

data/README.md

@@ -1,46 +1,134 @@
 # PostgreSQL Change Management Tool
 
-This project is a tool for schema change management within a PostgreSQL database
-cluster.
+## What psql-cm is
 
-# Prerequisites
+This project is a tool to assist with an ITIL like change management process
+for *database schemas* within a PostgreSQL database cluster.
+
+Specifically psql-cm is a tool which encodes *one* change management process
+for a complex multi database, multi schema PostgreSQL system.
+
+This means that psql-cm may be much more than you need for a simple
+single database system.  Please take the time to understand the process and
+what problems it solves. In order for psql-cm to be effective it must be
+combined with complimentary process and adherence.
+
+## What psql-cm is not
+
+psql-cm is not intended on being a solution whatsoever for data backup.
+
+For backup of data instead use the
+[pg\_dump](http://www.postgresql.org/docs/current/static/app-pgdump.html)
+command line utility for backing up data in addition to a
+[repliaction](http://www.postgresql.org/docs/current/static/different-replication-solutions.html)
+technique tailored to your needs.
+
+## The process
+
+# Using psql-cm
+
+## Prerequisites
 
 - [Ruby >= 1.9.3](http://www.ruby-lang.org/en/)
 - [Postgresql >= 9.1+](http://www.postgresql.org/)
 - [Git SCM](http://git-scm.com/)
 
-# Installation of psql-cm
+## Installation
 
 Once the prerequisites have been satisfied on your system, using the
 'gem' command from Ruby 1.9.3 do:
 
-    user$ gem install psql-scm
+    $ gem install psql-scm
 
-# Setup
+## Setup
 
 Setup the psql\_cm control tables on the target databases, use a comma (',')
 to separate multiple database names.
 
-    user$ psql-cm --databases psqlcm_test --uri "postgres://127.0.0.1:5432" setup
+    $ psql-cm --databases psqlcm_test --uri "postgres://127.0.0.1:5432" setup
 
-# Dump
+## Dump
 
 Dump the current database schema to the specified --sql-path directory, if none
 specified it dumps to $PWD/sql
 
-    user$ psql-cm --databases psqlcm_test --uri "postgres://127.0.0.1:5432" dump
+    $ psql-cm --databases psqlcm_test --uri "postgres://127.0.0.1:5432" dump
 
-# Restore (Currently being implemented)
+## Restore
 
 Restore a previously psql-cm dumped database schema into a brand new postgresql
 database cluster.
 
-    user$ psql-cm --databases psqlcm_test --uri "postgres://127.0.0.1:5432" restore
+    $ psql-cm --databases psqlcm_test --uri "postgres://127.0.0.1:5432" restore
+
+## Command line parameters
+
+--databases argument may take multiple database targets, to do this pass them
+in ',' separated format, no spaces. Specifically the format is,
+
+    $ psql-cm --databases psqlcm_test,psqlcm_test2,... ...
+
+--uri has the format,
+
+    $ psql-cm --uri "postgres://{user}:{password}@{host}:{port}/{database}?{sslmode}={mode}"
+
+user, password, port, the ? and everything after it (the query) are all optional.
+
+sslmode mode may be one of disable, allow, prefer, require if used.
+
+# Walkthrough
+
+First let's create a PostgreSQL database for us to work with,
+
+    $ createdb psqlcm_test
+
+Next let's create two schemas in addition to the public schema (which is added
+by default when the database is created) and a table for each schema for our
+database.
+
+    $ psql psqlcm_test -c '
+        SET search_path = public;
+        CREATE SCHEMA schema_one;
+        CREATE TABLE a_bool(a BOOL);
+
+        SET search_path = schema_one;
+        CREATE TABLE an_integer(an INTEGER);
+
+        CREATE SCHEMA schema_two;
+        SET search_path = schema_two;
+        CREATE TABLE a_varchar(a VARCHAR);'
+
+Now that we have a base set of database(s) and schemas that we wish to apply
+change management process to we can setup the psql-cm control tables.
+
+The setup action adds one table called 'pg\_psql\_cm' to each of the target
+database schemas.
+
+    $ psql-cm --databases psqlcm_test --uri "postgres://127.0.0.1:5432" setup
+
+Use a PostgreSQL client tool (psql/pgAdmin/Navicat/...) and examine the schemas
+for the psqlcm\_test database for which there should be three:
+
+    public
+    schema_one
+    schema_two
+
+each with two tables, the pg\_psql\_cm control table and one other table.
+
+Next we'll dump the schema to sql/ within our working directory
+
+    $ psql-cm --databases psqlcm_test --uri "postgres://127.0.0.1:5432" dump
+
+At this point we have the base schema for the psqlcm\_test database recorded and
+we can test to see that this is true by droping the database and then running
+the psql-cm restore action.
+
+    $ dropdb psqlcm_test
+    $ psql-cm --databases psqlcm_test --uri "postgres://127.0.0.1:5432" restore
 
-# Example
+Once again use yoru favorite client tool and verify that the schema is inded
+what it was after setup was run.
 
-    user$ createdb psqlcm_test
-    user$ psql psqlcm_test -c 'CREATE SCHEMA schema_one; CREATE SCHEMA schema_two'
-    user$ echo psql-cm --databases psqlcm_test --uri "postgres://127.0.0.1:5432" setup
-    user$ psql-cm --databases psqlcm_test --uri "postgres://127.0.0.1:5432" dump
+Note that one caveat is that psql-cm does not handle ROLEs and USERs so these
+will have to be accounted for after doing a restore.
 

data/lib/psql-cm/base.rb

@@ -87,6 +87,10 @@ module PSQLCM
             sh 'dump', command
           end
         end
+
+        sh 'git', "git init; git add ." unless File.exists?('.git') && File.directory?('.git')
+
+        sh 'git', "git commit -a -m 'PostgreSQL Change Management (psql-cm).\nDatabases: #{databases}\nTree: #{tree}'"
       end
     end # def dump!
 
@@ -148,6 +152,11 @@ module PSQLCM
           end
         end
       end
+    end # def restore!
+
+    def change!
+      puts "TODO: allow change string and/or file to be specified and add to the
+      specified database scema control table"
     end
 
     def run!(action = config.action, parent_id = config.parent_id)
@@ -162,6 +171,8 @@ module PSQLCM
         restore!
       when "setup"
         setup!
+      when "change"
+        change!
       else
         halt! "Action '#{action}' is not handled."
       end

data/lib/psql-cm/database.rb

@@ -36,18 +36,20 @@ module PSQLCM
     end
 
     def pgpass # Ensure a pgpass entry exists for this connection.
-      pgpass_line = [
-        @config[:host], @config[:port], @config[:dbname], @config[:user],
-        @config[:password]
-      ].join(':')
+      pgpass_line = [ @config[:host], @config[:port], @config[:dbname],
+                      @config[:user], @config[:password] ].join(':')
 
-      content = File.open(File.join(ENV['HOME'], '.pgpass'), 'r') { |file| file.read }
-      unless content.lines.detect{ |line| line == pgpass_line }
+      content = File.open(File.join(ENV['HOME'], '.pgpass'), 'r') do |file|
+        file.read
+      end.split("\n")
+
+      unless content.detect{ |line| line == pgpass_line }
         File.open(File.join(ENV['HOME'], '.pgpass'), 'w') do |file|
-          file.write(content + pgpass_line + "\n")
+          content << pgpass_line
+          file.write(content.join("\n") + "\n")
         end
+        File.chmod(0600, File.join(ENV['HOME'], '.pgpass'))
       end
-
       pgpass_line
     end # def pgpass
 

data/lib/psql-cm/version.rb

@@ -1,4 +1,4 @@
 module PSQLCM
-  Version = '0.0.4'
+  Version = '0.0.5'
 end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: psql-cm
 version: !ruby/object:Gem::Version
-  version: 0.0.4
+  version: 0.0.5
   prerelease: 
 platform: ruby
 authors: