Help language development. Donate to The Perl Foundation

MongoDB cpan:MARTIMM last updated on 2020-07-19

doc/Manual/MongoDB.sxml
#!/usr/bin/env sxml2xml.pl6 --in=db5 --out=pdf MongoDB.sxml

$!d5b.article [
  $title [ Perl 6 MongoDB driver ]

  $!d5b.info firstname=Marcel surname=Timmerman [email protected]
             city=Haarlem country=Netherlands
             copy-year='2015, 2016 ... Inf' copy-holder='Marcel Timmerman' [

    $para [
      MongoDB is a $glossterm linkend=nosql [Non SQL] database which uses
      $glossterm linkend=bson [Binary JSON (BSON)] to
      store and load information in a database. With the mongodb package a
      shell program called mongo is available to give instructions to a
      mongodb server.
    ]

    $para [
      To work with data on the server from within a program a driver is needed.
      There are drivers for many program languages. This document describes a
      driver for the Perl6 language. In the perl6 ecosystem, which might grow
      into a cpan like system later, there are two packages needed to work with
      the driver. These are $glossterm linkend=mongodb [MongoDB] and BSON.
      BSON is automatically installed with other necessary modules.
    ]

    $para [
      The latest version of this document is generated on date $!SxmlCore.date
    ]
  ]

  $sect1 [
    $title [Introduction]
    $para [
      The purpose of this document is to show how things are accomplished in
      this driver in the light of the MongoDB developer documents and how to
      work with the perl6 mongodb driver.
    ]

    $para [
      However, this document will not tell you how to design your database among
      other things. There are plenty of good books and documents out there, not
      to mention, the mongodb website.
    ]

    $para [
      There are quite a few modules written to perform the tasks at hand but not
      all modules will be explained here because many of them are modules
      defining classes to be used in the background and are not used by
      applications directly.
    ]

    $para [
      Furthermore, this document is not a reference. There are other documents
      for that, written to document the attributes, (sub)methods and subs in a
      class. There will be a list of references at the end of the document.
    ]

    $para [
      This document assumes that the reader is aware of at least the basics of
      the mongodb database and what one can do with it. Also some perl 6
      knowledge will be necessary.
    ]

    $para [
      As a last remark, the driver is still in development. Although many parts
      are accomplished, some parts still need to be implemented like
      authentication agains kerberos or LDAP. Furthermore, there are some
      improvements needed to speedup the operations.
    ]

    $para [
      The following sections will be explained:

      $itemizedlist spacing=compact [
        $listitem [
          $emphasis[Implementation].

          $itemizedlist spacing=compact [
            $listitem [
            $emphasis[Server states].
            ]

            $listitem [
            $emphasis[Topology]. The topology of a client is defined by the set of servers and their states.
            ]

            $listitem [
              $emphasis[Round trip time].
            ]

            $listitem [
              $emphasis[Read concern].
            ]

            $listitem [
              $emphasis[Write concern].
            ]

            $listitem [
              $emphasis[URI]. The URI tells the software how to connect and
              select the proper server.
            ]

            $listitem [
              $emphasis[Server selection process]. This is the process of finding a server depending on the server state and the topology.
            ]
          ]
        ]

        $listitem [
          $emphasis[Modules and classes]. There are many more classes but the classes named below are the ones which will be used by you.

          $itemizedlist spacing=compact [

            $listitem [
              $emphasis[BSON::Document]. This is the basic vehicle to insert,
              update retrieve and send commands to the database server. In this
              section there is an explanation of the supported types as well as
              different ways to make requests. Some detailed perl6 is necessary
              to understand mistakes often made when creating the data
              structures.
            ]

            $listitem [
              $emphasis[MongoDB]. Here a lot of the programs constants, enumerations and subtypes are defined as well as the import of logging subs.
            ]

            $listitem [
              $emphasis[MongoDB::Client]. This module is the starting point of all applications which need access to a mongodb database server. The client receives the uri from the user of the module to access one or more servers.

# named attributes to control selecting and monitoring
# cleanup!
            ]

            $listitem [
              $emphasis[MongoDB::Collection]. The Collection module is used to search through the collection data of the database.
            ]

            $listitem [
              $emphasis[MongoDB::Cursor]. The Cursor is used to process the found data returned from the search.
            ]

            $listitem [
              $emphasis[MongoDB::Database]. The Database is the most used module to send commands to the server.
            ]
          ]
        ]

        $listitem [
          $emphasis[Programs]. There are also a few programs in this package to help you with a few administrative tasks;
          $itemizedlist spacing=compact [
            $listitem [
              Starting and stopping of servers
            ]
            $listitem [
              Add, remove and modify accounts
            ]
            $listitem [
              Creating a replicaset
            ]
          ]
        ]

        $listitem [
          $emphasis[MongoDB Servers].
        ]

        $listitem [
          $emphasis[Examples].
        ]

        $listitem [
        $emphasis[Things to add to this package]. The program is far from complete. The most important items to add are the following;

          $itemizedlist spacing=compact [
            $listitem [
              Secure connection to the server. This is at least needed when authentication is performed. If not, the username/password information is visible when you know where to look.
            ]
            $listitem [
              Higher level commands. There is a need for some convenience methods like insert, update, remove etcetera. In the past there were methods like these but I have removed them for two reasons: 1) the methods were based on the wire protocol which will be obsoleted partly in the future by MongoDB and 2) MongoDB has replaced them by operations all executable using the MongoDB runCommand function and therefore by the run-command method from the MongoDB::Database class.
            ]
            $listitem [
            ]
          ]
        ]
      ]
    ]
  ]

  $sect1 [
    $title [Implementation]
    $para [
      A short description of what happens when a user instantiates a MongoDB::Client object providing it with a URI. The Client object parses the URI for server names. These are used by the Client to instantiate a MongoDB::Server object. The server object instantiates a MongoDB::Monitor object to keep contact with the server and to process any changes when they appear. The Monitor object informs the Server object to set the Server state. The Client object will then use the Server states to define the topology of that group of servers.
    ]
    $para [
      Conflicts can happen when servers defined in the URI not belong together in a group. For example a replica server and a standalone server can not be taken together in one URI because both servers can accept commands to change data. The Client object cannot guess to which of the servers the command must be send to. In such cases the topology is set to $emphasis[MongoDB::TT-Unknown] which will block any operation.
    ]

    $sect2 [
      $title [Server states]
      $para [
        Server states are situations in which a server can be. The server is queried regularly with a so called $emphasis[ismaster] command. The result of this command is processed to see what kind of server we are dealing with. Based on these results the $emphasis[MongoDB::Server] object sets a state which is displayed in the table below.
      ]

      $para [
        $table rules=all [
          $title [Server states depending on isMaster outcome]
          $thead [
            $tr [
              $th [Server state]
              $th [isMaster command result]
            ]
          ]

          $tbody [
            $tr [
              $td [ST-Unknown]
              $td [
                a) Initial state before processing the response.
                b) After a network error or failed ismaster call.
                c) "ok: 1" not in ismaster response.
              ]
            ]
          ]

          $tbody [
            $tr [
              $td [ST-Standalone]
              $td [
                There is no key/value pair "msg: isdbgrid", there is no setName, and there is no "isreplicaset: true" key/value pair.
              ]
            ]
          ]

          $tbody [
            $tr [
              $td [ST-Mongos]
              $td [ Key/value pair "msg: isdbgrid" is found in the Monitor response.
              ]
            ]
          ]

          $tbody [
            $tr [
              $td [ST-PossiblePrimary]
              $td [
                Not yet processed, but another secondary server member thinks it is the primary.
              ]
            ]
          ]

          $tbody [
            $tr [
              $td [ST-RSPrimary]
              $td [
                Key/value "ismaster: true" and "setName" is found in the Monitor response.
              ]
            ]
          ]

          $tbody [
            $tr [
              $td [ST-RSSecondary]
              $td ["secondary: true", "setName" in response.]
            ]
          ]

          $tbody [
            $tr [
              $td [ST-RSArbiter]
              $td ["arbiterOnly: true", "setName" in response.]
            ]
          ]

          $tbody [
            $tr [
              $td [ST-RSOther]
              $td [
                "setName" in response, "hidden: true" or not primary,
                secondary, nor arbiter. E.g. starting up or recovering.
              ]
            ]
          ]

          $tbody [
            $tr [
              $td [ST-RSGhost]
              $td [
                "isreplicaset: true" in response. E.g.  briefly during server
                startup, in an uninitialized replica set, or when the server
                is shunned (removed from the replica set config).
              ]
            ]
          ]
        ]
      ]
    ]

    $sect2 [
      $title [Topology]
      $para [
        $table rules=all [
          $title [Topology controlled by server states]
          $thead [
            $tr [
              $th [Topology type]
              $th [Server states]
            ]
          ]

          $tbody [
            $tr [
              $td [TT-Unknown]
              $td [
                When a deployment has this topology type, no servers are
                suitable for read or write operations. These are servers which
                did not respond on initial connection or threw an exception
                because of e.g. a DNS lookup failure. All server states of
                these servers herded by the Client object is ST-Unknown.
              ]
            ]
          ]

          $tbody [
            $tr [
              $td [TT-Single]
              $td [
                A deployment of topology type TT-Single contains only a single
                server which can have any state except ST-Unknown. This topology
                type signifies a direct connection intended to receive all read
                and write operations.
              ]
            ]
          ]

          $tbody [
            $tr [
              $td [TT-Sharded]
              $td [
                A deployment of topology type TT-Sharded contains one or more
                servers of type ST-Mongos or ST-Unknown of at least one is
                ST-Mongos.
              ]
            ]
          ]

          $tbody [
            $tr [
              $td [TT-ReplicaSetNoPrimary]
              $td [
                A deployment with this topology type can have a mix of server
                types: ST-RSSecondary, ST-RSArbiter, ST-RSOther, ST-RSGhost,
                ST-Unknown or ST-PossiblePrimary.
              ]
            ]
          ]

          $tbody [
            $tr [
              $td [TT-ReplicaSetWithPrimary]
              $td [
                A deployment with this topology type can have a mix of server
                types: ST-RSPrimary, ST-RSSecondary, ST-RSArbiter, ST-RSOther,
                ST-RSGhost, ST-Unknown or ST-PossiblePrimary.
              ]
            ]
          ]
        ]
      ]
    ]

    $sect2 [
      $title [Round Trip Time]
      $para [
      ]
    ]

    $sect2 [
      $title [Read concern]
      $para [
      ]
    ]

    $sect2 [
      $title [Write concern]
      $para [
      ]
    ]

    $sect2 [
      $title [URI]
      $para [


        $table rules=all [
          $title [Implemented uri connection options]
          $thead [
            $tr [
              $th [Option]
              $th [Description]
            ]
          ]

          $tbody [
            $tr [
              $td [replicaSet]
              $td [
                Specifies the name of the replica set, if the mongod is a member
                of a replica set. When connecting to a replica set it is
                important to give a seed list of at least two mongod instances.
                If you only provide the connection point of a single mongod
                instance, and omit the replicaSet, the client will create a
                standalone connection.
              ]
            ]
          ]
        ]
      ]
    ]

    $sect2 [
      $title [Server selection]
      $para [

        $itemizedlist spacing=compact [
          $listitem [
            Record the server selection start time
          ]
          $listitem [
            If the topology wire version is invalid, raise an error
          ]
          $listitem [
            Find suitable servers by topology type and operation type
          ]
          $listitem [
            If there are any suitable servers, choose one at random from those
            within the latency window and return it; otherwise, continue to
            step #5
          ]
          $listitem [
            Request an immediate topology check, then block the server
            selection thread until the topology changes or until the server
            selection timeout has elapsed
          ]
          $listitem [
            If more than serverSelectionTimeoutMS milliseconds have elapsed
            since the selection start time, raise a server selection error
          ]
          $listitem [
            Goto Step #2
          ]
        ]

      ]
    ]
  ]

  $sect1 [
    $title [Modules and classes]

    $sect2 [
      $title [MongoDB]
      $para [

      ]
    ]

    $sect2 [
      $title [MongoDB::Client]
      $para [

      ]

      $sect3 [
        $title [Making a connection]
        $para [
        ]
      ]
    ]


    $sect2 [
      $title [BSON::Document]
      $para [

      ]
    ]

    $sect2 [
      $title [MongoDB::Database]
      $para [

      ]

      $sect3 [
        $title [run-command()]
        $para [

        ]
      ]
    ]

    $sect2 [
      $title [MongoDB::Collection]
      $para [

      ]

      $sect3 [
        $title [find()]
        $para [

        ]
      ]
    ]

    $sect2 [
      $title [MongoDB::Cursor]
      $para [

      ]

      $sect3 [
        $title [fetch()]
        $para [

        ]
      ]

      $sect3 [
        $title [iterating over documents]
        $para [

        ]
      ]
    ]

    $sect2 [
      $title [MongoDB::Server]
      $para [

      ]
    ]

    $sect2 [
      $title [MongoDB::Server::Control]
      $para [

      ]
    ]
  ]

  $sect1 [
    $title [BSON]
    $sect2 [
      $title [Supported types]
      $para [

        $table rules=all [
          $title [Supported types of the BSON package]
          $thead [
            $tr [
              $th [BSON]
              $th [Perl6]
              $th [Description]
            ]
          ]

          $tbody [
            $tr [
              $td [Double]
              $td [Num]
              $td [
                An eight byte floating point number. The perl6 type choosen
                is a 'Num' which stores a floating-point number.  On most
                platforms, it's an IEEE 754 64-bit floating point number, aka
                "double precision" (From perl 6 doc).

                The 'Rat' is not choosen because it can not be converted back
                the way it was thereby loosing accuracy.
              ]
            ]
          ]

          $tbody [
            $tr [
              $td [String]
              $td [Str]
              $td [
                A normal string type.
              ]
            ]
          ]

          $tbody [
            $tr [
              $td [Document]
              $td [BSON::Document]
              $td [
                As the document itself a subdocument is also a BSON::Document.
                Hashes are refused because the keys are not necessary kept in
                the same order as is stored by the user. This is important when
                searches are done. The seach query is also encoded using the
                BSON::Document and on the server not decoded. So the query
                is matched against binary data which is ofcourse faster.
              ]
            ]
          ]

          $tbody [
            $tr [
              $td [Array]
              $td [Array]
              $td [
              ]
            ]
          ]

          $tbody [
            $tr [
              $td [Binary]
              $td [Buf]
              $td [
                The perl6 Buf type is used to express the BSON binary type.
                However, the BSON specification also covers for types such as
                Function, UUID and MD5. Furthermore user defined types can also
                be be specified. Ideas for this are the perl6 types Rat, Set,
                IntStr, Hash, List etc. Also very large or small Int values
                could encoded this way.
              ]
            ]
          ]

          $tbody [
            $tr [
              $td [ObjectId]
              $td [BSON::ObjectId]
              $td [
                This object is generated on the server by default. However, it
                can be used to refer to other objects or to create the document
                $emphasis[_id] themselves.
              ]
            ]
          ]

          $tbody [
            $tr [
              $td [Boolean]
              $td [Bool]
              $td [
              ]
            ]
          ]

          $tbody [
            $tr [
              $td [Date]
              $td [DateTime]
              $td [
              ]
            ]
          ]

          $tbody [
            $tr [
              $td [Null]
              $td [Any]
              $td [
                Any undefined variable or Type object is used to express the
                Null BSON type. It will also convert to Any only. So any other
                used Type object is lost when decoding the document.
              ]
            ]
          ]

          $tbody [
            $tr [
              $td [Javascript]
              $td [BSON::Javascript]
              $td [
              ]
            ]
          ]

          $tbody [
            $tr [
              $td [Javascript with scope]
              $td [BSON::Javascript]
              $td [
              ]
            ]
          ]

          $tbody [
            $tr [
              $td [32 bit int]
              $td [Int]
              $td [
                The perl6 Int type can represent integers from -∞ to
                +∞. The software tests the Int number if it falls in
                the 4 byte range. When outside that range, it tests for the 8
                byte range and converts to the BSON 64 bit type. When even
                smaller/larger, an exception is thrown.
              ]
            ]
          ]

          $tbody [
            $tr [
              $td [Timestamp]
              $td [-]
              $td [
                Not yet supported because it is for internal MongoDB use.
              ]
            ]
          ]

          $tbody [
            $tr [
              $td [64 bit int]
              $td [Int]
              $td [
                See 32 bit Int.
              ]
            ]
          ]

          $tbody [
            $tr [
              $td [Decimal128]
              $td [-]
              $td [
                Not yet supported.
              ]
            ]
          ]
        ]
      ]
    ]
  ]

  $sect1 [
    $title [MongoDB servers]
    $para [

    ]

    $sect2 [
      $title [Supported versions]
      $para [

      ]
    ]

    $sect2 [
      $title [mongod]
      $para [

      ]
    ]

    $sect2 [
      $title [mongos]
      $para [

      ]
    ]
  ]

  $sect1 [
    $title [Examples]
    $para [
    ]
    $sect2 [
      $title [Starting and stopping a server using the configuration]
      $para [
        This method, using a configuration file, is also used to test
        the modules to help starting and stopping a locally installed server.
        There are several steps in order to configure it properly.

        $itemizedlist spacing=compact [
          $listitem [
            $emphasis[Configuration file].
          ]

          $listitem [
            $emphasis[Server selection].
          ]

          $listitem [
            $emphasis[Starting and stopping].
          ]
        ]
      ]

      $sect3 [
        $title [Configuration file]
        $para [

        ]
      ]

      $sect3 [
        $title [Server selection]
        $para [

        ]
      ]

      $sect3 [
        $title [Starting and stopping]
        $para [

        ]
      ]
    ]

    $sect2 [
      $title [Making a replica server]
      $para [
      ]

      $sect3 [
        $title [Preparing]
        $para [

        ]
      ]

      $sect3 [
        $title [Initializing]
        $para [

        ]
      ]
    ]

    $sect2 [
      $title [Develop your own set of helper functions]
      $para [
      ]

    ]
  ]

  #-----------------------------------------------------------------------------
  # References to books, websites
  $sect1 [
    $title [References to books, websites, articles and pod-documents]

    $sect2 [
      $title [Web Pages]

      $sect3 [
        $para [
          MongoDB Manual covering all aspects of what is possible.
          Source is from MongoDB, Inc.
          $link xlink:href=http://docs.mongodb.com/master/MongoDB-manual.epub [
            EPub edition
          ]
        ]
      ]
    ]
  ]

  #-----------------------------------------------------------------------------
  # Glossary of things
  $glossary [
    $title [MongoDB Driver Glossary and References]

    $glossdiv [
      $title [B]

      $glossentry xml:id=bson [
        $glossterm [Binary JSON]
        $acronim [JSON]
        $glossdef [
          $para [
            BSON is a computer data interchange format used mainly as a data
            storage and network transfer format in the MongoDB database.
            See also on
            $link xlink:href=https://nl.wikipedia.org/wiki/BSON [
              WikipediA
            ].
          ]
        ]
      ]
    ]


    $glossdiv [
      $title [J]

      $glossentry xml:id=json [
        $glossterm [JavaScript Object Notation]
        $acronim [JSON]
        $glossdef [
          $para [
            JavaScript Object Notation) is an open-standard format that uses
            human-readable text to transmit data objects consisting of
            attribute-value pairs.
            See also on
            $link xlink:href=https://nl.wikipedia.org/wiki/JSON [
              WikipediA
            ].
          ]
        ]
      ]
    ]


    $glossdiv [
      $title [M]

      $glossentry xml:id=mongodb [
        $glossterm [MongoDB]
        $acronim [MongoDB]
        $glossdef [
          $para [
            MongoDB (from humongous) is a free and open-source cross-platform
            document-oriented database program.
          ]
        ]
      ]
    ]


    $glossdiv [
      $title [N]

      $glossentry xml:id=nosql [
        $glossterm [Non SQL]
        $acronim [NoSql]
        $glossdef [
          $para [
            A NoSQL (originally referring to "non $glossterm linkend=sql
            [Structured Query Language]", "non relational" or "not only SQL"
            database provides a mechanism for storage and retrieval of data
            which is modeled in means other than the tabular relations used in
            relational databases.
          ]
        ]
      ]
    ]


    $glossdiv [
      $title [S]

      $glossentry xml:id=sql [
        $glossterm [Structured Query Language]
        $acronim [Sql]
        $glossdef [
          $para [
            SQL or Structured Query Language is a special-purpose
            domain-specific language used in programming and designed for
            managing data held in a relational database management system
            (RDBMS)
          ]
        ]
      ]
    ]
  ]

  $index
]