Version 1.0.0

.travis.yml

@@ -0,0 +1,18 @@
+sudo: required
+dist: trusty
+language: ruby
+rvm:
+  - 2.2
+  - 2.1
+  - 2.0
+services:
+  - postgresql
+addons:
+  postgresql: "9.6"
+before_install:
+  - sudo apt-get -qq update
+  - sudo apt-get install -y postgresql-server-dev-9.6
+before_script:
+  - psql -c 'create database dumbo_test;' -U postgres
+  - cp config/database.yml.travis config/database.yml
+  - sudo chmod 777 /usr/lib/postgresql/9.6/lib /usr/share/postgresql/9.6/extension

Gemfile

@@ -1,4 +1,8 @@
 source 'https://rubygems.org'
 
 # Specify your gem's dependencies in dumbo.gemspec
-gemspec
+gemspec
+
+gem 'rspec', '~> 3.5.0'
+gem 'pry'
+gem 'rake', '~> 10.5'

README.md

@@ -1,60 +1,168 @@
-# Dumbo
+[![Build Status](https://travis-ci.org/adjust/dumbo.svg?branch=version-1.0.0)](https://travis-ci.org/adjust/dumbo)
 
-postgres extension with fun
+# Dumbo - the PostgreSQL Extension-Development Framework
 
-![](http://img1.wikia.nocookie.net/__cb20091210033559/disney/images/7/76/Dumbo-HQ.JPG)
+Dumbo has been created with the purpose to facilitate development of PostgreSQL
+extensions. Together with our [pgbundle
+project](https://github.com/adjust/pgbundle) tool, it brings a lean approach
+to the development of a bundle of PostgreSQL extension dependencies.
+
+Some of the features the Dumbo framework offers are:
+
+  * facilitated PostgreSQL extension initialization
+  * improved version management
+  * automated generation of upgrade/downgrade migrations
+  * ERB templating support for automating repeated code generation
 
 ## Installation
 
-Add this line to your application's Gemfile:
+To install Dumbo you can use rubygems' `gem` command from your command line:
 
-    gem 'dumbo'
+    $ gem install dumbo
 
-And then execute:
+This should get you sorted instantly but in special system setup you might to
+use `sudo` for this command to run.
 
-    $ bundle
+## Configuration
 
-Or install it yourself as:
+For some of its features Dumbo requires a database connection. For example when
+building migration files between extension versions, Dumbo needs to install
+these two versions on PostgreSQL and compare the respective Postgres objects.
+Database connection settings are expected to be present in `config/database.yml`.
+The expected structure of this file is:
 
-    $ gem install dumbo
+    development:
+      client_encoding: utf8
+      user: postgres
+      password:
+      host: localhost
+      port: 5432
+      dbname: dumbo_test
+
+Note that the keys follow the standard PostgreSQL [connection string
+parameters](https://www.postgresql.org/docs/9.5/static/libpq-connect.html#LIBPQ-CONNSTRING).
+
+## Usage
+
+Dumbo comes with an executable, which would be your main interface to the
+functionality of the framework.
+
+### Initialize new PostgreSQL extension
+
+For new PG extension projects, Dumbo can generate a directory skeleton and
+create the typical files for you.
+
+    $ dumbo new myextname [Initial.Version.String] ['This extension is about that']
+
+where "myextname" is the name for the new PG extension. As a stating point take
+a look at the sample functions generated in `sql/myextname.sql` as well as the
+generated `Makefile`.
+
+The optional second argument sets the initial version for the new extension; the
+default value is `0.0.1` but you could for example wish to start at `0.1.0`.
+Note that the extension versions must follow the Semantic versioning style. An
+optional third argument is a description on what the extension would be about.
+
+So, as a concrete example, the following command line command command:
 
-## Getting Started
+    $ dumbo new pg_currency 0.1.0 'A currency data-type for PostgreSQL'
 
-At the command prompt, create a new extension:
+would generate a project skeleton like this:
 
-  dumbo new myextention
+    pg_currency
+    ├── Makefile
+    ├── pg_currency--0.1.0.sql
+    ├── README.md
+    ├── config
+    │   └── database.yml
+    ├── pg_currency.control
+    ├── sql
+    │   └── pg_currency.sql
+    ├── src
+    │   ├── pg_currency.c
+    │   └── pg_currency.h
+    └── test
+        ├── expected
+        │   └── pg_currency_test.out
+        └── sql
+            └── pg_currency_test.sql
 
-where "myextention" is the extension name.
+This is already enough for you to go into the newly created directory and
+install your extension against Postgres using standard `make install`.
 
-Change directory to myextention to start hacking:
+Once installed, login to Postgres using `psql` and issue this SQL:
 
-    cd myapp
+    CREATE EXTENSION pg_currency;
 
-As a stating point take a look at the sample function in
+This skeleton includes the SQL declaration and C implementation of a sample
+funcion called `add_one(int)`. Note that there's also an automatically
+generated sample regression testsuite, which you can run using the standard:
 
-    sql/sample.sql
+    $ make installcheck
 
-and the corresponding test file
+from your command line.
 
-    spec/sample_spec.rb
+### Building the extension
 
-build the extension and run the specs
+Using Dumbo you'd typically write SQL in files under the `sql` directory and
+optionally C code in the `src` directory. To concatenate the SQL files into the
+required `extname--0.0.1.sql` extension file, Dumbo offers the following command:
 
-    rake
+    $ dumbo build
 
-if you start working on a new version run
+`dumbo new` builds this file for you, but for any following version
+you'd need to run `dumbo build` in order to concatinate files in `sql/*.sql`
+together.
 
-    rake dumbo:new_version [level]
+Note that if you haven't bumped the extension version in the `extname.control`
+file, subsequent `dumbo build` runs will overwrite the same generated file. This
+comes handy while doing development work.
 
-where level is new version level (major, minor patch)
+#### Using ERB templates
 
-when you are done you can create the migration files with
+Files under `sql/*.sql.erb` and `src/*.{c,h}.erb` support templating using the
+ERB format. If you use that feature I've no idea what will happen....
 
-    rake dumbo:migrations
+### Start a new version
+
+To initialize a new version on an existing extension:
+
+    $ dumbo bump [major|minor|patch]
+
+Note that keeping to the (major.minor.patch) versioning is required. If no
+argument is given, the default level for the version bump is `patch`. So given
+a current version `0.1.0`:
+
+    $ dumbo bump
+
+will update the `*.control` file of the extension to version `0.1.1`.
+
+### Create migrations between versions
+
+Developing a PostgreSQL extension involves producing and releasing multiple
+versions. To migrate from one version to version PostgreSQL supports the
+mechanism of migration (upgrade & downgrade) files. These are files named like
+`extname--0.0.1--0.0.2.sql` upgrading from version `0.0.1` to `0.0.2` and
+`extname--0.0.2--0.0.1.sql` downgrading the other way.
+
+Maintaining the changes between versions in these files manually is tedious and
+error-prone and Dumbo does it for you automatically.
+
+    $ dumbo migrations
+
+Note that Dumbo differentiates between extension versions by looking for files structured
+`extname--major.minor.patch.sql`. Here `extname` is the name of the extension
+and the `major.minor.patch` is the version - e.g. `0.1.1`.
+
+![](http://img1.wikia.nocookie.net/__cb20091210033559/disney/images/7/76/Dumbo-HQ.JPG)
 
 ## Contributing
 
-1. Fork it ( http://github.com/adeven/dumbo/fork )
+Contributions in form of Pull Request, documentation improvement and/or [issue
+reports](https://github.com/adjust/dumbo/issues) are very welcome. To contribute
+code:
+
+1. Fork it (http://github.com/adjust/dumbo/fork)
 2. Create your feature branch (`git checkout -b my-new-feature`)
 3. Commit your changes (`git commit -am 'Add some feature'`)
 4. Push to the branch (`git push origin my-new-feature`)

Rakefile

@@ -1,9 +1,7 @@
 require 'rake'
 require 'bundler/gem_tasks'
 require 'rspec/core/rake_task'
-require 'dumbo/db_task'
 
 RSpec::Core::RakeTask.new(:spec)
-Dumbo::DbTask.new(:db)
 
-task :default => ['db:test:prepare', :spec]
+task :default => :spec