rails_age 0.3.2 → 0.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dc953f22e786b1ce4280d8ced0bcb6ca768f89773c49a4ad0d7ddd3e3505e91e
-  data.tar.gz: fff1d2809ce6f439196bfbc8a50b7990453d17def541829ef332ee2711a7fd3a
+  metadata.gz: 03e419984be6f29b1da74d0de6e31ccb218ba966e3818537884fcff715024e02
+  data.tar.gz: cb5a30c1e17ee7bf30394691232e3185e317ef5e827ece3ab02ef7d14cb0aef5
 SHA512:
-  metadata.gz: e03cb391c29274953ab63badc3da19a9a965d53b23844086775d5668e61f32feba68605078b506c2a1ef8bde9d6627c67c087b7b1752acd2ccff681a55d4eec2
-  data.tar.gz: 6373605ea72f6d85babde6ba167135f3098bb6b04c60a56015a04670e48f40e452a2473ce974de2e5577d2930d267aff72e253fc0a1fe10f740def2b28c0cf1b
+  metadata.gz: 555b80c544a8d5217d5c40ef3f24c15cd8fbf0c13bf96d1445845d9afc21d5e2ab835a60ac678ba5177fa5562ef1b87d7f293226783c94f1470d8b64e7a56fd9
+  data.tar.gz: 303f2776ebc5320711f50ec54e9a136ba7d9727fcb28c8d0038ffdcb0edb94d6715b93f40598a70d3eb3b8f1405a05610a707458f91209288414f0a4a7251374

data/CHANGELOG.md

@@ -1,26 +1,58 @@
 # Change Log
 
-## VERSION 0.4.0 - 2024-xx-xx
+## VERSION 0.5.1 - 2024-xx-xx
 
-- **cypher**
+- **cypher queries** (like active record queries)
+  * schema override
   * query support
   * paths support
   * select attributes support
-- **Paths**
-  * ?
 
-## VERSION 0.3.4 - 2024-xx-xx
+## VERSION 0.5.0 - 2024-xx-xx
 
-- **Type Generators**
-  * add `rails generate apache_age:type`
-  * add `rails generate apache_age:node_type`
-  * add `rails generate apache_age:edge_type`
+- **Age Path**
 
-## VERSION 0.3.3 - 2024-xx-xx
+## VERSION 0.4.3 - 2024-xx-xx
+
+- **AGE Schema override**
+
+- **multiple AGE Schema**
+
+## VERSION 0.4.3 - 2024-xx-xx
+
+- **Edge Scaffold** (generates edge, type, view and controller)
+  * add `rails generate apache_age:edge_scaffold HasJob employee_role start_node:person end_node:company`
+
+## VERSION 0.4.2 - 2024-xx-xx
+
+- **Node Scaffold** (generates node, type, view and controller)
+  * add `rails generate apache_age:node_scaffold Person first_name last_name age:integer`
+
+## VERSION 0.4.2 - 2024-xx-xx
 
 - **Edge Generator**
-  * add `rails generate apache_age:edge` to create an edge model
+  * add `rails generate apache_age:edge HasPet owner_role` just a property
+  * add `rails generate apache_age:edge HasPet owner_role start_node:person end_node:pet`
+        with property and specified start-/end-nodes (person and pet nodes must have already been created)
+
+## VERSION 0.4.1 - 2024-06-15
+
+- **Installer**
+  * add optional: safe migrations with `bin/rails db:migrate` instead of using `bin/rails apache_age:migrate`
+    (install using `bin/rails apache_age:override_db_migrate`)
+
+## VERSION 0.4.0 - 2024-06-14
 
+Minor breaking change: type (:vertix) is now required in core for edges
+
+- **Installer**
+  * AGE types added to installer (with tests)
+
+- **Node Generator**
+  * add also creates node types (with tests)
+
+- **Apache AGE Migrate**
+  * add `bin/rails apache_age:migrate` runs `bin/rails db:migrate` followed by `bin/rails apache_age:config_schema` to fix the schema file after `bin/rails db:migrate`
 
 ## VERSION 0.3.2 - 2024-06-08
 
@@ -33,6 +65,7 @@
 
 - **Installer**
   * refactor into multiple independent tasks with tests
+
 - **Documentation**
   * updated README with additional information
   * added `db/structure.sql` config to README
@@ -41,6 +74,7 @@
 
 - **Edges**
   * `find_by(start_node:, :end_node:, properties:)` to find an edge with specific nodes & properties (deprecated `find_edge`)
+
 - **Installer** (`rails generate apache_age:install`)
   * copy Age PG Extenstion migration to `db/migrate`
   * run the AGE PG Migration
@@ -56,6 +90,7 @@ NOTE: the `rails generate apache_age:install` can be run at any time to repair t
   * add missing methods to use in rails controllers
   * validate edge start- & end-nodes are valid
   * add unique edge validations
+
 - **Nodes**
   * add missing methods to use in rails controllers
   * add unique node validations
@@ -67,9 +102,11 @@ Initial release has the following features:
 - **Nodes:**
   * `.create`, `.read`, `.update`, `.delete`, `.all`, `.find(by id)`, `.find_by(age_properties)`
   * verified with usage in a controller and views
+
 - **Edges:**
   *`.create`, `.read`, `.update`, `.delete`, `.all`, `.find(by id)`, `.find_by(age_properties)`
   * verified with usage in a controller and views
+
 - **Entities:**
   * `.all`, `.find(id)`, `.find_by(age_property)` use these when class, label, edge, node
 

data/README.md

@@ -12,371 +12,109 @@ Add this line to your application's Gemfile:
 gem "rails_age"
 ```
 
-### Quick Install
+## Quick Start
 
 using the installer, creates the migration to install age, runs the migration, and adjusts the schema file, and updates the `config/database.yml` file.
 
+setup (& Test) postgresql with AGE (using the docker version of AGE DB may be the easiest way to get started)
+using the docker version of AGE DB, you can confirm psql AGE with the following commands:
 ```bash
