Apache AGE
Apache AGE is a PostgreSQL extension that provides graph database functionality. The goal of Apache AGE is to enable users of Postgres to use graph query modeling in unison with Postgres’ existing relational model.
Apache AGE is a Top-Level Project of the Apache Software Foundation since May 2022. It is licensed under the Apache License 2.0.
Below is a brief overview of the AGE architecture in relation to the PostgreSQL architecture and backend.
Every component runs on the PostgreSQL transaction cache layer and storage layer.
Features
- AGE is currently being developed for the PostgreSQL 11 release and will support PostgreSQL 12 and 13 in Q3 and PostgreSQL 14 in Q4 2022.
- AGE supports the openCypher graph query language and label hierarchy.
- AGE enables querying multiple graphs at the same time. This will allow a user to query two or more graphs at once with cypher, decide how to merge them and get the desired query outputs.
- AGE will be enhanced with an aim to support all of the key features of AgensGraph (PostgreSQL fork extended with graph DB functionality).
License
Roadmap
v0.1.0-alpha ✅ | |
Release Date | 2020 Q1 |
Release Notes | https://github.com/apache/incubator-age/releases/tag/v0.1.0 |
Key Improvements |
|
v0.2.0-alpha ✅ | |
Release Date | 2020 Q2 |
Release Notes | https://github.com/apache/incubator-age/releases/tag/v0.2.0 |
Key Improvements |
|
v0.3.0-incubating (official Apache incubator release) ✅ | |
Release Date | 2021-FEB-19 |
Release Notes | https://github.com/apache/incubator-age/releases/tag/v0.3.0.rc0-incubating |
Key Improvements |
|
v0.4.0-incubating (official Apache incubator release) ✅ | |
Release Date | 2021-MAY-03 |
Release Notes | https://github.com/apache/incubator-age/releases/tag/0.4.0 |
Key Improvements |
|
v0.5.0-incubating (official Apache incubator release) ✅ | |
Release Date | 2021-AUG-03 |
Release Notes | https://github.com/apache/incubator-age/releases/tag/v0.5.0 |
Key Improvements |
|
v0.6.0-incubating (official Apache incubator release) ✅ | |
Release Date | 2021-DEC-01 |
Release Notes | https://github.com/apache/incubator-age/releases/tag/v0.6.0 |
Key Improvements |
|
v0.7.0-incubating (official Apache incubator release) ✅ | |
Release Date | 2022-FEB-01 |
Release Notes | https://github.com/apache/incubator-age/releases/tag/v.0.7.0-rc0 |
Key Improvements |
|
AGE Viewer v1.0.0-incubating (official Apache incubator release) ✅ | |
Release Date | 2022-APR-05 |
Release Notes | https://github.com/apache/incubator-age-viewer/releases/tag/v1.0.0-rc2 |
Key Improvements |
|
v1.0.0-incubating (official Apache incubator release) ✅ | |
Release Date | 2022-APR-21 |
Release Notes | https://github.com/apache/incubator-age/releases/tag/v1.0.0-rc1 |
Key Improvements |
|
* PostgreSQL 12 support will be implemented in Q2 2022.
Installing AGE
Using Docker
Installing from source
Getting Started
Loading AGE
Using AGE
How to contribute
Becoming a Committer
Contributing by Helping Other Users
Contributors should subscribe to this list and follow it to keep up to date on what's happening in AGE. Answering questions is an excellent and visible way to help the community, which also demonstrates your expertise.
Contributing by Reviewing Changes
Contributing Documentation Changes
Contributing Bug Reports
Bug reports are only useful, however, if they include enough information to understand, isolate and ideally reproduce the bug. Simply encountering an error does not mean a bug should be reported; search JIRA and inquire on the AGE user / dev mailing lists first. Unreproducible bugs, or simple error reports, may be closed.
The more context the reporter can give about a bug, the better, such as: how the bug was introduced, by which commit, etc. It assists the committers in the decision process on how far the bug fix should be backported, when the pull request is merged. The pull request to fix the bug should narrow down the problem to the root cause.
Data correctness/data loss bugs are very serious. Make sure the corresponding bug report JIRA issue is labeled as correctness or data-loss. Please send an email to dev@age.apache.org after submitting the bug report, to quickly draw attention to the issue.
Performance issues are classified as bugs. The pull request to fix a performance bug must provide a benchmark to prove the problem is indeed fixed.
Contributing to JIRA Maintenance
When resolving JIRA tickets, please observe the following conventions:
-
Resolve as Fixed if there's a release or code commit that resolved the issue.
- Set Fix Version(s), if and only if the resolution is Fixed
- Set Assignee to the person who contributed the most to its resolution, usually the person who opened the PR that resolved the issue.
- For issues that can't be reproduced against master as reported, resolve as Cannot Reproduce.
-
If the issue is the same as or a subset of another issue, resolved as Duplicate
- Mark the issue that has less activity or discussion as the duplicate.
- Link it to the JIRA ticket it duplicates.
- If the issue seems clearly obsolete and applies to issues or components that have changed radically since it was opened, resolve as Not a Problem
- If the issue doesn't make sense or is not actionable resolve as Invalid.
- If it's a coherent issue, but there is a clear indication that there is no support or interest in acting on it, then resolve as Won't Fix.
Searching JIRA How to search JIRA for existing issues:
- Basic:
- Visit AGE JIRA
- Type query into search box in top right (beware this will return results from all projects)
-
Advanced:
- Visit AGE JIRA Advanced Search
- Replace the empty quotes with quoted text (such as "cypher")
-
Search Now:
- Use the search box below
Creating a release
Update the Postgres version extension
Files to update:
Step 1 - Rename CREATE EXTENSION script name:
Rename age--Y.Y.Y.sql to age--X.X.X.sql
Step 2 - Update Makefile:
Update line 62 in Makefile from: DATA = age--Y.Y.Y.sql to: DATA age--X.X.X.sql
Step 3 - Update age.control:
Update line 18 in age.control from default_version = 'Y.Y.Y' to: default_version = 'X.X.X'
Step 4 Add Release Notes:
Update RELEASE with X.X.X release notes
Step 5 update documentation:
update line 46 in doc/conf.py:
from:
release = u'Y.Y.Y'
to:
release = u'X.X.X'
Creating a release branch
git branch release/X.X.X upstream/master
git checkout release/X.X.X
git push upstream release/X.X.X:release/X.X.X
Creating the release artifacts
git clone --depth 1 --branch X.X.X-rcX
https://github.com/apache/incubator-age.git apache-age-X.X.Xincubating
rm -rf apache-age-X.X.X-incubating/.git
tar -czvf apache-age-X.X.X-incubating-src.tar.gz apache-ageX.X.X-incubating
Sign the artifacts
gpg --armor --default-key username@apache.org --output apacheage-X.X.X-incubating-src.tar.gz.asc --detach-sig apache-ageX.X.X-incubating-src.tar.gz
sha512sum apache-age-X.X.X-incubating-src.tar.gz > apache-ageX.X.X-incubating-src.tar.gz.sha512
# Validate
gpg --verify apache-age-X.X.X-incubating-src.tar.gz.asc
sha512sum -c apache-age-X.X.X-incubating-src.tar.gz.sha512
Staging the files
svn co https://dist.apache.org/repos/dist/dev/incubator/age
age_release
cd age_release
svn mkdir apache-age-x.x.x-incubating-rcx
Now copy over the following files in this new directory
apache-age-X.X.X-incubating-src.tar.gz.sha512
apache-age-X.X.X-incubating-src.tar.gz.asc
apache-age-X.X.X-incubating-src.tar.gz
Add and commit the files to svn
svn add *
svn status
svn commit -m 'Add release files for Apache age X.XX-rcX'
Check if the files are uploaded here
Send a mail to dev list to announce new release candidate
Subject: [VOTE] Release Apache age (incubating) X.X.X-rcX
TO: dev@age.apache.org
Hi All,
[ INCLUDE SOME TEXT ]
Build instructions can be found in the README included.
The tag to be voted on is X.X.X-rcX [REPLACE TAG] (commit[COMMIT HASH]):
[ URL TO TAG COMMIT ]
The release files, including signatures, digests, etc. can be found at:
[ INCLUDE URL TO DIST RC FOLDER ]
https://dist.apache.org/repos/dist/dev/incubator/age/apacheage-X.X.X-incubating-rcX/
The SHA512 Checksum for these artifacts is:
[ INCLUDE CHECKSUM FROM SHA512 FILE ]
Release artifacts are signed with the following key:
[ ADD URL TO YOUR KEY ON A PUBLIC KEYSERVER ]
For more information about the contents of this release, see:
[ ADD URL TO RELEASE IN JIRA ]
Please vote on releasing this package as Apache AGE (incubating) X.XX!
The vote is open for 72 hours and passes if a majority of at least 3 +1 PMC votes are cast.
[ ] +1 Release this package as Apache age (incubating) X.XX
[ ] +0 No opinion
[ ] -1 Do not release this package because ...
Best Regards,
[ YOUR NAME ]
Send a result mail to the dev mailing list
TO: dev@age.apache.org
Hello Team,
The vote to release Apache age (incubating) X.X.X - RCX has passed/failed.
+1 (binding)
+1 (non-binding)
+0
-1 (binding)
-1 (non-binding)
Thank you for reviewing this release candidate.
Cheers,
[ YOUR NAME ]
While in incubator
Send a mail to the general incubator list
- Vote and Result mail thread
Subject: [VOTE] Release Apache age (incubating) X.XX-rcX
TO: general@incubator.apache.org
Hi All,
[ INCLUDE SOME TEXT ]
Build instructions can be found in the README included.
age community vote and result threads:
Vote:
[ URL TO VOTE FROM https://lists.apache.org/list.html?dev@age.apache.org ]
Result:
[ URL TO VOTE RESULT FROM https://lists.apache.org/list.html?dev@age.apache.org ]
The tag to be voted on is X.X.X-rcX [REPLACE TAG] (commit[COMMIT HASH]):
[URL TO TAG COMMIT]
The release files, including signatures, digests, etc. can be found at:
[ INCLUDE URL TO DIST RC FOLDER ]
https://dist.apache.org/repos/dist/dev/incubator/age/apacheage-X.X.X-incubating-rcX/
The SHA512 Checksum for these artifacts is:
[ INCLUDE CHECKSUM FROM SHA512 file ]
Release artifacts are signed with the following key:
[ ADD URL TO YOUR KEY ON A PUBLIC KEYSERVER ]
For more information about the contents of this release, see:
[ ADD URL TO RELEASE IN JIRA ]
Please vote on releasing this package as Apache age (incubating) X.X.X!
The vote is open for 72 hours and passes if a majority of at least 3 +1 PMC votes are cast.
[ ] +1 Release this package as Apache age (incubating) X.XX
[ ] +0 No opinion
[ ] -1 Do not release this package because ...
Best Regards,
[ YOUR NAME ]
Creating a key
gpg --gen-key
gpg -k [username]@apache.org
# get the ID for your key
gpg --send-keys --keyserver php.mit.edu [KEY ID]
gpg --send-keys --keyserver keyserver.ubuntu.com [KEY ID]
Next step is to add your key to the key file in the Apache SVN repository.
svn co https://dist.apache.org/repos/dist/dev/incubator/age
age_release
cd age_release
gpg --list-sigs [KEY ID] >> KEYS
gpg --armor --export [KEY ID] >> KEYS
svn commit -m "added new public key to KEYS file"
Developer Guidelines
Code Review Process
- Make a commit (or multiple commits) on your local branch.
- Create .patch file(s) of the commit(s).
- Use git format-patch command.
- Send the .patch file(s) to the reviewer.
- The title of the email must be "[Review] [JIRA Ticket Name Here] summary-of-the-issue"
(e.g. [Review] [JIRA Ticket Name] Support changing graph name)- If the commit is not for any issues on JIRA, omit " [JIRA Ticket Name Here]". OR make a JIRA ticket
- The email body will look like this:
Commit bef50e5d86d45707806f5733695a229f3e295b1a [one blank line] Description
-
The first line is the hash code of the base commit, NOT the commit you've created.
- This will help reviewers to quickly apply the .patch files.
- Put proper information to help the reviewer.
-
The first line is the hash code of the base commit, NOT the commit you've created.
-
Attach .patch files.
- Do NOT rename files. They are named with numbers in order.
- Do NOT compress them unless the total file size is over 5MB.
- The title of the email must be "[Review] [JIRA Ticket Name Here] summary-of-the-issue"
- Reply to the last email in the same thread to send a review of it.
- You can attach some .diff files.
- Reply to the last email in the same thread to send updated patch(es) and opinions.
- If you rebase commits, state the hash code of the new base commit.
- Repeat 4 and 5.
How to Merge a Pull Request
Single Commit for a Single Task
In this case, the commit will be merged into the master branch with the following process.-
Change the current working branch to the local master branch by running the following command.
$ git checkout master
- Make the local master branch up-to-date by running the following command (or any other commands that result the same.)
$ git pull
- Change the current working branch to the local task branch that the commit resides in by running the following command.
$ git checkout
- Rebase the local task branch by running the following command.
$ git rebase master
- Resolve any conflicts that occur during rebase.
- Change the current working branch to the local master branch by running the following command.
$ git checkout master
- Merge the local task branch into the local master branch by running the following command.
$ git merge
Multiple Commits for a Single Task
Keeping Commit HistorySometimes, having logically separated, multiple commits for a single task helps developers to grasp the logical process of the work that had been done for the task. If the commits are merged with fast-forward strategy, the commits will not be grouped together. Therefore, to group the commits, create an explicit merge commit.
In this case, the commits will be merged into the master branch with the same process above except the last step (step 7).
For the last step, the local task branch will be merged into the local master branch with an explicit merge commit by running the following command. If you omit --no-ff option, the command will do fast-forward merge instead.
Code Style Guide
Indentation
- You can see the same indentation in all environments.
For switch statement, see below.
Breaking long lines and strings
Placing Braces and Spaces
Naming
Typedefs
Commenting
For single-line comments, use C++ style single-line comments.
See below.
Macros, Enums, and RTL
- If names are changed or new entries are added, it may produces unnecessary diffs and this makes it harder for you to find lines that are actually modified
- If bodies of macros are modified, it may produce unnecessary diffs and this makes it harder for you to find lines that are actually modified.
- It is harder for you to find lines that are actually modified.
Newlines
Conditions
Rules for ereport()
An error detail/hint message that is passed to errdetail()/errhint() starts with an upper case letter.
Creating Documentation
- Dependencies: python3, python3-sphinx, sphinx_rtd_theme
- Clone incubator-age repository (AGE) (https://github.com/apache/incubator-age)
- Go to the doc folder of the project
- Type make html
- The documents are in _build/html
Committer Requirements
1-Continuous contributions to AGE:
Committers should have a decent amount, of continuous engagement and contributions (fixing bugs, writing documentation, answering community questions) to AGE either by contributing on GitHub Repos, documentation and mailing list, etc.
+3 months with light activity and engagement.
+2 months of medium activity and engagement.
+1 month with solid activity and engagement.
2-Quality of contributions: Well tested, well-designed, following Apache AGE coding standards, and simple patches.
3-Community involvement: Committers should support the development and advancement of AGE in different areas. They should also be active on the dev and user list and help mentor newer contributors and users. They should also be active in the design, road map discussions with a professional and diplomatic approach even if there is a disagreement.
Apache AGE Members
Name | |
---|---|
Alex Kwak | take-me-home@kakao.com |
Dehowe Feng | dehowe.feng@bitnine.net |
Eya Badal - PMC Chair | badaleya@gmail.com |
Felix Cheung | felixcheung@apache.org |
Jasper Blues | jasper@liberation-data.com |
John Gemignani | john.gemignani@bitnine.net |
Josh Innis | josh.innis@bitnine.net |
Juan (Trista) Pan | panjuan@apache.org |
Kevin Ratnasekera | djkevincr@apache.org |
Nick Sorrell | nick@cint.io |
Pieterjan De Potter | pdpotter@apache.org |
Von Gosling | vongosling@apache.org |
Name | |
---|---|
Andrew Ko | youngseung.andrew@gmail.com |
Muhammad Shoaib | muhemmed.shoaib@gmail.com, muhammad.shoaib@uni.lu |
Kokou Afidegnon | afidegnum@yahoo.com |
Vuong Quoc Viet | quocviet.vuong2810@gmail.com |
David Shin | sinhanbyeol@gmail.com |
Apache AGE Releases
Apache AGE Release | CheckSum & Signature |
---|---|
Download Apache AGE 1.0.0 | CheckSum & Signature & KEY Files |
Download Apache AGE 0.7.0 | CheckSum & Signature & KEY Files |
Download Apache AGE 0.6.0 | CheckSum & Signature & KEY Files |
Download Apache AGE 0.5.0 | CheckSum & Signature & KEY Files |
Download Apache AGE 0.4.0 | CheckSum & Signature & KEY Files |
Download Apache AGE 0.3.0 | CheckSum & Signature & KEY Files |
Docker Images |
---|
Apache AGE Docker Hub |
Apache AGE Viewer Release | CheckSum & Signature |
---|---|
Download Apache AGE Viewer 1.0.0 | CheckSum & Signature & KEY Files |
Mailing Lists
The Apache AGE Security
The Apache Software Foundation takes a rigorous standpoint in annihilating the security issues in its software projects. Apache AGE is highly sensitive and forthcoming to issues pertaining to its features and functionality. If you have apprehensions regarding AGE’s security or you discover vulnerability or potential threat, don’t hesitate to get in touch with the Apache Security Team by dropping a mail at Security Apache. In the mail, specify the project name AGE with the description of the issue or potential threat. You are also urged to recommend the way to reproduce and replicate the issue. The security team and the AGE community will get back to you after assessing and analysing the findings. PLEASE PAY ATTENTION to report the security issue on the security email before disclosing it on public domain. The ASF Security Team maintains a page with the description of how vulnerabilities and potential threats are handled, check their Web page for more Details.
Apache AGE Maturity Assessment
Overview
It is based on the ASF project maturity model
Status of this document
Maturity model assessment
Category | Description | Self Asssessment |
Code CD10 | The project produces Open Source software for distribution to the public, at no charge. | YES. The project source code is licensed under the Apache License, version 2.0. |
Code CD20 | Anyone can easily discover and access the project's code. | YES. Linked from the website, available via git.apache.org and GitHub at https://github.com/apache/incubator-age |
Code CD30 | Anyone using standard, widely-available tools, can build the code in a reproducible way. | YES. Anyone with a standard OS can build the AGE extension from the code at the GitHub repo. |
Code CD40 | The full history of the project's code is available via a source code control system, in a way that allows anyone to recreate any released version. | YES. Releases are cut from Main repository at https://github.com/apache/incubator-age All releases are tagged. |
Code CD50 | The source code control system establishes the provenance of each line of code in a reliable way, based on strong authentication of the committer. When third parties contribute code, commit messages provide reliable information about the code provenance. | YES. The project GitHub repository, managed by Apache Infra, ensures provenance of each line of code to a committer. Third party contributions are accepted in accordance with the Contribution Guide only. |
Licenses and Copyright LC10 | The Apache License, version 2.0, covers the released code. | YES. Source distributions clearly state license. Convenience binaries clearly state license. |
Licenses and Copyright LC20 | Libraries that are mandatory dependencies of the project's code do not create more restrictions than the Apache License does. | YES. The list of mandatory dependencies have been reviewed to contain approved licenses only. |
Licenses and Copyright LC30 | The libraries mentioned in LC20 are available as Open Source software. | YES. All mandatory dependencies are available as open source software. |
Licenses and Copyright LC40 | Committers are bound by an Individual Contributor Agreement (the "Apache iCLA") that defines which code they may commit and how they need to identify code that is not their own. | YES. The project uses a repository managed by Apache Infra -- write access requires an Apache account, which requires an ICLA on file. |
Licenses and Copyright LC50 | The project clearly defines and documents the copyright ownership of everything that the project produces. | YES. All files in the source repository have appropriate headers (see below).Even further, Software Grant Agreements for the initial donations and Corporate CLAs have been filed. |
Releases RE10 | Releases consist of source code, distributed using standard and open archive formats that are expected to stay readable in the long term. | YES. Source releases are distributed via dist.apache.org and linked from the website. |
Releases RE20 | The project's PMC (Project Management Committee, see CS10) approves each software release in order to make the release an act of the Foundation. | YES. All incubating releases have been unanimously approved by the AGE community and the Incubator, all with at least 3 (P)PMC votes. |
Releases RE30 | Releases are signed and/or distributed along with digests that anyone can reliably use to validate the downloaded archives. | YES. All releases are signed, and the KEYS file is provided on dist.apache.org. |
Releases RE40 | The project can distribute convenience binaries alongside source code, but they are not Apache Releases, they are provided with no guarantee. | YES. Docker images are available at the AGE Docker Hub under the Apache Software Foundation account. |
Releases RE50 | The project documents a repeatable release process so that someone new to the project can independently generate the complete set of artifacts required for a release. | YES. Release guide is available describing the entire process on the AGE website at the Release Process page. The AGE releases have been performed by multiple release managers. |
Quality QU10 | The project is open and honest about the quality of its code. Various levels of quality and maturity for various modules are natural and acceptable as long as they are clearly communicated. | YES. The AGE project records bugs in the Apache’s JIRA issue tracker. |
Quality QU20 | The project puts a very high priority on producing secure software. | YES. Security issues are treated with the highest priority and any potential security issue is managed and reported per the Apache Way. |
Quality QU30 | The project provides a well-documented, secure and private channel to report security issues, along with a documented way of responding to them. | YES. The Apache AGE Security page describes how to report security issues and also informs how to deal with security issuses in accordance with the Apache Way. |
Quality QU40 | The project puts a high priority on backwards compatibility and aims to document any incompatible changes and provide tools and documentation to help users transition to new features. | YES. Each release contains a release notes and is announced on the AGE website at the Roadmap page with the details of the features added or improved. The project aims to make no backward incompatible changes within a given major version. |
Quality QU50 | The project strives to respond to documented bug reports in a timely manner. | YES. The AGE project community has responded to every bug reported in a timely manner. |
Community CO10 | The project has a well-known homepage that points to all the information required to operate according to this maturity model. | YES. The AGE website contains every key information about the AGE project including the description of the project, technical details, online user guide and how to contribute and release the software. |
Community CO20 | The community welcomes contributions from anyone who acts in good faith and in a respectful manner, and who adds value to the project. | YES. It’s part of the contribution guide and the current committers are really keen to welcome contributions. |
Community CO30 | Contributions include source code, documentation, constructive bug reports, constructive discussions, marketing and generally anything that adds value to the project. | The AGE project values and accepts both source code and non-source code contributions. |
Community CO40 | The community strives to be meritocratic and gives more rights and responsibilities to contributors who, over time, add value to the project. | YES. Based on meritocracy, the AGE community has elected 9 new committers and has elevated 4 committers to PPMC during incubation. |
Community CO50 | The project documents how contributors can earn more rights such as commit access or decision power, and applies these principles consistently. | YES. The process to become a committer is documented on the AGE website at the Committer Requirements page. |
Community CO60 | The community operates based on consensus of its members (see CS10) who have decision power. Dictators, benevolent or not, are not welcome in Apache projects. | YES. The project works to build consensus. All votes have been unanimous todate. |
Community CO70 | The project strives to answer user questions in a timely manner. | YES. The AGE project typically provides detailed answers to user questions in a timely manner via dev@ mailing list and users@ mailing list. |
Community consensus CS10 | The project maintains a public list of its contributors who have decision power. The project's PMC (Project Management Committee) consists of those contributors. | YES. The AGE website contains a list of the committers and the PPMC members. |
Community consensus CS20 | Decisions require a consensus among PMC members and are documented on the project's main communications channel. The PMC takes community opinions into account, but the PMC has the final word. | YES. The AGE project has been making all important decisions on the Apache AGE project mailing lists. |
Community consensus CS30 | The project uses documented voting rules to build consensus when discussion is not sufficient. | YES. The project uses the standard ASF voting rules. Voting rules are clearly stated before the voting starts for each individual vote. |
Community consensus CS40 | In Apache projects, vetoes are only valid for code commits. The person exercising the veto must justify it with a technical explanation, as per the Apache voting rules defined in CS30. | YES. The project hasn't used a veto at any point and relies on robust code reviews. |
Community consensus CS50 | All "important" discussions happen asynchronously in written form on the project's main communications channel. Offline, face-to-face or private discussions 11 that affect the project are also documented on that channel. | YES. The AGE project has been making all important decisions on the AGE project's official Apache mailing lists. Some discussions may occasionally happen at the AGE project's GitHub repository and they become registered also on the AGE project's developer mailing list. |
Independence IN10 | The project is independent from any corporate or organizational influence. | YES. The AGE project's PPMC members and committer are from 7 different companies. |
Independence IN20 | Contributors act as themselves, not as representatives of a corporation or organization. | YES. The contributors act on their own initiative without representing a corporation or organization. |