wowsql-sdk 1.3.0 → 3.0.1

data/lib/wowsql/schema.rb

@@ -0,0 +1,250 @@
+require 'faraday'
+require 'json'
+require_relative 'exceptions'
+
+module WOWSQL
+  # Schema management client for PostgreSQL.
+  #
+  # Requires a SERVICE ROLE key (wowsql_service_...), not an anonymous key.
+  #
+  # @example
+  #   schema = WOWSQL::WOWSQLSchema.new(
+  #     "myproject",
+  #     "wowsql_service_..."
+  #   )
+  #   schema.create_table("users", [
+  #     { "name" => "id", "type" => "SERIAL", "auto_increment" => true },
+  #     { "name" => "email", "type" => "VARCHAR(255)", "unique" => true, "nullable" => false },
+  #     { "name" => "name", "type" => "VARCHAR(255)" },
+  #     { "name" => "metadata", "type" => "JSONB", "default" => "'{}'" },
+  #     { "name" => "created_at", "type" => "TIMESTAMPTZ", "default" => "CURRENT_TIMESTAMP" },
+  #   ], primary_key: "id", indexes: ["email"])
+  class WOWSQLSchema
+    attr_reader :base_url
+
+    # @param project_url [String] Project subdomain or full URL
+    # @param service_key [String] Service role key (wowsql_service_...)
+    # @param base_domain [String] Base domain (default: "wowsql.com")
+    # @param secure [Boolean] Use HTTPS (default: true)
+    # @param timeout [Integer] Request timeout in seconds (default: 30)
+    # @param verify_ssl [Boolean] Verify SSL certificates (default: true)
+    def initialize(project_url, service_key, base_domain: 'wowsql.com', secure: true,
+                   timeout: 30, verify_ssl: true)
+      if project_url.start_with?('http://') || project_url.start_with?('https://')
+        base = project_url.chomp('/')
+        base = base.split('/api').first if base.include?('/api')
+        @base_url = base
+      else
+        protocol = secure ? 'https' : 'http'
+        if project_url.include?(".#{base_domain}") || project_url.end_with?(base_domain)
+          @base_url = "#{protocol}://#{project_url}"
+        else
+          @base_url = "#{protocol}://#{project_url}.#{base_domain}"
+        end
+      end
+
+      @timeout = timeout
+
+      ssl_options = verify_ssl ? {} : { verify: false }
+
+      @conn = Faraday.new(url: @base_url, ssl: ssl_options) do |f|
+        f.request :json
+        f.response :json
+        f.adapter Faraday.default_adapter
+        f.options.timeout = timeout
+      end
+
+      @conn.headers['Authorization'] = "Bearer #{service_key}"
+      @conn.headers['Content-Type'] = 'application/json'
+    end
+
+    # ── Table operations ─────────────────────────────────────────
+
+    # Create a new table.
+    #
+    # @param table_name [String] Name of the table
+    # @param columns [Array<Hash>] Column definitions (name, type, auto_increment, unique, nullable, default)
+    # @param primary_key [String, nil] Primary key column name
+    # @param indexes [Array<String>, nil] Columns to create indexes on
+    # @return [Hash]
+    def create_table(table_name, columns, primary_key: nil, indexes: nil)
+      request('POST', '/api/v2/schema/tables', nil, {
+        table_name: table_name,
+        columns: columns,
+        primary_key: primary_key,
+        indexes: indexes
+      })
+    end
+
+    # Alter an existing table.
+    #
+    # Operations: add_column, drop_column, modify_column, rename_column
+    #
+    # @param table_name [String] Table name
+    # @param operation [String] Operation type
+    # @param column_name [String, nil] Column name
+    # @param column_type [String, nil] Column type
+    # @param new_column_name [String, nil] New column name (for rename)
+    # @param nullable [Boolean] Whether column is nullable
+    # @param default [String, nil] Default value
+    # @return [Hash]
+    def alter_table(table_name, operation, column_name: nil, column_type: nil,
+                    new_column_name: nil, nullable: true, default: nil)
+      request('PATCH', "/api/v2/schema/tables/#{table_name}", nil, {
+        table_name: table_name,
+        operation: operation,
+        column_name: column_name,
+        column_type: column_type,
+        new_column_name: new_column_name,
+        nullable: nullable,
+        default: default
+      })
+    end
+
+    # Drop a table. WARNING: This cannot be undone!
+    #
+    # @param table_name [String] Table to drop
+    # @param cascade [Boolean] Also drop dependent objects
+    # @return [Hash]
+    def drop_table(table_name, cascade: false)
+      request('DELETE', "/api/v2/schema/tables/#{table_name}", { 'cascade' => cascade }, nil)
+    end
+
+    # Execute raw DDL SQL.
+    #
+    # Only schema statements are allowed: CREATE TABLE, ALTER TABLE,
+    # DROP TABLE, CREATE INDEX, DROP INDEX, etc.
+    #
+    # @param sql [String] DDL SQL statement
+    # @return [Hash]
+    def execute_sql(sql)
+      request('POST', '/api/v2/schema/execute', nil, { sql: sql })
+    end
+
+    # ── Convenience methods ──────────────────────────────────────
+
+    # Add a column to an existing table.
+    #
+    # @param table_name [String] Table name
+    # @param column_name [String] Column name
+    # @param column_type [String] Column type
+    # @param nullable [Boolean] Whether column is nullable
+    # @param default [String, nil] Default value
+    # @return [Hash]
+    def add_column(table_name, column_name, column_type, nullable: true, default: nil)
+      alter_table(
+        table_name, 'add_column',
+        column_name: column_name,
+        column_type: column_type,
+        nullable: nullable,
+        default: default
+      )
+    end
+
+    # Drop a column from a table.
+    #
+    # @param table_name [String] Table name
+    # @param column_name [String] Column name
+    # @return [Hash]
+    def drop_column(table_name, column_name)
+      alter_table(table_name, 'drop_column', column_name: column_name)
+    end
+
+    # Rename a column.
+    #
+    # @param table_name [String] Table name
+    # @param old_name [String] Current column name
+    # @param new_name [String] New column name
+    # @return [Hash]
+    def rename_column(table_name, old_name, new_name)
+      alter_table(
+        table_name, 'rename_column',
+        column_name: old_name,
+        new_column_name: new_name
+      )
+    end
+
+    # Change column type, nullability, or default value.
+    #
+    # @param table_name [String] Table name
+    # @param column_name [String] Column name
+    # @param column_type [String, nil] New column type
+    # @param nullable [Boolean, nil] New nullability
+    # @param default [String, nil] New default value
+    # @return [Hash]
+    def modify_column(table_name, column_name, column_type: nil, nullable: nil, default: nil)
+      kwargs = { column_name: column_name }
+      kwargs[:column_type] = column_type unless column_type.nil?
+      kwargs[:nullable] = nullable unless nullable.nil?
+      kwargs[:default] = default unless default.nil?
+      alter_table(table_name, 'modify_column', **kwargs)
+    end
+
+    # Create an index.
+    #
+    # @param table_name [String] Table to index
+    # @param columns [String, Array<String>] Column(s)
+    # @param unique [Boolean] Create a UNIQUE index
+    # @param name [String, nil] Custom index name
+    # @param using [String, nil] Index method (btree, hash, gin, gist)
+    # @return [Hash]
+    def create_index(table_name, columns, unique: false, name: nil, using: nil)
+      cols = columns.is_a?(Array) ? columns : [columns]
+      idx_name = name || "idx_#{table_name}_#{cols.join('_')}"
+      unique_kw = unique ? 'UNIQUE ' : ''
+      using_kw = using ? " USING #{using}" : ''
+      col_list = cols.map { |c| "\"#{c}\"" }.join(', ')
+      sql = "CREATE #{unique_kw}INDEX IF NOT EXISTS \"#{idx_name}\" ON \"#{table_name}\"#{using_kw} (#{col_list})"
+      execute_sql(sql)
+    end
+
+    # List all tables via the v2 REST API.
+    #
+    # @return [Array<String>]
+    def list_tables
+      resp = request('GET', '/api/v2/tables', nil, nil)
+      resp['tables'] || []
+    end
+
+    # Get column-level schema information for a table.
+    #
+    # @param table_name [String] Table name
+    # @return [Hash]
+    def get_table_schema(table_name)
+      request('GET', "/api/v2/tables/#{table_name}/schema", nil, nil)
+    end
+
+    # Close the HTTP connection.
+    def close
+      @conn.close if @conn.respond_to?(:close)
+    end
+
+    private
+
+    def request(method, path, params = nil, json = nil)
+      response = @conn.public_send(method.downcase, path) do |req|
+        req.params = params if params
+        req.body = json if json
+      end
+
+      if response.status == 403
+        raise SchemaPermissionError.new(
+          'Schema operations require a SERVICE ROLE key. ' \
+          'You are using an anonymous key which cannot modify database schema.',
+          403
+        )
+      end
+
+      if response.status >= 400
+        error_data = response.body.is_a?(Hash) ? response.body : {}
+        error_msg = error_data['detail'] || error_data['message'] ||
+                    "Request failed with status #{response.status}"
+        raise WOWSQLError.new(error_msg, response.status, error_data)
+      end
+
+      response.body
+    rescue Faraday::Error => e
+      raise WOWSQLError.new("Request failed: #{e.message}")
+    end
+  end
+end