-$ bundle
-$ bin/rails apache_age:install
-$ git add .
-$ git commit -m "Add Apache Age to Rails"
-$ rails generate apache_age:node Company company_name
-$ rails generate apache_age:node Person first_name last_name age:integer
+psql -h localhost -p 5455 -U docker_username
+> CREATE EXTENSION IF NOT EXISTS age;
+> LOAD 'age';
+> SET search_path = ag_catalog, "$user", public;
+> SELECT create_graph('age_schema');
+> \q
 ```
 
-NOTE: it is important to commit the `db/schema.rb` to git because `rails db:migrate` inappropriately modifies the schema file (I haven't yet tested `db/structure.sql`).
-
-**You can run `bin/rails apache_age:install` at any time to repair the schema file as needed.**
-
-For now, if you are using `db/structure.sql` you will need to manually configure Apache Age (RailsAge) as described below.
-
-### Manual Install
-
-create a migration to add the Apache Age extension to your database
+create a new Rails app (WITH POSTGRESQL!)
 ```bash
-$ bin/rails g migration AddApacheAge
+rails new age_demo -d postgresql
+cd age_demo
+git add .
+git commit -m "Initial Rails App"
 ```
-copy the contents of https://github.com/marpori/rails_age/blob/main/db/migrate/20240521062349_add_apache_age.rb
-```ruby
-class AddApacheAge < ActiveRecord::Migration[7.1]
-  def up
-    # Allow age extension
-    execute('CREATE EXTENSION IF NOT EXISTS age;')
-
-    # Load the age code
-    execute("LOAD 'age';")
-
-    # Load the ag_catalog into the search path
-    execute('SET search_path = ag_catalog, "$user", public;')
-
-    # Create age_schema graph if it doesn't exist
-    execute("SELECT create_graph('age_schema');")
-  end
-
-  def down
-    execute <<-SQL
-      DO $$
-      BEGIN
-        IF EXISTS (
-          SELECT 1
-          FROM pg_constraint
-          WHERE conname = 'fk_graph_oid'
-        ) THEN
-          ALTER TABLE ag_catalog.ag_label
-          DROP CONSTRAINT fk_graph_oid;
-        END IF;
-      END $$;
-    SQL
-
-    execute("SELECT drop_graph('age_schema', true);")
-    execute('DROP SCHEMA IF EXISTS ag_catalog CASCADE;')
-    execute('DROP EXTENSION IF EXISTS age;')
-  end
-end
+configure `config/database.yml` when using the docker version of AGE DB my config looks like:
+```yaml
+port: 5455
+host: localhost
+username: docker_username
+password: dockerized_password
 ```
-into your new migration file
 
-then run the migration
+now you should be able to create the rails database:
 ```bash
-$ bin/rails db:migrate
-```
-
-Rails migrate will mangle the schema `db/schema.rb` file.  You need to remove the lines that look like:
-```ruby
-ActiveRecord::Schema[7.1].define(version: 2024_05_21_062349) do
-  create_schema "ag_catalog"
-  create_schema "age_schema"
-
-  # These are extensions that must be enabled in order to support this database
-  enable_extension "age"
-  enable_extension "plpgsql"
-
-  # Could not dump table "_ag_label_edge" because of following StandardError
-  #   Unknown type 'graphid' for column 'id'
-
-  # Could not dump table "_ag_label_vertex" because of following StandardError
-  #   Unknown type 'graphid' for column 'id'
-
-  # Could not dump table "ag_graph" because of following StandardError
-  #   Unknown type 'regnamespace' for column 'namespace'
-
-  # Could not dump table "ag_label" because of following StandardError
-  #   Unknown type 'regclass' for column 'relation'
-
-  add_foreign_key "ag_label", "ag_graph", column: "graph", primary_key: "graphid", name: "fk_graph_oid"
-
-  # other migrations
-  # ...
-end
-```
-
-and replace them with the following lines:
-```ruby
-ActiveRecord::Schema[7.1].define(version: 2024_05_21_062349) do
-  # These are extensions that must be enabled in order to support this database
-  enable_extension 'plpgsql'
-
-  # Allow age extension
-  execute('CREATE EXTENSION IF NOT EXISTS age;')
-
-  # Load the age code
-  execute("LOAD 'age';")
-
-  # Load the ag_catalog into the search path
-  execute('SET search_path = ag_catalog, "$user", public;')
-
-  # Create age_schema graph if it doesn't exist
-  execute("SELECT create_graph('age_schema');")
-
-  # other migrations
-  # ...
-end
+rails db:create
+rails db:migrate
+git add .
+git commit -m "Add Apache Age Postgres DB configured with Rails App"
 ```
 
-NOTE: if using `db/structure.sql` use:
-```sql
--- These are extensions that must be enabled in order to support this database
-CREATE EXTENSION IF NOT EXISTS plpgsql WITH SCHEMA public;
-
--- Allow age extension (if not already enabled), this builds the age_catalog schema
-CREATE EXTENSION IF NOT EXISTS age;
-
--- Load the age module
-LOAD 'age';
-
--- Load the ag_catalog into the search path
-SET search_path = ag_catalog, "$user", public;
-
--- Create age_schema graph if it doesn't exist
-SELECT create_graph('age_schema');
-
-# other migrations
-# ...
-
-INSERT INTO "schema_migrations" (version) VALUES
-('20110315075839'),
---- ...
-('20240521062349');
+install Apache Age (you can ignore the `unknown OID` warnings)
+```bash
+bundle add rails_age
+bundle install
+bin/rails apache_age:install
+git add .
+git commit -m "Add Apache Age to Rails"
 ```
 
-## Contributing
-
-Create an merge request (with tests) and I will review it/merge it when ready.
-
-## License
-
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
-
-## Usage
-
-I suggest you creat a folder create a folder called `app/nodes` and `app/edges` to keep the code organized.
-I frequently use the `app/graphs` folder to keep all the graph related code together in a Module (as is done in the [rails age demo app](https://github.com/marpori/rails_age_demo_app))
-
-I suggest you creat a folder within app called `graphs` and under that create a folder called `nodes` and `edges`. This will help you keep your code organized.
-
-A trival, but fully functional [rails age demo app](https://github.com/marpori/rails_age_demo_app), based on the Flintstones Commic, is available for reference.
-
-### Nodes
-
-```ruby
-# app/graphs/nodes/company.rb
-module Nodes
-  class Company
-    include ApacheAge::Entities::Vertex
-
-    attribute :company_name, :string
-
-    validates :company_name, presence: true
-    validates_with(
-      ApacheAge::Validators::UniqueVertexValidator,
-      attributes: [:company_name]
-    )
-  end
-end
+make some nodes :string is the default type
+```bash
+rails generate apache_age:node Company company_name
+rails generate apache_age:node Person first_name last_name
+rails generate apache_age:node Pet pet_name:string age:integer
 ```
