oraora 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: ea908b533f803251dad4a3c654c32da376f4026b
+  data.tar.gz: 708a8b06e602feaf36619098b5f585d6bed3505a
+SHA512:
+  metadata.gz: d9d0bad778bd145d9244ce38bf32bfba433d6c259bca2669e8666657e2818cd953ca5f5ffae409c446b57da319b6cc8892739a4c2c2d3daefbd5fdc0c8dc64fc
+  data.tar.gz: 59cc924133dcafbbf68d78b70606a6fb3a3d63122cec05fed7c6a4c29794ab700f61ac1437a2240a02c92681e8d52db658e0e020a7f1b56751e533a14899b2cf

data/.gitignore

@@ -0,0 +1,8 @@
+*.gem
+Gemfile.lock
+.ruby-version
+.ruby-gemset
+.rvmrc
+
+# RubyMine project
+/.idea

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2014 Kombajn Zbożowy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,141 @@
+# Oraora
+
+Oraora is a command-line utility for interacting with Oracle database.
+
+## Features
+
+* Command line history
+* Input TAB-completion
+* Password file support
+* Metadata querying
+* Context-aware SQL
+* Readable colored output
+* su/sudo as SYS
+
+## Installation
+
+Oraora comes bundled as a Ruby gem. To install just run:
+```
+$ gem install oraora
+```
+
+If you don't have Ruby, check one-click installer for Windows or rvm for Linux.
+
+## Usage
+
+Start oraora passing connection string as argument, just like you would connect to SQL*Plus:
+```
+$ oraora user/password@DB
+```
+
+OS authentication is supported (pass `/`).
+
+Roles are supported (append `as SYSDBA` / `as SYSOPER`).
+
+### Passfile
+
+Oraora attempts to read file `.orapass` in your home directory if it exists. It should contain connection strings in
+`user/password@DB` format. Then it's enough to provide `user@DB` when connecting and oraora will automatically fill
+the password.
+```
+$ oraora --log-level=debug user@DB
+[DEBUG] Connecting: user/password@DB
+```
+
+### Context
+
+Use `c` command to navigate through database like directory structure.
+```
+~ $ c some_table                  # Starting at home schema, navigate into table some_table
+~.SOME_TABLE $ c col1             # Navigate into column col1
+~.SOME_TABLE.COL1 $ c -           # Navigate up
+~.SOME_TABLE $ c --               # Navigate two levels up - to database level. You could also use 'cd .'
+. $ c HR.EMPLOYEES                # Navigate to schema HR, table EMPLOYEES
+HR.EMPLOYEES $ c -/DEPARTMENTS    # Navigate up, then to table DEPARTMENTS
+HR.DEPARTMENTS $ c .              # Navigate to root (database level)
+/ $ c                             # Navigate to your home schema
+```
+
+Note: `c` is aliased as `cd` for unix addicts.
+
+### Listing and describing objects
+
+Use `d` command to describe object currently in context.
+```
+HR.EMPLOYEES $ d
+Schema:       HR
+Name:         EMPLOYEES
+Partitioned:  NO
+```
+
+Use `l` command to list for object currently in context. In database schemas are listed. In schema - objects. In table,
+view or materialized view - columns, etc.
+```
+HR.EMPLOYEES $ l
+EMPLOYEE_ID                     PHONE_NUMBER                    COMMISSION_PCT
+FIRST_NAME                      HIRE_DATE                       MANAGER_ID
+LAST_NAME                       JOB_ID                          DEPARTMENT_ID
+EMAIL                           SALARY
+```
+
+You can also provide context path as additional parameter for list and describe:
+```
+HR.EMPLOYEES $ l .SYS.DUAL
+DUMMY
+```
+
+For list provide filter as last segment of the path:
+```
+~ $ l .HR.EMPLOYEES.*NAME
+FIRST_NAME                      LAST_NAME
+```
+
+Note: `l` is aliased as `ls`. `d` is aliased as `desc` and `describe`.
+
+### SQL
+
+Any input starting with SQL keyword like `SELECT`, `INSERT`, `CREATE`, ... is recognized as SQL and passed to database
+for execution.
+
+### Context-aware SQL
+
+When in specific context, you can omit some obvious parts of SQL statements. For example, in context of a table following
+statements will work:
+```
+~.SOME_TABLE $ SELECT;                  # implicit '... FROM SOME_TABLE'
+~.SOME_TABLE $ WHERE col = 1;           # implicit 'SELECT * FROM SOME_TABLE ...'
+~.SOME_TABLE $ SET col = 2;             # implicit 'UPDATE SOME_TABLE ...'
+~.SOME_TABLE $ ADD x INTEGER;           # implicit 'ALTER TABLE SOME_TABLE ...'
+```
+
+Some other examples:
+```
+~ $ IDENTIFIED BY oraora;               # implicit 'ALTER USER xxx ...'
+~.SOME_TABLE.COL $ WHERE x = 1;         # implicit 'SELECT COL FROM SOME_TABLE ...'
+~.SOME_TABLE.COL $ RENAME TO kol;       # implicit 'ALTER TABLE SOME_TABLE RENAME COLUMN col TO kol'
+```
+
+### Su / sudo
+
+`su` and `sudo` allow to switch to SYS session temporarily or execute a single statement as SYS, similarly to their
+unix counterparts. If you don't have SYS password for current connection in orafile, you will be prompted for it.
+```
+$ oraora foo@DB
+~ $ SELECT * FROM boo.test;
+ERROR: Insufficient privileges
+~ $ sudo GRANT SELECT ON boo.test TO foo;
+Grant succeeded.
+~ $ SELECT * FROM boo.test;
+text
+------------
+Hello world!
+```
+
+## Limitations
+
+This is an early alpha version. Things may crash and bugs are hiding out there.
+
+PL/SQL blocks are not supported (yet).
+
+Oraora does not implement SQL*Plus-specific commands. `rem`, `set`, `show`, `desc`, `exec`, etc. are not
+supported.

