metabase_tarot 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: bd886182a092af7e593d482ddea5460b9e7197440a740cb364c09074f29ba7c3
+  data.tar.gz: 5974f750ce4309063b7e30ec19415ad855da958cd3fec0bc9b089ab7878791d5
+SHA512:
+  metadata.gz: cf750b934c4b05fa9d804b3bcfc84c0ebee5f1085c9280c653b668da45febd4fdd2ee0ac52303693d97bf78db84df62d05860c5fb520692f22e58aab18a75fb4
+  data.tar.gz: c6494b6d00ac88a3a9feb9f7020eb190c7b2356f659fbbfab93786ccd7da1254b4d301a670890c74510c223e14e74f05d09fe4b7cd8165b3f43e7ed95e7523e8

data/bin/tarot

@@ -0,0 +1,197 @@
+#!/usr/bin/env ruby
+require 'tarot'
+require 'fileutils'
+
+SUBCOMMAND_NAMES = %w[run columns new console]
+
+if ARGV.length == 0
+  puts "Tarot will give you the answer! But first you have to give tarot the question (#{SUBCOMMAND_NAMES.join(', ')})"
+  exit(1)
+end
+
+# https://stackoverflow.com/questions/16323571/measure-the-distance-between-two-strings-with-ruby
+def levenshtein_distance(s, t)
+  m = s.length
+  n = t.length
+  return m if n == 0
+  return n if m == 0
+  d = Array.new(m+1) {Array.new(n+1)}
+
+  (0..m).each {|i| d[i][0] = i}
+  (0..n).each {|j| d[0][j] = j}
+  (1..n).each do |j|
+    (1..m).each do |i|
+      d[i][j] = if s[i-1] == t[j-1] # adjust index into string
+                  d[i-1][j-1]       # no operation required
+                else
+                  [ d[i-1][j]+1,    # deletion
+                    d[i][j-1]+1,    # insertion
+                    d[i-1][j-1]+1,  # substitution
+                  ].min
+                end
+    end
+  end
+  d[m][n]
+end
+
+def pretty_print_databases
+  puts <<~TEXT
+    Available databases:
+    #{Tarot.database_names.join("\n")}
+  TEXT
+end
+
+def pretty_print_array(array)
+  array.each_slice(3) do |slice|
+    puts slice.map { |item| item.ljust(40) }.join
+  end
+end
+
+def demand_argument(index, name)
+  return ARGV[index] if ARGV.count > index
+
+  puts "Missing argument #{index}: #{name}"
+  exit(1)
+end
+
+def require_tarot_spec
+  path = "#{Dir.pwd}/tarot_spec.rb"
+  if !File.exist?("#{Dir.pwd}/tarot_spec.rb")
+    puts "No tarot_spec.rb found on #{Dir.pwd}. To create it on this directory, type: tarot new ."
+    exit(1)
+  end
+  require_relative path
+end
+
+def retrieve_database(database_name)
+  begin
+    database = Tarot.database(database_name)
+  rescue Tarot::DatabaseNotFound
+    pretty_print_databases
+    puts "\nNot found: #{database_name}"
+    did_you_mean(database_name, Tarot.database_names)
+    exit(1)
+  end
+end
+
+def sort_possibilities(input, possibilities)
+  possibilities.sort_by { |possibility| levenshtein_distance(input, possibility) }
+end
+
+def did_you_mean(input, possibilities)
+  return if possibilities.empty?
+
+  sorted_possibilities = sort_possibilities(input, possibilities)
+  closest_match = sorted_possibilities.first
+  distance = levenshtein_distance(input, closest_match)
+
+  return if distance > (input.length / 2)
+
+  puts "Did you mean?  #{closest_match}"
+end
+
+case ARGV[0]
+when 'run'
+  path = demand_argument(1, 'consultation')
+  require_tarot_spec()
+  require_relative "#{Dir.pwd}/consultations/#{path}"
+when 'new'
+  path = "#{Dir.pwd}/#{demand_argument(1, 'path')}"
+
+  if File.exist?("#{path}/tarot_spec.rb")
+    puts 'This already is a valid Tarot folder (tarot_spec.rb exists)'
+    exit(1)
+  end
+
+  FileUtils.mkdir_p(path)
+  File.open("#{path}/tarot_spec.rb", "w") do |file|
+    file.write(
+      <<~RUBY
+        require 'tarot'
+        include Tarot
+
+        Config.build do |config|
+          config.session_expire_days = 13
+          config.url = 'You have to configure the url!'
+          config.database_aliases = {
+            #   my_database: 'The name they actually use on metabase'
+          }
+        end
+      RUBY
+    )
+  end
+
+  File.open("#{path}/.gitignore", "w") do |file|
+    file.write(
+      <<~TEXT
+        .secret_token
+        consultations/
+      TEXT
+    )
+  end
+
+  File.open("#{path}/Gemfile", "w") do |file|
+  file.write(
+    <<~TEXT
+      source 'https://rubygems.org'
+
+      ruby '3.0.0'
+      gem 'metabase_tarot'
+    TEXT
+  )
+end
+
+  puts "New deck created! Remember to configure #{path}/tarot_spec.rb"
+when 'consultation'
+  input = demand_argument(1, 'consultation name')
+  filepath = "consultations/#{input}.rb"
+  FileUtils.mkdir_p(File.dirname(filepath))
+
+  File.open(filepath, "w") do |file|
+    file.write(
+      <<~RUBY
+        consultation(__FILE__) do
+          {
+            query: db('mydatabase').query!(
+              <<~SQL
+                SELECT *
+                FROM yourtablehere
+              SQL
+            )
+          }
+        end
+      RUBY
+    )
+  end
+when 'dbs'
+  require_tarot_spec
+  pretty_print_databases
+when 'cols'
+  require_tarot_spec
+  database_name = demand_argument(1, 'database name')
+  table_name = demand_argument(2, 'table name')
+  database = retrieve_database(database_name)
+  begin
+    query = database.query!("SELECT * FROM #{table_name} LIMIT 1")
+  rescue Tarot::QueryError => e
+    puts "Query for retrieving columns went wrong, probably the table '#{table_name}' does not exist:"
+    puts e
+    exit(1)
+  end
+  pretty_print_array(query.first.keys)
+when 'tables'
+  require_tarot_spec
+  database_name = demand_argument(1, 'database name')
+  database = retrieve_database(database_name)
+  tables = database.query!("SELECT table_name FROM INFORMATION_SCHEMA.TABLES WHERE TABLE_TYPE = 'BASE TABLE'")
+                   .map { |x| x.values.first }
+                   .reject { |x| x.start_with?("pg_") || x.start_with?("sql_") }
+  pretty_print_array(tables)
+when 'console'
+  require_tarot_spec
+  Tarot.print_cheatsheet
+  binding.irb
+else
+  puts "Invalid command #{ARGV[0]}"
+  did_you_mean(ARGV[0], SUBCOMMAND_NAMES)
+end