+make some edges (`:vertex` is the default type) for start_node and end_node
+```bash
+# when start node and end node are not specified they are of type `:vertex`
+# this is generally not recommended - exept when very generic relationships are needed
+rails generate apache_age:edge HasJob employee_role
 
-```ruby
-# app/graphs/nodes/person.rb
-module Nodes
-  class Person
-    include ApacheAge::Entities::Vertex
-
-    attribute :first_name, :string, default: nil
-    attribute :last_name, :string, default: nil
-    attribute :given_name, :string, default: nil
-    attribute :nick_name, :string, default: nil
-
-    validates :first_name, :last_name, :given_name, :nick_name,
-              presence: true
-
-    def initialize(**attributes)
-      super
-      # use unless present? since attributes when empty sets to "" by default
-      self.nick_name = first_name unless nick_name.present?
-      self.given_name = last_name unless given_name.present?
-    end
-  end
-end
+# this is recommended - use explicit start_node and end_node types
+rails generate apache_age:node HasPet start_node:person end_node:pet caretaker_role
 ```
 
-### Edges
+**NOTE:** the default `rails db:migrate` inappropriately modifies the schema file. This installer patches the migration to prevent this (however this might break on rails updates, etc). **You can run `bin/rails apache_age:install` at any time to repair the schema file as needed.**
 
-```ruby
-# app/graphs/edges/has_job.rb
-module Edges
-  class HasJob
-    include ApacheAge::Entities::Edge
-
-    attribute :employee_role, :string
-    attribute :start_node, :person
-    attribute :end_node, :company
-
-    validates :employee_role, presence: true
-    validate :validate_unique
-    # or with a one-liner
-    # validates_with(
-    #   ApacheAge::Validators::UniqueEdgeValidator,
-    #   attributes: %i[employee_role start_node end_node]
-    # )
-
-    private
-
-    def validate_unique
-      ApacheAge::Validators::UniqueEdgeValidator
-        .new(attributes: %i[employee_role start_node end_node])
-        .validate(self)
-    end
-  end
-end
-```
+For now, if you are using `db/structure.sql` you will need to manually configure Apache Age (RailsAge) as described below.
 
 ### Rails Console Usage
 
 ```ruby
-fred = Nodes::Person.create(first_name: 'Fredrick Jay', nick_name: 'Fred', last_name: 'Flintstone', gender: 'male')
-fred.to_h
-
-quarry = Nodes::Company.create(company_name: 'Bedrock Quarry')
-quarry.to_h
-
-job = Edges::HasJob.create(start_node: fred, end_node: quarry, employee_role: 'Crane Operator')
-job.to_h
-```
-
-### Update Routes
-
-```ruby
-Rails.application.routes.draw do
-  # mount is not needed with the engine
-  # mount RailsAge::Engine => "/rails_age"
-
-  # defines the route for the people controller
-  resources :people
-
-  # Reveal health status on /up that returns 200 if the app boots with no exceptions, otherwise 500.
-  # Can be used by load balancers and uptime monitors to verify that the app is live.
-  get 'up' => 'rails/health#show', as: :rails_health_check
-
-  # Defines the root path route ("/")
-  root 'people#index'
-end
-```
-
-### Types (Optional)
-
-```ruby
-# spec/dummy/config/initializers/types.rb
-require 'apache_age/types/age_type_generator'
-
-Rails.application.config.to_prepare do
-  # Ensure the files are loaded
-  require_dependency 'nodes/company'
-  require_dependency 'nodes/person'
-
-  # Register the custom types
-  ActiveModel::Type.register(:company, ApacheAge::Types::AgeTypeGenerator.create_type_for(Nodes::Company))
-  ActiveModel::Type.register(:person, ApacheAge::Types::AgeTypeGenerator.create_type_for(Nodes::Person))
-end
-```
-
-### Controller Usage
-
-```ruby
-# app/controllers/people_controller.rb
-class PeopleController < ApplicationController
-  before_action :set_person, only: %i[show edit update destroy]
-
-  # GET /people or /people.json
-  def index
-    @people = Nodes::Person.all
-  end
-
-  # GET /people/1 or /people/1.json
-  def show; end
-
-  # GET /people/new
-  def new
-    @person = Nodes::Person.new
-  end
-
-  # GET /people/1/edit
-  def edit; end
-
-  # POST /people or /people.json
-  def create
-    @person = Nodes::Person.new(**person_params)
-    respond_to do |format|
-      if @person.save
-        format.html { redirect_to person_url(@person), notice: 'Person was successfully created.' }
-        format.json { render :show, status: :created, location: @person }
-      else
-        format.html { render :new, status: :unprocessable_entity }
-        format.json { render json: @person.errors, status: :unprocessable_entity }
-      end
-    end
-  end
-
-  # PATCH/PUT /people/1 or /people/1.json
-  def update
-    respond_to do |format|
-      if @person.update(**person_params)
-        format.html { redirect_to person_url(@person), notice: 'Person was successfully updated.' }
-        format.json { render :show, status: :ok, location: @person }
-      else
-        format.html { render :edit, status: :unprocessable_entity }
-        format.json { render json: @person.errors, status: :unprocessable_entity }
-      end
-    end
-  end
-
-  # DELETE /people/1 or /people/1.json
-  def destroy
-    @person.destroy!
-
-    respond_to do |format|
-      format.html { redirect_to people_url, notice: 'Person was successfully destroyed.' }
-      format.json { head :no_content }
-    end
-  end
-
-  private
-
-  # Use callbacks to share common setup or constraints between actions.
-  def set_person
-    @person = Nodes::Person.find(params[:id])
-  end
-
-  # Only allow a list of trusted parameters through.
-  def person_params
-    # params.fetch(:person, {})
-    params.require(:nodes_person).permit(:first_name, :last_name, :nick_name, :given_name, :gender)
-  end
-end
-```
-
-### Views
-
-```erb
-
-```
+bin/rails c
+
+fred = Person.new(first_name: 'Fredrick Jay', last_name: 'Flintstone')
+fred.valid?
+fred.save
+fred.to_h # should have an ID
+
+# fails because of a missing required field (Property)
+incomplete = Person.new(first_name: 'Fredrick Jay')
+incomplete.valid?
+incomplete.errors
+incomplete.to_h
+
+# fails because of uniqueness constraints
+jay = Person.create(first_name: 'Fredrick Jay', last_name: 'Flintstone')
+jay.to_h
+=> {:id=>nil, :first_name=>"Fredrick Jay", :last_name=>"Flintstone"}
+jay.valid?
+=> false
+jay.errors
+=> #<ActiveModel::Errors [#<ActiveModel::Error attribute=base, type=record not unique, options={}>, #<ActiveModel::Error attribute=first_name, type=property combination not unique, options={}>, #<ActiveModel::Error attribute=last_name, type=property combination not unique, options={}>]>
+irb(main):008> jav.to_h
+=> {:id=>nil, :first_name=>"Fredrick Jay", :last_name=>"Flintstone"}
+
+# .create is a shortcut for .new and .save
+quarry = Company.create(company_name: 'Bedrock Quarry')
+quarry.to_h # should have an ID
+
+# create an edge (no generator yet)
+job = HasJob.create(start_node: fred, end_node: quarry, employee_role: 'Crane Operator')
+job.to_h # should have an ID
+```
+
+## Manual Install, Config and Usage
+
+see [Manuel Installation, Configuration and Usage](MANUAL_INSTALL.md)

