NAME
Muldis::DB - Full-featured truly relational DBMS in Perl
VERSION
This document describes Muldis::DB version 0.0.1 for Perl 5.
It also describes the same-number versions for Perl 5 of Muldis::DB::Interface::DBMS ("DBMS"), Muldis::DB::Interface::HostGateVar ("HostGateVar"), and Muldis::DB::Interface::HostGateRtn ("HostGateRtn").
It also describes the same-number versions for Perl 5 of Muldis::DB::Engine::Role, Muldis::DB::Engine::Role::DBMS, Muldis::DB::Engine::Role::HostGateVar, and Muldis::DB::Engine::Role::HostGateRtn.
SYNOPSIS
use Muldis::DB;
# Instantiate a Muldis::DB DBMS / virtual machine.
my $dbms = Muldis::DB::new_dbms({
'engine_name' => 'Muldis::DB::Engine::Example',
'dbms_config' => {},
});
# TODO: Create or connect to a repository and work with it.This documentation is pending.
DESCRIPTION
The "Muldis::DB" DBMS framework is a powerful but elegant system, which makes it easy to create and use relational databases in a very reliable, portable, and efficient way. This "Muldis::DB" file is the core of the Muldis::DB framework and defines a truly relational common programmatic interface (API), called the Muldis::DB Native Interface, which applications invoke and which multiple interchangeable "Engine" back-ends (usually provided by third parties) implement. This interface is rigorously defined, such that there should be no ambiguity when trying to invoke or implement it, and so an application written to it should behave identically no matter which conforming "Engine" is in use.
Muldis::DB incorporates a complete and uncompromising implementation of "The Third Manifesto" (TTM), a formal proposal by Christopher J. Date and Hugh Darwen for a solid foundation for data and database management systems (DBMSs); like Edgar F. Codd's original papers, TTM can be seen as an abstract blueprint for the design of a DBMS and the language interface to such a DBMS. The main web site for TTM is http://www.thethirdmanifesto.com/, and its authors have also written several books and papers and taught classes on the subject over the last 35+ years, along with Codd himself (some are listed in the Muldis::DB::SeeAlso documentation file). Note that the Muldis::DB documentation will be focusing mainly on how Muldis::DB itself works, and will not spend much time in providing rationale; you can read TTM itself and various other external documentation for much of that.
The Muldis::DB Native Interface is defined mainly in terms of a new high-level programming language named "Muldis D", which is computationally complete (and industrial strength) and has fully integrated database functionality; this language, which satisfies TTM's definition of a "D" language, is described fully in the Muldis::DB::Language documentation file that comes with this "Muldis::DB" distribution.
While it is possible that one could write a self-contained application in Muldis D and compile that into its own executable, in practice one would normally just write some components of their application in Muldis D (as either named modules or anonymous routines) and write the rest of the application in their other language(s) of choice. Assuming the main application is written in Perl, it is this "Muldis::DB" file which provides the glue between your Perl code and your Muldis D code; "Muldis::DB" implements a virtual machine that is embedded in your Perl application and in which the Muldis D code runs (it is analogous to the Perl interpreter itself, which provides a virtual machine in which Perl code runs).
The classes and methods of this "Muldis::DB" file, together with those of Muldis::DB::AST, define the balance of the Muldis::DB Native Interface. A Muldis::DB::Interface::DBMS object represents a single active Muldis::DB virtual machine; it has a spartan DBI-inspired set of methods which you use to compile/prepare and/or invoke/execute Muldis D statements and routines within the virtual machine, input data to it, and output data from it.
You can create more than one DBMS object at a time, and they are essentially all isolated from each other, even if more than one uses the same Engine class to implement it; that is, multiple DBMS objects will not have references to each other at a level visible in the Muldis::DB Native Interface, if at all. To account for situations where multiple DBMS objects want to use the same external resources, such as a repository file on disk, it is expected that the Engines will employ appropriate measures such as system-managed locks so that resource corruption or application failure is prevented. Also, Muldis::DB should be thread safe and/or savvy in the future, but for now it officially is not and you should not share Muldis::DB objects between multiple threads, nor have objects in separate threads try to access the same external resources.
Muldis::DB does not use any dialect of SQL in its native API (unlike many other DBMS products) because SQL is more ambiguous and error-prone to use, and it is less expressive. While Muldis D is very different from SQL, it is fully capable of modeling anything in the real world accurately, and it can support a complete SQL emulation layer on top of it, so that your legacy applications can be migrated to use the Muldis::DB DBMS with little trouble. Likewise, emulation layers for any other programming language can be supported, such as Tutorial D or XQuery or FoxPro or dBase.
One distinctive feature of a Muldis::DB DBMS (compared to a typical other vendor's DBMS) is that data definition statements are structured as standard data manipulation statements but that the target relation variables are system catalog relation variables rather than user-defined relation variables. In SQL terms, you create or alter tables by adding or updating their "information schema" records, which in SQL are read-only, not by using special 'create' or 'alter' statements.
Each Muldis::DB Engine has the complete freedom to implement the Muldis::DB DBMS and Muldis D however it likes; all Muldis::DB cares about is that the user interface and behaviour conform to its preconceptions.
Muldis::DB::Engine::Example is the self-contained and pure-Perl reference implementation of an Engine and is included in the "Muldis::DB" core distribution to allow the core to be completely testable on its own. It is coded intentionally in a simple fashion so that it is easy to maintain and and easy for developers to study. As a result, while it performs correctly and reliably, it also performs quite slowly; you should only use Example for testing, development, and study; you should not use it in production.
For production use, there should be a wide variety of third party Engine modules that become available over time. One plan being favored is that the new (under development) enterprise-strength and Perl implemented database server named Genezzo (see also http://www.genezzo.com/) will evolve to implement the Muldis::DB DBMS natively, and be the back-end which is recommended above all others for production use.
Most of the other (near term) third party Engines will likely just map Muldis::DB's rigorously defined API onto a pre-existing quasi-relational database manager (such as SQLite, PostgreSQL, MySQL, Firebird, Teradata, Oracle, Sybase, SQL Server, Informix, DB2, OpenBase, FrontBase, etc). Given this fact, Muldis::DB's most prominent feature is that it provides a common API for access to those databases, each of which takes a different SQL or quasi-SQL dialect. An application written to it should easily port to alternative relational database engines with minimal effort.
This might seem strange to somebody who has not tried to port between databases before, especially given that the Perl DBI purports to provide "Database Independence". However, the level of DBI's provided independence is Database Driver Independence, and not Database Language Independence. To further demonstrate the difference, it is useful to compare the DBI and Muldis::DB. Such documentation is currently absent.
FEATURE SUPPORT VALIDATION
The Muldis::DB Native Interface declares accessors for a large number of actual or possible database features, any of which your application can invoke, and all of which each Muldis::DB Engine would ideally implement or interface to.
In reality, however, all Engines or underlying databases probably don't support some features, and if your application tries to invoke any of the same features that an Engine you are using doesn't support, then you will have problems ranging from immediate crashes/exceptions to subtle data corruption over time.
As an official quality assurance (QA) measure, Muldis::DB provides a means for each Engine to programmatically declare which features it does and does not support, so that code using that Engine will know so in advance of trying to use said features. Feature support declarations are typically coarse grained and lump closely similar things together, for simplicity; they will be just as fine grained as necessary and no finer (this can be changed over time). See the features() method, which is how you read the declarations.
One benefit of this QA feature is that, after you have written your application and it is working with one Engine/database, and you want to move it to a different Engine/database, you can determine at a glance which alternatives also support the features you are using. Note that, generally speaking, you would have to be using very proprietary features to begin with in order for the majority of Muldis::DB Engines/databases to not support the application outright.
Another benefit of this QA feature is that there can be made a common comprehensive test suite to run against all Engines in order to tell that they are implementing the Muldis::DB interface properly or not; said test suite will be smart enough to only test each Engine's compliance for those features that the Engine claims to support, and not fail it for non-working features that it explicitly says it doesn't support. This common test suite will save each Engine maker from having to write their own module tests. It would be used similarly to how Sun has an official validation suite for Java Virtual Machines to make sure they implement the official Java specification. Please see the Muldis::DB::Validator module(s), which implements this test suite.
INTERFACE
The interface of Muldis::DB is fundamentally object-oriented; you use it by creating objects from its member classes, usually invoking new() on the appropriate class name, and then invoking methods on those objects. All of their attributes are private, so you must use accessor methods.
Muldis::DB also provides the not-exportable wrapper subroutine Muldis::DB::new_dbms for the Muldis::DB::Interface::DBMS constructor, which has identical parameters, and exists solely as syntactic sugar. Similarly, the DBMS methods new_var and prepare exist purely as syntactic sugar over the HostGateVar and HostGateRtn constructors. TODO: Reimplement these as lexical aliases or compile-time macros instead, to avoid the overhead of extra routine calls.
The usual way that Muldis::DB indicates a failure is to throw an exception; most often this is due to invalid input. If an invoked routine simply returns, you can assume that it has succeeded, even if the return value is undefined.
The Muldis::DB::Interface::DBMS Class
This documentation is pending.
The Muldis::DB::Interface::HostGateVar Class
This documentation is pending.
The Muldis::DB::Interface::HostGateRtn Class
This documentation is pending.
The Muldis::DB::Engine::Role(|::\w+) Roles
This "Muldis::DB" file also defines a few roles that the public interface classes of all Engine modules must implement, and explicitly declare that they are doing so.
The initial Engine class, which users specify in the $engine_name argument to the Muldis::DB::Interface::DBMS constructor, must compose the Muldis::DB::Engine::Role, and implement the new_dbms submethod. The DBMS Engine object returned by new_dbms must compose the Muldis::DB::Engine::Role::DBMS role, and implement the methods new_var and prepare. The HostGateVar Engine object returned by new_var must compose the Muldis::DB::Engine::Role::HostGateVar role, and implement the methods fetch_ast and store_ast. The HostGateRtn Engine object returned by new_var must compose the Muldis::DB::Engine::Role::HostGateRtn role, and implement the methods bind_host_params and execute.
The Muldis::DB Interface classes don't just validate user input on behalf of Engines (allowing them to be simpler), but they also validate each requested Engine's APIs and results, to some extent, on behalf of users (so an application can more gracefully handle a bad Engine); the Engine Role roles exist to help with the latter kind of validation, and they mainly just declare shims for the required (sub|)methods, which die on invocation if the Engine didn't declare its own versions; they don't presently contain any actual functionality for Engines to use.
DIAGNOSTICS
This documentation is pending.
CONFIGURATION AND ENVIRONMENT
This documentation is pending.
DEPENDENCIES
This file requires any version of Perl 5.x.y that is at least 5.8.1.
It also requires these Perl 5 classes that are in the current distribution: Muldis::DB::AST-(0.0.1).
INCOMPATIBILITIES
None reported.
SEE ALSO
These documentation files are included in the Muldis::DB distribution: Muldis::DB::Language.
The Perl 5 module Muldis::DB::Validator is bundled with Muldis::DB and can be used to test Muldis::DB Engines.
The Perl 5 module Muldis::DB::Engine::Example is bundled with Muldis::DB and implements a self-contained reference implementation of a Muldis::DB Engine.
Go to the Muldis::DB::SeeAlso file for the majority of external references.
BUGS AND LIMITATIONS
The Muldis::DB framework for Perl 5 is built according to certain old-school or traditional Perl-5-land design principles, including that there are no explicit attempts in code to enforce privacy of the framework's internals, besides not documenting them as part of the public API. (The Muldis::DB framework for Perl 6 is different.) That said, you should still respect that privacy and just use the public API that Muldis::DB provides. If you bypass the public API anyway, as Perl 5 allows, you do so at your own peril.
This documentation is pending.
AUTHOR
Darren Duncan (perl@DarrenDuncan.net)
LICENSE AND COPYRIGHT
This file is part of the Muldis::DB framework.
Muldis::DB is Copyright © 2002-2007, Darren Duncan. All rights reserved.
Muldis::DB is free software; you can redistribute it and/or modify it under the terms of either:
a) the GNU General Public License (GPL) as published by the Free Software Foundation (http://www.fsf.org/); either version 3 of the License, or (at your option) any later version, or
b) the GNU Affero General Public License (AGPL) as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version.
You should have received copies of the GPL and AGPL as part of the Muldis::DB distribution, in the files named "LICENSE/GPL" and "LICENSE/AGPL" respectively; if not, see http://www.gnu.org/licenses or write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
WARNING: The AGPL version 3 are still being drafted, and its date of final publication is unknown, but is presumed to be soon; until then, the AGPL can not actually be used. So the previous paragraphs just represent what the license of Muldis::DB is anticipated to be following the AGPL's release. That said, Muldis::DB is for now simply licensed to you under the GPL version 3, which is the first choice in the above disjunction.
If it is not feasible for you to employ Muldis::DB subject to the terms of the GPL or AGPL, then the copyright holder of Muldis::DB can provide you a customized proprietary license, often at no cost, so that it is still possible for you to employ Muldis::DB to meet your needs.
Note that the copyright holder of Muldis::DB is open to being convinced to generally release the work under the GNU Lesser General Public License (LGPL), version 3 or later, instead of under the GPL (or alternately, of being convinced not to change). But any argument for or against that change should be centred on how the free software community in general, and in particular the subset that work with or on Perl or Muldis::DB itself, would be benefited more by the change versus staying with the GPL; that is, such a change should have strategic value for the community.
For more information on matters such as licensing, including rationale, see also the Muldis::DB::Copying file that comes with Muldis::DB.
Any versions of Muldis::DB that you modify and distribute must carry prominent notices stating that you changed the files and the date of any changes, in addition to preserving this original copyright notice and other credits. Muldis::DB is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. However, for an additional fee, the copyright holders of Muldis::DB can sell you a warranty for it.
While it is by no means required, the copyright holder of Muldis::DB would appreciate being informed any time you create a modified version of Muldis::DB that you are willing to distribute, because that is a practical way of suggesting improvements to the standard version.
ACKNOWLEDGEMENTS
None yet.
FORUMS
Several public email-based forums for Muldis::DB now exist, all of which you can reach via http://mm.DarrenDuncan.net/mailman/listinfo; go there to manage your subscriptions to, or view the archives of, the following:
muldis-db-announce@mm.DarrenDuncan.net-
This low-volume list is mainly for official announcements from the Muldis::DB developers, though developers of Muldis::DB extensions can also post their announcements here. This is not a discussion list.
muldis-db-users@mm.DarrenDuncan.net-
This list is for general discussion among people who are using Muldis::DB, which is not concerned with the implementation of Muldis::DB itself. This is the best place to ask for basic help in getting Muldis::DB installed on your machine or to make it do what you want. You could also submit feature requests or report perceived bugs here, if you don't want to use CPAN's RT system.
muldis-db-devel@mm.DarrenDuncan.net-
This list is for discussion among people who are designing or implementing the Muldis::DB core API (including Muldis D language design), or who are implementing Muldis::DB Engines, or who are writing core documentation, tests, or examples. It is not the place for non-implementers to get help in using said.
An official IRC channel for Muldis::DB is also intended, but not yet started.
Alternately, you can purchase more advanced commercial support for Muldis::DB from its author; contact perl@DarrenDuncan.net for details.