data/lib/tarot.rb

@@ -0,0 +1,307 @@
+require 'uri'
+require 'net/http'
+require 'json'
+require 'io/console'
+require 'date'
+require 'yaml'
+
+# Módulo para interagir com a API do Metabase.
+module Tarot
+  # Exceção base do Tarot para suprimir backtracing.
+  class TarotError < StandardError
+    def backtrace
+    end
+  end
+
+  # Módulo para interagir com a configuração do tarot local do usuário.
+  module Config
+    # Exceção levantada quando a configuração do usuário (localizado na tarot_spec.rb) falha.
+    class ConfigError < TarotError
+    end
+
+    module_function
+    # Estrutura para representar uma configuração de usuário.
+    Data = Struct.new(:session_expire_days, :url, :database_aliases)
+
+    # Usa um bloco, normalmente definido na tarot_spec.rb, para popular as configurações de usuário.
+    #
+    # @example
+    # Config.build do |config|
+    #   config.session_expire_days = 13
+    #   config.url = 'https://metabase.mycompany.com'
+    #   config.database_aliases = {}
+    # end
+    #
+    # @yieldreturn [Hash] Bloco que recebe um Tarot::Config::Data e modifica seus valores.
+    # @return [void]
+    # @raise [ConfigError] Se alguma configuração estiver faltando após a execução do bloco.
+    def build(&block)
+      @data = Data.new()
+      block.call(@data)
+
+      if @data.session_expire_days.nil?
+        raise ConfigError, "Tarot config is missing 'session_expire_days'"
+      end
+
+      if @data.url.nil?
+        raise ConfigError, "Tarot config is missing 'url'"
+      end
+
+      if @data.database_aliases.nil?
+        raise ConfigError, "Tarot config is missing 'database_aliases'"
+      end
+
+      @data.session_expire_days.freeze
+      @data.url.freeze
+      @data.database_aliases.freeze
+
+      @built = true
+    end
+
+    # Retorna as configurações de usuário
+    # @return [Config::Data] Resultado da consulta.
+    # @raise [ConfigError] Se as configurações ainda não foram definidas via Config.build.
+    def data
+      return @data unless @built.nil?
+
+      raise ConfigError, 'Tarot is not properly configured, check tarot_spec.rb'
+    end
+  end
+
+  # Caminho para o arquivo que carrega o token de autenticação do usuário + a data de expiração do token
+  SECRET_TOKEN_PATH = "#{Dir.pwd}/.secret_token".freeze
+
+  # Exceção levantada quando a autenticação falha.
+  class LoginError < TarotError
+  end
+
+  # Exceção levantada quando uma database não é encontrada na API. Imprime na tela quais são as database disponíveis.
+  class DatabaseNotFound < TarotError
+  end
+
+  # Exceção levantada quando o endpoint de query retornou erros. Vem com informações sobre o erro que ocorreu, caso a API disponibilize.
+  class QueryError < TarotError
+  end
+
+  # Estrutura para representar uma database na API.
+  Database = Struct.new(:id, :name) do
+    def inspect
+      "<Metabase::Database id=#{id.inspect}, name=#{name.inspect}>"
+    end
+
+    def to_s
+      "'#{name}'(id #{id})"
+    end
+
+    # Mesmo que Tarot.query!(esse_banco, sql)
+    # Executa uma consulta SQL e retorna o resultado. Levanta erro conforme resposta da API.
+    # @param sql [String] Consulta SQL a ser executada.
+    # @return [Object] Resultado da consulta.
+    # @raise [QueryError] Se ocorrer um erro na consulta.
+    def query!(sql)
+      Tarot.query!(self, sql)
+    end
+
+    # Mesmo que Tarot.query(esse_banco, sql)
+    # Executa uma consulta SQL e retorna o resultado.
+    # @param sql [String] Consulta SQL a ser executada.
+    # @return [Object] Resultado da API contendo a resposta da consulta ou um JSON com os erros que ocorreram.
+    def query(sql)
+      Tarot.query(self, sql)
+    end
+  end
+
+  module_function
+
+  # Grava os resultados de um bloco em um arquivo YAML com o mesmo nome passado pelo argumento filepath (porém terminando em .yaml), incluindo metadados de quando foi gerado, e do script que gerou o arquivo.
+  #
+  # @example
+      # exemplos/test.rb
+  #   consultation(__FILE__) do
+  #     db('minha db').query!('SELECT * FROM plans WHERE id = 3;')
+  #   end
+  #   # Isto irá criar um arquivo 'exemplos/test.yaml' com os resultados do bloco e metadados.
+  #
+  # @param filepath [String] Caminho do arquivo de origem, cujo conteúdo será usado nos metadados. É esperado que se preencha com __FILE__.
+  # @yieldreturn [Hash] Bloco que retorna um hash com os dados a serem gravados.
+  # @return [void]
+  def consultation(filepath, &block)
+    target_file = filepath.gsub(/\.rb\z/, '.yaml')
+
+    File.write(target_file, YAML.dump({
+      metadata: {
+        generated_at: DateTime.now.iso8601,
+        generated_by: File.read(filepath)
+      },
+      results: block.call()
+    }))
+    puts "Recorded #{target_file}"
+  end
+
+  # Encontra uma database pelo nome/alias.
+  # @param name [String] Nome ou alias da database.
+  # @return [Database] A database encontrada.
+  # @raise [DatabaseNotFound] Se a database não for encontrada.
+  def database(name)
+    if Config.data.database_aliases.keys.include?(name.to_sym)
+      name = Config.data.database_aliases[name.to_sym]
+    end
+
+    result = databases.find { |d| d.name == name }
+
+    unless result
+      message = <<~TEXT
+
+        Database not found: #{name}
+        To see available databases, run: tarot dbs
+      TEXT
+
+      raise DatabaseNotFound, message
+    end
+
+    result
+  end
+
+  alias db database
+
+  # Retorna uma lista do nome de todos os nomes de databases disponíveis. Caso exista um alias para um nome, ele substituirá o nome.
+  # @return [String] String com o nomes das databases.
+  def database_names
+    names = Tarot.databases.map(&:name)
+    aliases = Tarot::Config.data.database_aliases.keys.map(&:to_s)
+
+    names.filter! do |name|
+      !Tarot::Config.data.database_aliases.values.include?(name)
+    end
+
+    (names + aliases)
+  end
+
+  # Retorna uma lista de todas as databases disponíveis.
+  # @return [Array<Database>] Array de objetos Database.
+  def databases
+    unless @databases
+      uri = URI.parse("#{Config.data.url}/api/database")
+      http = Net::HTTP.new(uri.hostname, uri.port)
+      http.use_ssl = true
+
+      request = Net::HTTP::Get.new(uri)
+      request['Accept'] = 'application/json'
+      request['X-Metabase-Session'] = fetch_token
+
+      response = http.request(request)
+      @databases = JSON.parse(response.body).map do |payload|
+        Database.new(payload['id'], payload['name'])
+      end
+    end
+    @databases
+  end
+
+  # Executa uma consulta SQL e retorna o resultado. Levanta erro conforme resposta da API.
+  # @param database [Database] Base de dados onde executar a consulta.
+  # @param sql [String] Consulta SQL a ser executada.
+  # @return [Object] Resultado da consulta.
+  # @raise [QueryError] Se ocorrer um erro na consulta.
+  def query!(database, sql)
+    result = query(database, sql)
+    raise QueryError, result['error'] if result.is_a?(Hash) && result['error']
+
+    result
+  end
+
+  # Executa uma consulta SQL e retorna o resultado.
+  # @param database [Database] Base de dados onde executar a consulta. Use Tarot.database('minah db') para conseguir esse objeto.
+  # @param sql [String] Consulta SQL a ser executada.
+  # @return [Object] Resultado da API contendo a resposta da consulta ou um JSON com os erros que ocorreram.
+  def query(database, sql)
+    uri = URI.parse("#{Config.data.url}/api/dataset/json")
+    http = Net::HTTP.new(uri.hostname, uri.port)
+    http.use_ssl = true
+
+    request = Net::HTTP::Post.new(uri,
+     'Accept' => 'application/json',
+     'X-Metabase-Session' => fetch_token
+    )
+    request.content_type = 'application/x-www-form-urlencoded'
+
+    params = {
+      'query': JSON.dump({
+        'type' => 'native',
+        'database' => database.id,
+        'parameters' => [],
+        'native' => {
+          'query' => sql,
+          'template-tags' => {}
+        },
+      })
+    }
+    request.body = URI.encode_www_form(params)
+    response = http.request(request)
+    JSON.parse(response.body) rescue response.body
+  end
+
+  # Limpa o token de sessão, armazenado localmente.
+  def clear_token
+    File.write(SECRET_TOKEN_PATH, '{}')
+  end
+
+  # Imprime a cheatsheet na tela
+  def print_cheatsheet
+    puts <<~TEXT
+                                      Tarot Cheatsheet
+
+        ┌─────────────────────────┬────────────────────────────────────────────────────┐
+        │ Ver databases           │ puts database_names                                │
+        │ Puxar database por nome | db('nome')                                         │
+        │ Fazer query             │ minha_db.query!('SELECT * FROM mytable')           │
+        │ Limpar dados de sessão  │ clear_token                                        │
+        │ Ver essa mensagem       │ print_cheatsheet                                   │
+        └─────────────────────────┴────────────────────────────────────────────────────┘
+    TEXT
+  end
+
+  # Obtém o token de sessão do Metabase, solicitando ao usuário se necessário.
+  # @return [String] Token de sessão.
+  def fetch_token
+    token_json = File.exist?(SECRET_TOKEN_PATH) ? JSON.load(File.read(SECRET_TOKEN_PATH)) : {}
+    token = token_json['token']
+
+    if token.nil?
+      uri = URI("#{Config.data.url}/api/session")
+      http = Net::HTTP.new(uri.hostname, uri.port)
+      http.use_ssl = true
+
+      request = Net::HTTP::Post.new(uri, 'Content-Type' => 'application/json')
+      login = {}
+      puts 'Login to Metabase'
+      print 'Username: '
+      login['username'] = STDIN.gets.chomp
+      print 'Password: '
+      login['password'] = STDIN.noecho(&:gets).chomp
+      puts "\n\n"
+
+      request.body = JSON.dump(login)
+      begin
+        response = http.request(request)
+      rescue OpenSSL::SSL::SSLError
+        puts "#{Config.data.url} seems to be unreachable at the moment"
+      end
+
+      token = JSON.parse(response.body)['id']
+
+      raise(LoginError, 'Wrong credentials') if token.nil?
+
+      File.write(SECRET_TOKEN_PATH, JSON.dump(token: token, expire_at: DateTime.now + Config.data.session_expire_days))
+      puts 'Authorized! :>'
+    else
+      expire_at = DateTime.parse(token_json['expire_at'])
+      if DateTime.now >= expire_at
+        puts 'Your token expired'
+        clear_token
+        fetch_token
+      end
+    end
+
+    token
+  end
+end

metadata

@@ -0,0 +1,45 @@
+--- !ruby/object:Gem::Specification
+name: metabase_tarot
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Hikari Luz
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2024-02-22 00:00:00.000000000 Z
+dependencies: []
+description: Utility tool for connecting directly to Metabase via its API
+email: hikaridesuyoo@gmail.com
+executables:
+- tarot
+extensions: []
+extra_rdoc_files: []
+files:
+- bin/tarot
+- lib/tarot.rb
+homepage: 
+licenses:
+- GPL-3.0
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.2.3
+signing_key: 
+specification_version: 4
+summary: Want to know something from Metabase? Tarot will give you the answer!
+test_files: []