data/lib/apache_age/entities/edge.rb

@@ -11,9 +11,9 @@ module ApacheAge
         attribute :id, :integer
         attribute :end_id, :integer
         attribute :start_id, :integer
-        # allow user to optionally specify the class type (or not) thus not adding: `:vertex`
-        attribute :end_node
-        attribute :start_node
+        # type: `:vertex` can be overriden with a specific node type
+        attribute :end_node, :vertex
+        attribute :start_node, :vertex
 
         validates :end_node, :start_node, presence: true
         validate :validate_nodes

data/lib/apache_age/validators/unique_edge_validator.rb

@@ -35,10 +35,10 @@ module ApacheAge
         query = record.class.find_by(edge_attribs.compact)
         return if query.blank? || (query.id == record.id)
 
-        record.errors.add(:base, 'attribute combination not unique')
-        record.errors.add(:end_node, 'attribute combination not unique')
-        record.errors.add(:start_node, 'attribute combination not unique')
-        attributes.each { record.errors.add(_1, 'attribute combination not unique') }
+        record.errors.add(:base, 'record not unique')
+        record.errors.add(:end_node, 'node combination not unique')
+        record.errors.add(:start_node, 'node combination not unique')
+        attributes.each { record.errors.add(_1, 'prpoerty combination not unique') }
       end
 
       private

data/lib/apache_age/validators/unique_vertex_validator.rb

@@ -20,8 +20,8 @@ module ApacheAge
         # if no match is found or if it finds itself, it's valid
         return if query.blank?  || (query.id == record.id)
 
-        record.errors.add(:base, 'attribute combination not unique')
-        attributes.each { record.errors.add(_1, 'attribute combination not unique') }
+        record.errors.add(:base, 'record not unique')
+        attributes.each { record.errors.add(_1, 'property combination not unique') }
       end
     end
   end

data/lib/generators/apache_age/node/node_generator.rb

@@ -14,11 +14,13 @@ module ApacheAge
 
     def create_node_file
       template "node.rb.tt", File.join(destination_root, "app/nodes", class_path, "#{file_name}.rb")
+      add_type_config
     end
 
     def destroy_node_file
       file_path = File.join(destination_root, "app/nodes", class_path, "#{file_name}.rb")
       File.delete(file_path) if File.exist?(file_path)
+      remove_type_config
     end
 
     def attributes_list
@@ -52,5 +54,41 @@ module ApacheAge
         "#{'  ' * (parent_module.split('::').length - 1 - index)}end"
       end.join("\n") + "\n"
     end
+
+    def add_type_config
+      return unless File.exist?(types_config_file)
+
+      types_content = File.read(types_config_file)
+      types_content.sub!(/^end\s*$/, "#{new_type_content}end")
+      File.open(types_config_file, 'w') { |file| file.write(types_content) }
+      puts "      modified: config/initializers/types.rb"
+    end
+
+    def remove_type_config
+      return unless File.exist?(types_config_file)
+
+      type_to_remove = new_type_content
+
+      types_content = File.read(types_config_file)
+      types_content.gsub!(type_to_remove, '')
+      File.open(types_config_file, 'w') { |file| file.write(types_content) }
+    end
+
+    def types_config_file = File.join(Rails.root, 'config/initializers/types.rb')
+
+    def new_type_content
+      file_path = [class_path, file_name].reject(&:blank?).join('/').downcase
+      node_namespace = class_path.map(&:capitalize).join('::')
+      node_class_name = file_name.split('_').map(&:capitalize).join
+      node_namespaced_class = [node_namespace, node_class_name].reject(&:blank?).join('::')
+      type_name = [class_path.join('_'), file_name].reject(&:blank?).join('_')
+      content =
+<<-RUBY
+  require_dependency '#{file_path}'
+  ActiveModel::Type.register(
+    :#{type_name}, ApacheAge::Types::AgeTypeGenerator.create_type_for(#{node_namespaced_class})
+  )
+RUBY
+    end
   end
 end

data/lib/rails_age/version.rb

@@ -1,3 +1,3 @@
 module RailsAge
-  VERSION = '0.3.2'
+  VERSION = '0.4.1'
 end

data/lib/tasks/add_age_migration.rake