data/bin/oraora

@@ -0,0 +1,48 @@
+#!/usr/bin/env ruby
+
+require 'oraora'
+require 'optparse'
+require 'logger'
+
+begin
+  # Options
+  options = { log_level: Logger::INFO }
+
+  OptionParser.new do |opts|
+    opts.banner = "Usage: oraora [options] connection"
+
+    opts.on("-l LEVEL", "--log-level=LEVEL", [:debug, :info, :warn, :error], "Set message verbosity (debug, info, warn, error)") do |l|
+      options[:log_level] = Logger.const_get(l.upcase)
+    end
+
+    opts.on("-h", "--help", "Show this message") { |h| puts opts; exit }
+  end.parse!
+
+  # Logger
+  logger = Oraora::Logger.new(STDOUT, options[:log_level])
+
+  # Read passfile
+    if File.file?(passfile = ENV['HOME'] + '/.orapass')
+      ok = Oraora::Credentials.read_passfile(passfile)
+      logger.warn "There were invalid entries in orapass file, which were ignored" if !ok
+    end
+
+  # Command line arguments
+  credentials = Oraora::Credentials.parse(ARGV[0])
+  credentials.fill_password_from_vault
+  role = ARGV[2] if ARGV[1] == 'as'
+
+  # Run application
+  app = Oraora::App.new(credentials, role, logger)
+  app.run
+
+rescue OptionParser::ParseError => e
+  puts "Options error: " + e.message
+
+rescue Oraora::Credentials::ParseError => e
+  puts "Invalid connection string: " + e.message
+
+rescue OCIError => e
+  logger.error "#{e.message}"
+
+end

data/lib/oraora.rb

@@ -0,0 +1,9 @@
+require 'readline'
+require 'highline'
+require 'highline/import'
+require 'indentation'
+require 'bigdecimal'
+require 'colorize'
+require 'oci8'
+
+Dir[File.dirname(__FILE__) + '/oraora/**/*.rb'].each { |file| require file }

