Table of Contents
This is the developer manual for InfiniSQL. This guide is intended for people who wish to get involved with developing InfiniSQL itself. For information about how to use InfiniSQL as a database system with a project that you are developing, please start with the InfiniSQL Guide.
InfiniSQL is being created entirely from the ground up from the work of non-paid volunteers. It is not sponsored by, funded, created, or in any other way springing from some large institution. Your desire to help create InfiniSQL is greatly appreciated, and a necessary element to our success. This guide is created with the spirit of heartily encouraging your pariticpation in InfiniSQL.
InfiniSQL is free software and is licensed under the GNU General Public License, version 3. A few source files are exceptions to this, and they are noted accordingly in the files themselves.
Please read an understand the GPLv3 license yourself. Those license terms guide the contribution goals of the InfiniSQL project, namely:
Any original work that you create for the project will also fall under the terms of the GPLv3 license.
Any work that you integrate from a 3rd party will fall under the license terms of that 3rd party. However, it must be compatible with the GPLv3. The only additional restriction acceptable is an atribution clause, such as required by some types of BSD-oriented licenses.
While you are encouraged to make your changes freely available, you are only required to do so if you distribute a modified copy of the software to somebody else. If you create your own version of InfiniSQL, then you can only distribute that version if you share your source code modifications.
The main goal of the InfiniSQL project is to create the highest performing relational database management system (RDBMS), with particular emphasis on horizontal scalability and distributed transaction processing. Distributed transactions are those which involve records on multiple nodes. In support of this, the project has the following high-level goals:
SQL compliance equivalent or superior to long established RDBMS systems, including (but not limited to):
ORDER BY, GROUP BY, HAVING clauses
CREATE TABLE, CREATE COLUMN, etc.: all data definition, to deprecate the commands in the raw interface, such as createtable, addcolumn, and the like.
Deadlock management or a deadlock-free concurrency alogorithm
Data integrity as appropriate for mission critical transaction processing workloads, such as required for financial operations.
To refer to the CAP protocol, InfiniSQL's primary goal is to support CP. And to maximize availability, InfiniSQL is likely not appropriate for infrastructure hosted in environments where power systems are not stable, network connectivity is spotty, hypervisor overhead is cumbersome, and resource allocation tends to be random. To maximize availability, InfiniSQL will rely upon visibility into and some control over the underlying infrastructure. And to maximize performance, InfiniSQL needs hosting upon a high performance platform.
Dynamic scalability, automated failover, and all maintenance activities to be performed on a running cluster. There should be no reason aside from catastrophic site damage to cause an InfiniSQL cluster shutdown.
Mixture of database activities, such as relational, messaging, and caching operations, performed within a single transaction.
Ease of use and deployment for the simplest of workloads and scaling to the most high volume and complex.
In-memory performance with non-volatile durability
Automated continuous integration and testing.
High speed cluster interconection, such as using Infiniband RDMA.
Feature gap analysis for desirable use cases.
Implicit in InfiniSQL's goals and capabilities is the support for simpler workloads. For example, since InfiniSQL can perform distributed transactions at very high throughput, it can also support simple operations, such as keystore activities, at very high throughput. Just like an automobile that goes fast uphill is also fast at going downhill (but not necessarily vice versa).
Hopefully, your own goals for InfiniSQL conform in some way to those stated above. And if they don't match entirely, there's always room for discussion. In particular, there are a rather wide variety of non-relational data storage formats, such as column, graph and document-based stores. The core InfiniSQL architecture can very likely work very well with those kinds of formats, and contributions to that effect are welcomed. Essentially, if it adds functionality and doesn't break anything, it's probably welcome.
The bulk of InfiniSQL source code is documented via doxygen and available at http://infinisql.github.io/doxygen/.
In lieu of a centralized roadmap (the creation of which is a TODO), there are a variety of different sources of information from which to start. The main project documentation contains over one hundred printed pages of information about InfiniSQL's capabilities, how to use it, FAQ, and features that are not yet fully implemented. The source code is available on Github at https://github.com/infinisql/infinisql.git. InfiniSQL uses project-related issues to describe bugs as well as requested items. Google Groups for InfiniSQL is at https://groups.google.com/forum/#!forum/infinisql. There is also a wiki associated with the project. Also, the main www site has many links to external media sources discussing InfiniSQL. There's also a blog.
So, please learn about InfiniSQL's current state, what we still need to do, and then think about how your skills and interests can match up!
If your change is relatively minor, and especially if it's in response to an open ticket, then do a GitHub pull request after you've completed your changes. Otherwise, open up communication about your proposed change. Any of the communication methods described on the community page are acceptable. You will probably get a response within 24 hours, and most likely much sooner.
InfiniSQL has a single committer, Mark Travis, who is also the founder of the project. Pull requests made via GitHub are handled by Mark. This situation may change over time as the project grows. All modes of communicating with InfiniSQL available on the web site, or on the GitHub repository, are monitored by Mark. To contact Mark, contact InfiniSQL. This arrangement will likely change over time as the project grows and the organization needs to scale.
Here are some general tips about coding with the InfiniSQL project. Coding standards are BSD-style, with indentation to 4 spaces. This means open braces on the column directly underneath the first column of the previous line. If possible, please try to comply with cppcheck. Obviously, don't let cppcheck's complaints result in broken code. But, generally, cppcheck seems to have good advice about coding quality.
Before adding files to a commit, execute the gitditchleavings.sh script in the root of the source tree. That keeps files that are modified by autotools from getting into the source tree. There is doubtless a better way of configuring autotools (or, perhaps, using another toolset, such as cmake or scons). Volunteers are welcome to help shore up that effort.
Regarding documentation, please use Doxygen commenting style to document classes, functions, structs, unions and enums that you create. Examples within the source tree abound. The main documentation is in Docbook 5 format in the docs/pubs directory. Docbook 5 is pretty easy to work with if you're used to structured markup formats, such as XML and HTML. But don't feel as though you need to patch these files to document your contributions--it is also acceptible to provide simple text documentation along with your patches, such as in the commend section for an open ticket.
Please test your changes before submitting them. Minimally, the regression test described in the user guide should be successful. Further, any new functionality added should also be tested, and the test mechanism provided as part of the patch submittal.
Stay in touch with InfiniSQL! Development communication takes place in our Google Groups forum and on irc at irc://irc.freenode.net/infinisql. Please subscribe to email messages from the Google Groups site--it's currently (12/2013) a very low volume group. Please also follow and star on Github, hang out with us on IRC, and follow on twitter.