@@ -0,0 +1,69 @@
+# lib/tasks/install.rake
+# Usage:
+# * `bin/rails apache_age:add_age_migration`
+# * `bin/rails  apache_age:add_age_migration[destination_path.to_s]`
+# * `bundle exec rails apache_age:add_age_migration.invoke(destination_path.to_s)`
+namespace :apache_age do
+  desc "Copy migrations from rails_age to application and update schema"
+  task :add_age_migration, [:destination_path] => :environment do |t, args|
+
+    base_name = 'add_apache_age'
+    destination_path =
+      File.expand_path(args[:destination_path].presence || "#{Rails.root}/db/migrate", __FILE__)
+
+    FileUtils.mkdir_p(destination_path) unless File.exist?(destination_path)
+    existing_migrations =
+      Dir.glob("#{destination_path}/*.rb").map { |file| File.basename(file).sub(/^\d+/, '') }
+
+    if existing_migrations.any? { |migration| migration.include?(base_name) }
+      puts "Skipping migration AddApacheAge, it already exists"
+    else
+      age_migration_contents =
+        <<~RUBY
+        class AddApacheAge < ActiveRecord::Migration[7.1]
+          def up
+            # Allow age extension
+            execute('CREATE EXTENSION IF NOT EXISTS age;')
+
+            # Load the age code
+            execute("LOAD 'age';")
+
+            # Load the ag_catalog into the search path
+            execute('SET search_path = ag_catalog, "$user", public;')
+
+            # Create age_schema graph if it doesn't exist
+            execute("SELECT create_graph('age_schema');")
+          end
+
+          def down
+            execute <<-SQL
+              DO $$
+              BEGIN
+                IF EXISTS (
+                  SELECT 1
+                  FROM pg_constraint
+                  WHERE conname = 'fk_graph_oid'
+                ) THEN
+                  ALTER TABLE ag_catalog.ag_label
+                  DROP CONSTRAINT fk_graph_oid;
+                END IF;
+              END $$;
+            SQL
+
+            execute("SELECT drop_graph('age_schema', true);")
+            execute('DROP SCHEMA IF EXISTS ag_catalog CASCADE;')
+            execute('DROP EXTENSION IF EXISTS age;')
+          end
+        end
+        RUBY
+
+      migration_version = Time.now.utc.strftime("%Y%m%d%H%M%S")
+      file_version = migration_version.delete('_')
+      new_filename = "#{file_version}_#{base_name}.rb"
+      destination_file = File.join(destination_path, new_filename)
+
+      File.write(destination_file, age_migration_contents)
+      puts "Created migration AddApacheAge"
+    end
+  end
+end

data/lib/tasks/{database_config.rake → config_database.rake}

@@ -3,7 +3,7 @@
 #
 namespace :apache_age do
   desc "Ensure the database.yml file is properly configured for Apache Age"
-  task :database_config => :environment do
+  task :config_database => :environment do
 
     db_config_file = File.expand_path("#{Rails.root}/config/database.yml", __FILE__)
 

data/lib/tasks/{schema_config.rake → config_schema.rake}

@@ -3,8 +3,7 @@
 #
 namespace :apache_age do
   desc "Copy migrations from rails_age to application and update schema"
-  task :schema_config => :environment do
-    # source_schema = File.expand_path('../../../db/schema.rb', __FILE__)
+  task :config_schema => :environment do
     destination_schema = File.expand_path("#{Rails.root}/db/schema.rb", __FILE__)
 
     unless File.exist?(destination_schema)

data/lib/tasks/config_types.rake