data/lib/oraora/app.rb

@@ -0,0 +1,298 @@
+module Oraora
+  class App
+    class InvalidCommand < StandardError; end
+
+    SQL_INITIAL_KEYWORDS = %w(
+      SELECT COUNT FROM PARTITION WHERE CONNECT GROUP MODEL UNION INTERSECT MINUS ORDER
+      INSERT UPDATE SET DELETE MERGE
+      TRUNCATE ADD DROP CREATE RENAME ALTER PURGE GRANT REVOKE
+      COMPILE ANALYZE COMMIT ROLLBACK
+      IDENTIFIED PROFILE ACCOUNT QUOTA DEFAULT TEMPORARY
+    )
+    SQL_KEYWORDS = SQL_INITIAL_KEYWORDS + %w(
+      TABLE VIEW MATERIALIZED COLUMN PROCEDURE FUNCTION PACKAGE TYPE BODY
+      USER SESSION SCHEMA SYSTEM DATABASE
+      REPLACE AND OR
+    )
+    ORAORA_KEYWORDS = %w(c cd l ls d desc describe x exit su sudo - -- --- . ! /)
+
+    attr_reader :meta, :context
+
+    def initialize(credentials, role, logger, context = nil)
+      @credentials = credentials
+      @user, @database, @role = (credentials.user ? credentials.user.upcase : nil), credentials.database, (role ? role.upcase.to_sym : nil)
+      @logger = logger
+      @context = context
+    end
+
+    # Run the application with given credentials
+    def run(command = nil)
+      last_interrupt = Time.now - 2
+
+      # Connect to Oracle
+      @logger.debug "Connecting: #{@credentials}" + (@role ? " as #{@role}" : '')
+      logon
+      @user ||= @oci.username
+      @context ||= Context.new(@user, schema: @user)
+
+      # Readline tab completion
+      Readline.completion_append_character = ''
+      Readline.completion_proc = Completion.new(self).comp_proc
+
+      if command
+        process(command)
+      else
+        # Main loop
+        buffer = ''
+        prompt = @context.prompt + ' ' + (@role== :SYSDBA ? '#' : '$') + ' '
+
+        while !@terminate do
+          begin
+            line = Readline.readline(prompt.green.bold)
+            break if !line
+
+            line.strip!
+            Readline::HISTORY << line if line != '' # Manually add to history to avoid empty lines
+            buffer += (buffer == '' ? '' : "\n") + line
+
+            # Process buffer on one of these conditions:
+            # * This is first line of the buffer and is empty
+            # * This is first line of the buffer and is a Oraora command
+            # * Entire buffer is a comment
+            # * Line is '/' or ends with ';'
+            if (buffer == line && (line =~ /^(#{ORAORA_KEYWORDS.collect { |k| Regexp.escape(k) }.join('|')})($|\s+)/i || line =~ /^\s*$/)) || line == '/' || line =~ /;$/ || buffer =~ /\A\s*--/ || buffer =~ /\A\s*\/\*.*\*\/\s*\Z/m
+              process(buffer)
+              buffer = ''
+            end
+
+            if buffer == ''
+              prompt = @context.prompt + ' ' + (@role == :SYSDBA ? '#' : '$') + ' '
+            else
+              prompt = @context.prompt.gsub(/./, ' ') + ' % '
+            end
+
+          rescue Interrupt
+            if Time.now - last_interrupt < 2
+              @logger.warn "Exit on CTRL+C, "
+              terminate
+            else
+              @logger.warn "CTRL+C, hit again within 2 seconds to quit"
+              buffer = ''
+              prompt = @context.prompt + ' ' + (@role == :SYSDBA ? '#' : '$') + ' '
+              last_interrupt = Time.now
+            end
+          end
+        end
+
+      end
+
+      if !@terminate
+        @logger.debug "Exiting on end of input"
+        terminate
+      end
+    end
+
+    private
+
+    # Logon to the server
+    def logon
+      begin
+        @oci = OCI.new(@user, @credentials.password, @database, @role)
+        @meta = Meta.new(@oci)
+      rescue Interrupt
+        @logger.warn "CTRL+C, aborting logon"
+        exit!
+      end
+    end
+
+    # Log off the server and terminate
+    def terminate
+      if @oci
+        @logger.debug "Logging off"
+        @oci.logoff
+      end
+      @terminate = true
+    rescue Interrupt
+      @logger.warn "Interrupt on logoff, force exit"
+      exit!
+    end
+
+    # Parse command options from arguments
+    # Returns options hash and the remaining argument untouched
+    def options_for(args)
+      options = {}
+      while (args =~ /^-[[:alnum:]]/) do
+        opts, args = args.split(/\s+/, 2)
+        @logger.debug "Raw options: #{opts}"
+        opts.gsub(/^-/, '').split('').each do |o|
+          options[o.downcase] = true
+        end
+      end
+      @logger.debug "Options: #{options}"
+      [options, args]
+    end
+
+    # Process the command buffer
+    def process(text)
+      @logger.debug "Processing buffer: #{text}"
+
+      # shortcuts for '.' and '-'
+      text = 'c ' + text if text =~ /^\s*(\.|\-+)\s*$/
+
+      # Determine first non-comment word of a command
+      text =~ /\A(?:\/\*.*?\*\/\s*|--.*?(?:\n|\Z))*\s*([^[:space:]\*\(\/;]+)?\s*(.*?)(?:[[:space:];]*)\Z/mi
+      #          <------------- 1 --------------->    <--------- 2 -------->-   < 3 >
+      # 1) strip '/* ... */' or '--' style comments from the beginning
+      # 2) first word (any characters not being a space, '(', ';' or '*'), captured into $1
+      # 3) remaining portion of a command, captured into $2
+
+      case first_word = $1 && $1.upcase
+        # Nothing, gibberish or just comments
+        when nil
+          if $2 && $2 != ''
+            raise InvalidCommand, "Invalid command: #{$2}"
+          end
+
+        when 'C', 'CD'
+          @logger.debug "Switch context"
+          old_schema = @context.schema || @context.user
+          if $2 && $2 != ''
+            @context = context_for(@context, $2[/^\S+/])
+          else
+            @context.set(schema: @user)
+          end
+          @logger.debug "New context is #{@context.send(:key_hash)}"
+          if old_schema != (@context.schema || @context.user)
+            @logger.debug "Implicit ALTER SESSION SET CURRENT_SCHEMA = " + (@context.schema || @context.user)
+            @oci.exec("ALTER SESSION SET CURRENT_SCHEMA = " + (@context.schema || @context.user))
+          end
+
+        when 'L', 'LS'
+          @logger.debug "List"
+          options, path = options_for($2)
+          filter = path ? path[/[^\.\/]*(\*|\?)[^\.\/]*$/] : nil
+          path.chomp!(filter) if filter
+          path = path.chomp('.').chomp('/')[/^\S+/] unless path.nil? || path == '.' || path == '/'
+          filter.upcase! if filter
+          @logger.debug "Path: #{path}, Filter: #{filter}"
+          work_context = context_for(@context, path)
+          @logger.debug "List for #{work_context.level || 'database'}"
+          Terminal.puts_grid(@meta.find(work_context).list(options, filter))
+
+        when 'D', 'DESC', 'DESCRIBE'
+          @logger.debug "Describe"
+          options, args = options_for($2)
+          path = args.split(/\s+/).first rescue nil
+          work_context = context_for(@context, path)
+          @logger.debug "Describe for #{work_context.level || 'database'}"
+          puts(@meta.find(work_context).describe(options))
+
+          # TODO: For refactoring
+          if work_context.level == :column && options['p']
+            prof = @oci.exec <<-SQL
+              SELECT value, cnt, rank
+                FROM (SELECT value, cnt, row_number() over (order by cnt desc) AS rank
+                        FROM (SELECT #{work_context.column} AS value, count(*) AS cnt
+                                FROM #{work_context.object}
+                               GROUP BY #{work_context.column}
+                             )
+                     )
+                WHERE rank <= 20 OR value IS NULL
+                ORDER BY rank
+            SQL
+            puts ""
+            Terminal.puts_cursor(prof)
+          end
+
+        # Exit
+        when 'X', 'EXIT'
+          @logger.debug "Exiting on exit command"
+          terminate
+
+        # SQL
+        when *SQL_INITIAL_KEYWORDS
+          raw_sql = text.gsub(/[;\/]\Z/, '')
+          @logger.debug "SQL: #{raw_sql}"
+          context_aware_sql = Awareness.enrich(raw_sql, @context)
+          @logger.debug "SQL (context-aware): #{context_aware_sql}" if context_aware_sql != raw_sql
+          res = @oci.exec(context_aware_sql)
+
+          if res.is_a? OCI8::Cursor
+            Terminal.puts_cursor(res)
+            @logger.info "#{res.row_count} row(s) selected"
+          else
+            @logger.info "#{res} row(s) affected"
+          end
+
+        when 'SU'
+          @logger.debug "Command type: su"
+          su
+
+        when 'SUDO'
+          @logger.debug "Command type: sudo (#{$2})"
+          raise InvalidCommand, "Command required for sudo" if $2.strip == ''
+          su($2)
+
+        when '!'
+          @logger.debug "Command type: metadata refresh"
+          @meta.purge_cache
+
+        # Unknown
+        else
+          raise InvalidCommand, "Invalid command: #{$1}"
+      end
+
+    rescue InvalidCommand, Meta::NotApplicable => e
+      @logger.error e.message
+    rescue Context::InvalidKey, Meta::NotExists => e
+      @logger.error "Invalid path"
+    rescue OCIError => e
+      @logger.error e.parse_error_offset ? "#{e.message} at #{e.parse_error_offset}" : e.message
+    rescue Interrupt
+      @logger.warn "Interrupted by user"
+    rescue StandardError => e
+      @logger.error "Internal error"
+      @logger.debug e.backtrace
+    end
+
+    # Returns new context relative to current one, traversing given path
+    def context_for(context, path)
+      return context.dup if !path || path == ''
+      new_context = context.dup
+      nodes = path.split(/[\.\/]/).collect(&:upcase) rescue []
+      return new_context.root if nodes.empty?
+      level = nodes[0] == '' ? nil : new_context.level
+
+      nodes.each_with_index do |node, i|
+        case
+          when i.zero? && node == '' then new_context.root
+          when i.zero? && node == '~' then new_context.set(schema: @user)
+          when node == '-' then new_context.up
+          when node == '--' then new_context.up.up
+          when node =~ /^-+$/ then new_context.up.up.up
+          else
+            raise Context::InvalidKey if node !~ /^[a-zA-Z0-9_\$]{,30}$/
+            case new_context.level
+              when nil
+                @meta.find(new_context.traverse(schema: node))
+              when :schema
+                o = @meta.find_object(new_context.schema, node)
+                new_context.traverse(object: node, object_type: o.type)
+              when :object
+                @meta.find(new_context.traverse(column: node))
+                #TODO: Subprograms
+              else raise Context::InvalidKey
+            end
+        end
+      end
+      new_context
+    end
+
+    # Gets SYS password either from orapass file or user input, then spawns subshell
+    def su(command = nil)
+      su_credentials = Credentials.new('sys', nil, @database).fill_password_from_vault
+      su_credentials.password = ask("SYS password: ") { |q| q.echo = '' } if !su_credentials.password
+      App.new(su_credentials, :SYSDBA, @logger, @context.su('SYS')).run(command)
+    end
+  end
+end