rails_age 0.3.1 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 272f8908dc8fb8a98adb443411e4b439eff914c8173b5eb64b53fa5362fa1572
-  data.tar.gz: bf1921611698ffc1b651787f2e1b1a5d1bc503cbe1300639b2f9dada8202cdde
+  metadata.gz: 8228c60b43732a31b364b658e65b5d6a2e1b76018b573b1ec5b7fa25582f519c
+  data.tar.gz: 60f5211cb37aa6605523f76cde81158b6495448e90d4fbeabecd020c38520c4e
 SHA512:
-  metadata.gz: 51592c31e872a9b8dc6e96fe8fa42374241496e4da6a17ce70bf63f5f118ac078e81200259c048529e7e16b2147c8c5bbef00315cee8f26237295d04ffaea887
-  data.tar.gz: 0b24560f7703e4dc4f97d3d36de626906a47a2cda5f5137cc6c1840a5281bbcf2693743666fb6301b26723c9723244bd1854c9c8b21d5d657eb621d4caf0d864
+  metadata.gz: eec16e9c7b4512793b4aac9a3ac1c9ee0ce6280a1033712cc6aed5466218ffa17a47c1fca4d1f4d0508ce38e4a12a9a0c392d927f72a62c5ebcf8d2ea7c343f5
+  data.tar.gz: 3ccdeba21d32bc35de9162698c5c340efce5b0557b5930a3b1e0d9caaf5697f5afcd2b39ad65d0c976b5b3bc46df5edaf18a7bb96e023a2090642b08eb002786

data/CHANGELOG.md

@@ -1,21 +1,64 @@
 # Change Log
 
-## VERSION 0.4.0 - 2024-xx-xx
+## VERSION 0.5.0 - 2024-xx-xx
+
+- **AGE Schema override** (instance and class methods) assumes db and migrations up-to-date
 
 - **cypher**
+  * schema override
   * query support
   * paths support
   * select attributes support
+
 - **Paths**
-  * ?
 
-## VERSION 0.3.1 - 2024-xx-xx
+## VERSION 0.4.4 - 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.3 - 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 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-xx-xx
+
+- **OPTIONAL Installer**
+  * add `config_migrate` to `rails generate apache_age:install` auto fix the schema after `rails 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
+
+- **Node Generator**
+  * add `rails generate apache_age:node Pets/Cat name age:integer` creates a node with a namespace and attributes at: `app/nodes/pets/cat.rb`
+  * add `rails generate apache_age:node Cat name age:integer` creates a node with attributes at:  `app/nodes/cat.rb`
+  * add `rails destroy apache_age:node Cat` deletes an existing node at: `app/nodes/cat.rb`
+
+## VERSION 0.3.1 - 2024-06-02
 
-- **Generators**
-  * add `rails generate apache_age:node` to create a node model (with its type in initializer)
-  * add `rails generate apache_age:edge` to create an edge model (with its type in initializer)
 - **Installer**
   * refactor into multiple independent tasks with tests
+
 - **Documentation**
   * updated README with additional information
   * added `db/structure.sql` config to README
@@ -24,6 +67,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
@@ -39,6 +83,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
@@ -50,9 +95,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,368 +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"
+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
-    attribute :gender, :string, default: nil
-
-    validates :gender, :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
-
-```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]
-    # )
+**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.**
 
-    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/edge/USAGE

@@ -0,0 +1,54 @@
+Description:
+    This creates Apache AGE nodes that work seamlessly with Rails.
+    A node can be created with or without a namespace.
+    See the below examples.
+
+Example:
+    `bin/rails g apache_age:node Cat name age:integer`
+
+    This creates:
+        `app/nodes/cat.rb`
+
+    with the contents:
+        ```
+        class Cat
+          include ApacheAge::Entities::Vertex
+
+          attribute :name, :string
+          attribute :age, :integer
+
+          validates :name, presence: true
+          validates :age, presence: true
+
+          # unique node validator (remove any attributes that are not important to uniqueness)
+          validates_with(
+            ApacheAge::Validators::UniqueVertexValidator,
+            attributes: [:name, :age]
+          )
+        end
+        ```
+
+    A namespace can also be used:
+        `bin/rails g apache_age:node Animals/Cat name age:integer`
+
+    This creates:
+        `app/nodes/animals/cat.rb`
+
+    with the contents
+        ```
+        class Animals::Cat
+          include ApacheAge::Entities::Vertex
+
+          attribute :name, :string
+          attribute :age, :integer
+
+          validates :name, presence: true
+          validates :age, presence: true
+
+          # unique node validator (remove any attributes that are not important to uniqueness)
+          validates_with(
+            ApacheAge::Validators::UniqueVertexValidator,
+            attributes: [:name, :age]
+          )
+        end
+        ```