@@ -0,0 +1,85 @@
+# lib/tasks/install.rake
+# Usage: `rake apache_age:config_types`
+#
+namespace :apache_age do
+  desc "Install AGE types from rails_age into the rails initializers"
+  task :config_types => :environment do
+    types_file_path = File.expand_path("#{Rails.root}/config/initializers/types.rb", __FILE__)
+    required_file_path = "require 'apache_age/types/age_type_generator'"
+    required_file_content =
+      <<~RUBY
+      require 'apache_age/types/age_type_generator'
+      # AGE Type Definition Usage (edges/nodes):
+      # require_dependency 'nodes/company'
+      # ActiveModel::Type.register(
+      #   :company, ApacheAge::Types::AgeTypeGenerator.create_type_for(Nodes::Company)
+      # )
+      RUBY
+    node_type_content =
+<<-RUBY
+  require_dependency 'apache_age/entities/vertex'
+  ActiveModel::Type.register(
+    :vertex, ApacheAge::Types::AgeTypeGenerator.create_type_for(ApacheAge::Entities::Vertex)
+  )
+RUBY
+    edge_type_content =
+<<-RUBY
+  require_dependency 'apache_age/entities/edge'
+  ActiveModel::Type.register(
+    :edge, ApacheAge::Types::AgeTypeGenerator.create_type_for(ApacheAge::Entities::Edge)
+  )
+RUBY
+
+    unless File.exist?(types_file_path)
+      source_content =
+        <<~RUBY
+        # config/initializers/types.rb
+
+        #{required_file_content}
+        Rails.application.config.to_prepare do
+          # Register AGE types
+        #{node_type_content}
+        #{edge_type_content}
+        end
+        RUBY
+      File.open(types_file_path, 'w') { |file| file.write(source_content) }
+      puts "config/initializers/types.rb file created with AGE base types"
+    else
+      destination_content = File.read(types_file_path)
+      original_content = destination_content.dup
+
+      unless destination_content.include?(required_file_path)
+        destination_content.sub!(
+          /^(\s*Rails\.application\.config\.to_prepare do\n)/,
+          "#{required_file_content}\n\\1"
+        )
+      end
+
+      unless destination_content.include?('# Register AGE types')
+        destination_content.sub!(
+          /^(\s*Rails\.application\.config\.to_prepare do\n)/,
+          "\\1  # Register AGE types\n"
+        )
+      end
+
+      unless destination_content.include?(edge_type_content)
+        destination_content.sub!(
+          /^(\s*Rails\.application\.config\.to_prepare do\n  # Register AGE types\n)/,
+          "\\1#{edge_type_content}"
+        )
+      end
+
+      unless destination_content.include?(node_type_content)
+        destination_content.sub!(
+          /^(\s*Rails\.application\.config\.to_prepare do\n  # Register AGE types\n)/,
+          "\\1#{node_type_content}"
+        )
+      end
+
+      if destination_content != original_content
+        File.open(types_file_path, 'w') { |file| file.write(destination_content) }
+        puts "modified: config/initializers/types.rb"
+      end
+    end
+  end
+end

data/lib/tasks/install.rake

@@ -4,16 +4,19 @@
 namespace :apache_age do
   desc "Install & configure Apache Age within Rails (updates migrations, schema & database.yml)"
   task :install => :environment do
-    # copy our migrations to the application (if needed)
-    Rake::Task["apache_age:copy_migrations"].invoke
+    # Ensure the AGE migration is in place
+    Rake::Task["apache_age:add_age_migration"].invoke
 
     # run any new migrations
     Rake::Task["db:migrate"].invoke
 
+    # ensure the config/database.yml file has the proper configurations
+    Rake::Task["apache_age:config_database"].invoke
+
     # adjust the schema file (unfortunately rails mangles the schema file)
-    Rake::Task["apache_age:schema_config"].invoke
+    Rake::Task["apache_age:config_schema"].invoke
 
-    # ensure the config/database.yml file has the proper configurations
-    Rake::Task["apache_age:database_config"].invoke
+    # ensure the config/initializers/types.rb file has the base AGE Types
+    Rake::Task["apache_age:config_types"].invoke
   end
 end

data/lib/tasks/migrate.rake

@@ -0,0 +1,7 @@
+namespace :apache_age do
+  desc "Ensure 'db:migrate' is followed by 'apache_age:config_schema' to repair 'schema.rb' after migrations"
+  task :migrate do
+    Rake::Task['db:migrate'].invoke
+    Rake::Task["apache_age:config_schema"].invoke
+  end
+end

data/lib/tasks/override_db_migrate.rake

@@ -0,0 +1,50 @@
+namespace :apache_age do
+  desc "Ensure 'db:migrate' is followed by 'apache_age:config_schema' to repair the schema.rb file after migration mangles it."
+  task :override_db_migrate, [:destination_path] => :environment do |t, args|
+    destination_path = (args[:destination_path].presence || "#{Rails.root}") + "/bin"
+    FileUtils.mkdir_p(destination_path) unless File.exist?(destination_path)
+    bin_rails_path = File.expand_path("#{destination_path}/rails", __FILE__)
+
+    original_content = File.read(bin_rails_path)
+    destination_content = original_content.dup
+
+    unless destination_content.include?("#!/usr/bin/env ruby\nrails_cmd = ARGV.first")
+      capture_rails_cmd =
+        <<~RUBY
+        rails_cmd = ARGV.first # must be first (otherwise consumed by rails:commands)
+        RUBY
+
+      # add to the top of the file (with gsub)
+      destination_content.sub!(
+        %r{#!/usr/bin/env ruby\n},
+        "#!/usr/bin/env ruby\n#{capture_rails_cmd}\n"
+      )
+    end
+
+    # Check if the migration hook is already present
+    unless destination_content.include?('Rake::Task["apache_age:config_schema"].invoke')
+      override_migrate =
+        <<~RUBY
+
+        # ensure db:migrate is followed with: `Rake::Task["apache_age:config_schema"].invoke`
+        # to the schema.rb file after the migration mangles it
+        if rails_cmd == 'db:migrate'
+          require 'rake'
+          Rails.application.load_tasks
+          Rake::Task['db:migrate'].invoke
+          Rake::Task["apache_age:config_schema"].invoke
+        end
+        RUBY
+
+      # append to the end of the file
+      destination_content << override_migrate
+    end
+
+    if destination_content == original_content
+      puts "AGE Safe Migration is already present in bin/rails. (If its not working inspect the bin/rails file)"
+    else
+      File.write(bin_rails_path, destination_content)
+      puts "AGE Safe Migration added to bin/rails. Now run `bin/rails db:migrate`, then run your tests (or inspect the schema.rb file)."
+    end
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rails_age
 version: !ruby/object:Gem::Version
-  version: 0.3.2
+  version: 0.4.1
 platform: ruby
 authors:
 - Bill Tihen
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-06-08 00:00:00.000000000 Z
+date: 2024-06-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -85,11 +85,13 @@ files:
 - lib/rails_age.rb
 - lib/rails_age/engine.rb
 - lib/rails_age/version.rb
-- lib/tasks/copy_migrations.rake
-- lib/tasks/database_config.rake
-- lib/tasks/install.original.rake
+- lib/tasks/add_age_migration.rake
+- lib/tasks/config_database.rake
+- lib/tasks/config_schema.rake
+- lib/tasks/config_types.rake
 - lib/tasks/install.rake
-- lib/tasks/schema_config.rake
+- lib/tasks/migrate.rake
+- lib/tasks/override_db_migrate.rake
 homepage: https://github.com/marpori/rails_age
 licenses:
 - MIT

data/lib/tasks/copy_migrations.rake

@@ -1,33 +0,0 @@
-# lib/tasks/install.rake
-# Usage:
-# * `bin/rails apache_age:copy_migrations`
-# * `bundle exec rails apache_age:copy_migrations[destination_path.to_s]`
-# * `bundle exec rails apache_age:copy_migrations.invoke(destination_path.to_s)`
-namespace :apache_age do
-  desc "Copy migrations from rails_age to application and update schema"
-  task :copy_migrations, [:destination_path] => :environment do |t, args|
-    source = File.expand_path('../../../db/migrate', __FILE__)
-    destination_path =
-      File.expand_path(args[:destination_path].presence || "#{Rails.root}/db/migrate", __FILE__)
-
-    FileUtils.mkdir_p(destination_path) unless File.exist?(destination_path)
-    existing_migrations =
-      Dir.glob("#{destination_path}/*.rb").map { |file| File.basename(file).sub(/^\d+/, '') }
-
-    Dir.glob("#{source}/*.rb").each do |file|
-      filename = File.basename(file)
-      test_name = filename.sub(/^\d+/, '')
-
-      if existing_migrations.include?(test_name)
-        puts "Skipping migration: '#{filename}', it already exists"
-      else
-        migration_version = Time.now.utc.strftime("%Y_%m_%d_%H%M%S")
-        file_version = migration_version.delete('_')
-        new_filename = filename.sub(/^\d+/, file_version)
-        destination_file = File.join(destination_path, new_filename)
-        FileUtils.cp(file, destination_file)
-        puts "Created migration: '#{new_filename}'"
-      end
-    end
-  end
-end

data/lib/tasks/install.original.rake

@@ -1,257 +0,0 @@
-# lib/tasks/install.rake
-# Usage: `rake apache_age:install`
-#
-namespace :apache_age do
-  desc "Install & configure Apache Age within Rails (updates migrations, schema & database.yml)"
-  task :install_old => :environment do
-    source_schema = File.expand_path('../../../db/schema.rb', __FILE__)
-    destination_schema = File.expand_path("#{Rails.root}/db/schema.rb", __FILE__)
-    source_migrations = File.expand_path('../../../db/migrate', __FILE__)
-    destination_migrations = File.expand_path("#{Rails.root}/db/migrate", __FILE__)
-    # create the migrations folder if needed
-    FileUtils.mkdir_p(destination_migrations) unless File.exist?(destination_migrations)
-    original_migrations =
-      Dir.glob("#{destination_migrations}/*.rb").map { |file| File.basename(file).sub(/^\d+/, '') }
-
-    # # check if the schema is non-existent or blank (NEW) we need to know how to handle schema
-    # is_schema_blank = !File.exist?(destination_schema) || blank_schema?(destination_schema)
-    # puts "Schema is blank: #{is_schema_blank}"
-
-    # ensure we have a schema file
-    unless File.exist?(destination_schema)
-      run_db_create
-      run_db_migrate
-    end
-
-    # copy our migrations to the application (last_migration_version is nil if no migration necessary)
-    # last_migration_version = copy_migrations
-    Rake::Task["apache_age:copy_migrations"].invoke
-
-    updated_migrations =
-      Dir.glob("#{destination_migrations}/*.rb").map { |file| File.basename(file).sub(/^\d+/, '') }
-
-    # # run our new migrations (unless we have not added any new migrations)
-    # if original_migrations == updated_migrations
-    #   puts "no new migrations were copied, skipping migrations"
-    # else
-    #   puts "added Apache Age migrations, running migrations"
-    #   run_db_migrate
-    # end
-    run_db_migrate
-
-    # adjust the schema file (unfortunately rails mangles the schema file)
-    # if is_schema_blank
-    #   puts "creating new schema..."
-    #   create_new_schema(last_migration_version, destination_schema, source_schema)
-    # else
-    #   puts "updating existing schema..."
-    #   update_existing_schema(last_migration_version, destination_schema, source_schema)
-    # end
-    Rake::Task["apache_age:schema_config"].invoke
-
-    # ensure the config/database.yml file has the proper configurations
-    # update_database_yml
-    Rake::Task["apache_age:database_config"].invoke
-  end
-
-  def run_db_create
-    puts "Running db:create..."
-    Rake::Task["db:create"].invoke
-  end
-
-  def run_db_migrate
-    puts "Running db:migrate..."
-    Rake::Task["db:migrate"].invoke
-  end
-
-  def copy_migrations
-    migration_version = nil
-
-    source = File.expand_path('../../../db/migrate', __FILE__)
-    destination = File.expand_path("#{Rails.root}/db/migrate", __FILE__)
-
-    FileUtils.mkdir_p(destination) unless File.exist?(destination)
-    existing_migrations =
-      Dir.glob("#{destination}/*.rb").map { |file| File.basename(file).sub(/^\d+/, '') }
-
-    Dir.glob("#{source}/*.rb").each do |file|
-      filename = File.basename(file)
-      test_name = filename.sub(/^\d+/, '')
-
-      if existing_migrations.include?(test_name)
-        puts "Skipping #{filename}, it already exists"
-      else
-        migration_version = Time.now.utc.strftime("%Y_%m_%d_%H%M%S")
-        file_version = migration_version.delete('_')
-        new_filename = filename.sub(/^\d+/, file_version)
-        destination_file = File.join(destination, new_filename)
-        FileUtils.cp(file, destination_file)
-        puts "Copied #{filename} to #{destination} as #{new_filename}"
-      end
-    end
-    migration_version
-  end
-
-  def blank_schema?(destination_schema)
-    return false unless File.exist?(destination_schema)
-
-    content = File.read(destination_schema)
-    content.include?('define(version: 0)') &&
-      (content.include?("enable_extension 'plpgsql'") || content.include?('enable_extension "plpgsql"')) &&
-      content.scan(/enable_extension/).size == 1
-  end
-
-  def schema_rails_version(destination_schema)
-    if File.exist?(destination_schema)
-      content = File.read(destination_schema)
-      version_match = content.match(/ActiveRecord::Schema\[(.*?)\]/)
-      return version_match[1] if version_match
-    else
-      full_version = Rails.version
-      primary_secondary_version = full_version.split('.')[0..1].join('.')
-      primary_secondary_version
-    end
-  end
-
-  def create_new_schema(last_migration_version, destination_schema, source_schema)
-    if File.exist?(source_schema) && File.exist?(destination_schema)
-      rails_version = schema_rails_version(destination_schema)
-      source_content = File.read(source_schema)
-
-      # ensure we use the Rails version from the destination schema
-      source_content.gsub!(
-        /ActiveRecord::Schema\[\d+\.\d+\]/,
-        "ActiveRecord::Schema[#{rails_version}]"
-      )
-      # ensure we use the last migration version (not the source schema version)
-      source_content.gsub!(
-        /define\(version: \d{4}(?:_\d{2}){2}(?:_\d{6})?\) do/,
-        "define(version: #{last_migration_version}) do"
-      )
-
-      File.write(destination_schema, source_content)
-      puts "Created new schema in #{destination_schema} with necessary extensions and configurations."
-    else
-      puts "local db/schema.rb file not found."
-    end
-  end
-
-  def update_existing_schema(last_migration_version, destination_schema, source_schema)
-    if File.exist?(source_schema) && File.exist?(destination_schema)
-      rails_version = schema_rails_version(destination_schema)
-      source_content = File.read(source_schema)
-      new_content =
-        source_content.gsub(
-          /.*ActiveRecord::Schema\[\d+\.\d+\]\.define\(version: \d{4}(?:_\d{2}){2}(?:_\d{6})?\) do\n|\nend$/,
-          ''
-        )
-
-      destination_content = File.read(destination_schema)
-
-      # Remove unwanted schema statements
-      destination_content.gsub!(%r{^.*?create_schema "ag_catalog".*?\n}, '')
-      destination_content.gsub!(%r{^.*?create_schema "age_schema".*?\n}, '')
-      destination_content.gsub!(%r{^.*?enable_extension "age".*?\n}, '')
-      destination_content.gsub!(%r{^.*?enable_extension "plpgsql".*?\n}, '')
-      destination_content.gsub!(%r{^.*?# Could not dump table "ag_graph" because of following StandardError.*?\n}, '')
-      destination_content.gsub!(%r{^.*?#   Unknown type 'regnamespace' for column 'namespace'.*?\n}, '')
-      destination_content.gsub!(%r{^.*?# Could not dump table "ag_label" because of following StandardError.*?\n}, '')
-      destination_content.gsub!(%r{^.*?#   Unknown type 'regclass' for column 'relation'.*?\n}, '')
-      destination_content.gsub!(%r{^.*?#   Unknown type 'graphid' for column 'id'.*?\n}, '')
-      destination_content.gsub!(
-        %r{^.*?# Could not dump table "_ag_label_edge" because of following StandardError.*?\n}, ''
-      )
-      destination_content.gsub!(
-        %r{^.*?# Could not dump table "_ag_label_vertex" because of following StandardError.*?\n}, ''
-      )
-      destination_content.gsub!(%r{^.*?# Could not dump table "ag_graph" because of following StandardError.*?\n}, '')
-      destination_content.gsub!(%r{^.*?# Could not dump table "ag_label" because of following StandardError.*?\n}, '')
-      destination_content.gsub!(%r{^.*?add_foreign_key "ag_label", "ag_graph".*?\n}, '')
-
-      # add new wanted schema statements (at the top of the schema)
-      unless destination_content.include?(%{execute("LOAD 'age';")}) &&
-             destination_content.include?(%{enable_extension 'plpgsql'}) &&
-             destination_content.include?(%{execute("SELECT create_graph('age_schema');")}) &&
-             destination_content.include?(%{execute('CREATE EXTENSION IF NOT EXISTS age;')}) &&
-             destination_content.include?(%{execute('SET search_path = ag_catalog, "$user", public;')})
-        # if not all are found then remove any found
-        destination_content.gsub!(%r{^.*?execute("LOAD 'age';")*?\n}, '')
-        destination_content.gsub!(%r{^.*?enable_extension 'plpgsql'*?\n}, '')
-        destination_content.gsub!(%r{^.*?execute("SELECT create_graph('age_schema');")*?\n}, '')
-        destination_content.gsub!(%r{^.*?execute('CREATE EXTENSION IF NOT EXISTS age;')*?\n}, '')
-        destination_content.gsub!(%r{^.*?execute('SET search_path = ag_catalog, "$user", public;')*?\n}, '')
-        destination_content.gsub!(%r{^.*?# Allow age extension*?\n}, '')
-        destination_content.gsub!(%r{^.*?# Load the ag_catalog into the search path*?\n}, '')
-        destination_content.gsub!(%r{^.*?# Create age_schema graph if it doesn't exist*?\n}, '')
-        destination_content.gsub!(%r{^.*?# These are extensions that must be enabled in order to support this database*?\n}, '')
-
-        # add all of the correct settings back in
-        destination_content.sub!(
-          %r{(ActiveRecord::Schema\[\d+\.\d+\]\.define\(version: \d{4}(?:_\d{2}){2}(?:_\d{6})?\) do\n)},
-          "\\1#{new_content}\n"
-        )
-          puts 'db/schema.rb has been updated with the necessary configuration.'
-      else
-        puts 'db/schema.rb has the necessary configuration, no adjustments necessary'
-      end
-
-      existing_version = destination_content.match(/define\(version: (\d{4}(?:_\d{2}){2}(?:_\d{6})?)\)/)[1].gsub('_', '')
-      current_version = last_migration_version ? last_migration_version.gsub('_', '') : existing_version
-
-      # ensure we use the last migration version (not the source schema version)
-      if current_version.to_i > existing_version.to_i
-        destination_content.gsub!(
-          /define\(version: \d{4}(?:_\d{2}){2}(?:_\d{6})?\) do/,
-          "define(version: #{last_migration_version}) do"
-        )
-        puts "Updated schema version to the migration version #{last_migration_version}"
-      end
-
-      File.write(destination_schema, destination_content)
-      puts "Updated #{destination_schema} with necessary extensions and configurations."
-    else
-      puts "local db/schema.rb file not found."
-    end
-  end
-
-  def update_database_yml
-    db_config_file = File.expand_path("#{Rails.root}/config/database.yml", __FILE__)
-
-    # Read the file
-    lines = File.readlines(db_config_file)
-
-    # any uncommented "schema_search_path:" lines?
-    path_index = lines.find_index { |line| !line.include?('#') && line.include?('schema_search_path:') }
-    default_start_index = lines.index { |line| line.strip.start_with?('default:') }
-
-    # when it finds an existing schema_search_path, it updates it
-    if path_index && lines[path_index].include?('ag_catalog,age_schema')
-      puts "schema_search_path already set to ag_catalog,age_schema nothing to do."
-      return
-    elsif path_index
-      key, val = lines[path_index].split(': ')
-      # remove any unwanted characters
-      val = val.gsub(/[ "\s\"\"'\n]/, '')
-      lines[path_index] = "#{key}: ag_catalog,age_schema,#{val}\n"
-      puts "add ag_catalog,age_schema to schema_search_path"
-    elsif default_start_index
-      puts "add ag_catalog,age_schema,public to schema_search_path in the default section of database.yml"
-      sections_index = lines.map.with_index { |line, index| index if !line.start_with?(' ') }.compact.sort
-
-      # find the start of the default section
-      next_section_in_list = sections_index.index(default_start_index) + 1
-
-      # find the end of the default section (before the next section starts)
-      path_insert_index = sections_index[next_section_in_list]
-
-      lines.insert(path_insert_index, "  schema_search_path: ag_catalog,age_schema,public\n")
-    else
-      puts "didn't find a default section in database.yml, please add the following line:"
-      puts "  schema_search_path: ag_catalog,age_schema,public"
-      puts "to the apprpriate section of your database.yml"
-    end
-
-    # Write the modified lines back to the file
-    File.open(db_config_file, 'w') { |file| file.write(lines.join) }
-  end
-end