{"id":15514716,"url":"https://github.com/fgasper/p5-mongodb-xs","last_synced_at":"2025-03-28T19:21:31.728Z","repository":{"id":65696466,"uuid":"590163561","full_name":"FGasper/p5-MongoDB-XS","owner":"FGasper","description":"CPAN’s MongoDB::XS","archived":false,"fork":false,"pushed_at":"2023-02-13T03:03:34.000Z","size":117,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-02-02T20:49:54.777Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Perl","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/FGasper.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-01-17T19:43:43.000Z","updated_at":"2023-02-07T02:28:34.000Z","dependencies_parsed_at":"2023-02-18T21:15:33.227Z","dependency_job_id":null,"html_url":"https://github.com/FGasper/p5-MongoDB-XS","commit_stats":{"total_commits":88,"total_committers":2,"mean_commits":44.0,"dds":"0.011363636363636354","last_synced_commit":"14f2a0fe79442abc3294c862aeedf3d1d995a891"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FGasper%2Fp5-MongoDB-XS","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FGasper%2Fp5-MongoDB-XS/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FGasper%2Fp5-MongoDB-XS/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FGasper%2Fp5-MongoDB-XS/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/FGasper","download_url":"https://codeload.github.com/FGasper/p5-MongoDB-XS/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246085655,"owners_count":20721213,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-02T10:00:25.058Z","updated_at":"2025-03-28T19:21:31.704Z","avatar_url":"https://github.com/FGasper.png","language":"Perl","funding_links":[],"categories":[],"sub_categories":[],"readme":"# NAME\n\nMongoDB::XS - [MongoDB](https://mongodb.com) in Perl via C/XS.\n\n# SYNOPSIS\n\n    use MongoDB::XS;\n\n    # This sample code uses AnyEvent for demonstration only;\n    # any event interface will work.\n    use AnyEvent;\n\n    my $mdb = MongoDB::XS-\u003enew(\"mongodb://127.0.0.1\");\n\n    my $cv = AE::cv();\n\n    # When the fd is readable there is at least one result pending.\n    my $w = AE::io( $mdb-\u003efd(), 0, sub {\n        $mdb-\u003eprocess();\n        $cv-\u003esend();\n    } );\n\n    my $request_bson = MongoDB::XS::ejson2bson('{\"hello\": 1}');\n\n    $mdb-\u003erun_command(\n        'admin',\n        $request_bson,\n        sub ($resp) {\n            if ($resp isa Mongo::DB::Error) {\n                warn $resp;\n            }\n            else {\n                # Success! $resp is a BSON string.\n                # Parse it, and be on your way.\n            }\n        },\n    );\n\n    $cv-\u003erecv();\n\n# DESCRIPTION\n\nThis library provides MongoDB support in Perl\nvia an XS binding to MongoDB’s official C driver,\n[MongoC](https://mongoc.org).\n\nThis is a research project, **NOT** an official MongoDB driver.\n\n# DESIGN\n\nThis module attempts to avoid blocking Perl.\nToward that end, each instance runs “behind” Perl in a separate\nthread; a pollable file descriptor facilitates event loop integration.\n\nThere is no attempt here to replicate the extensive interfaces found\nin official MongoDB drivers. Instead, this module provides a\nminimal interface that should nevertheless expose most useful MongoDB\nclient functionality.\n\nFor example, to use a\n[change stream](https://www.mongodb.com/docs/manual/changeStreams/),\nrun the\n[aggregate](https://www.mongodb.com/docs/manual/reference/command/aggregate/)\ncommand with a\n[$changeStream](https://www.mongodb.com/docs/manual/reference/operator/aggregation/changeStream/). This will return a cursor, which you can give to\n[getMore](https://www.mongodb.com/docs/manual/reference/command/getMore/)\nto receive successive pieces of the change stream.\n\nAlso see `/examples` in the distribution.\n\n# BSON\n\nSeveral interfaces here expect and return raw [BSON](https://bsonspec.org)\n(MongoDB’s binary JSON variant).\n\nHow you create \u0026 parse the BSON is up to you.\nCPAN offers [multiple BSON modules](https://metacpan.org/search?q=bson);\nalternatively, you can use [JSON::PP](https://metacpan.org/pod/JSON%3A%3APP) or some other JSON module\nwith this module’s BSON/JSON conversion functions (see below).\n\n# STATUS\n\nThis module is experimental; its interface is subject to change.\nIt’s been stable for the author as an alternative to\n`mongosh`, but YMMV.\n\n# NOTES\n\nThis library never calls\n[mongoc\\_cleanup()](http://mongoc.org/libmongoc/current/mongoc_cleanup.html).\n\n# SEE ALSO\n\nMongoDB’s [now-discontinued official Perl driver](https://metacpan.org/pod/MongoDB) is the\nobvious point of reference.\n\n# GENERAL-USE METHODS\n\nMost of the below run asynchronously.\n\n## $obj = _CLASS_-\u003enew( $URI )\n\nInstantiates _CLASS_ with the given $URI.\n\nNB: This may block briefly for DNS lookups.\n\n## $obj = _OBJ_-\u003erun\\_command( $REQUEST\\_BSON, \\\\\u0026CALLBACK )\n\nSends a request (encoded as BSON) to MongoDB.\n(See\n[mongoc\\_client\\_command\\_simple](http://mongoc.org/libmongoc/current/mongoc_client_command_simple.html) for details.)\n\nThe $CALLBACK receives either:\n\n- A raw BSON string (to indicate success).\n- A [MongoDB::XS::Error](https://metacpan.org/pod/MongoDB%3A%3AXS%3A%3AError) object.\n\nExceptions that escape the callback are trapped and reported\nas warnings.\n\n## _OBJ_-\u003eget\\_read\\_concern( \\\\\u0026CALLBACK )\n\nCalls \u0026CALLBACK with a string that represents _OBJ_’s active read concern,\nor undef if there is none.\n\nThe string should match the value of one of the read-concern\nconstants mentioned below.\n\n## _OBJ_-\u003eset\\_read\\_concern( $LEVEL \\[, \\\\\u0026CALLBACK \\] )\n\nSets the client’s read concern. $LEVEL should be one of the\nread-concern constants mentioned below.\n\n\u0026CALLBACK, if given, is called with no parameters whenever the request\ncompletes.\n\n## _OBJ_-\u003eget\\_write\\_concern( \\\\\u0026CALLBACK )\n\nCalls \u0026CALLBACK with a reference to a hash that represents _OBJ_’s active\nwrite concern. The hash contents are `w`, `j`, and `wtimeout`;\nsee [MongoDB’s documentation](https://www.mongodb.com/docs/manual/reference/write-concern/) for details of what these mean.\n\n(Undef values indicate that no value has been set, so the default\nis active.)\n\n## $obj = _OBJ_-\u003eset\\_write\\_concern( \\\\%WC \\[, \\\\\u0026CALLBACK \\] )\n\n`get_write_concern()`’s complement. It expects the same hash\nreference. Individual values can be omitted (or left undef) to\nindicate a default value.\n\nFor example, the following:\n\n    {\n        w        =\u003e 1,\n        j        =\u003e undef,\n        wtimeout =\u003e 7,\n    }\n\n… indicates the default value for `j` but explicit values\nfor `w` and `wtimeout`.\n\n\u0026CALLBACK, if given, is called with no parameters whenever the request\ncompletes.\n\n# CONSTANTS\n\n- READ\\_CONCERN\\_LOCAL, READ\\_CONCERN\\_MAJORITY,\nREAD\\_CONCERN\\_LINEARIZABLE, READ\\_CONCERN\\_AVAILABLE,\nand READ\\_CONCERN\\_SNAPSHOT\n\n# EVENT LOOP INTEGRATION METHODS\n\n## _OBJ_-\u003eprocess()\n\nReads any queued request results and calls their associated\ncallbacks.\n\n## $fd = _OBJ_-\u003efd()\n\nReturns the OS file descriptor that, when readable, indicates\nthat at least one result is ready for `process()`ing.\n\n**NOTE:** Some Perl event libraries only interact with Perl filehandles.\nFor these libraries you can do:\n\n    use POSIX ();\n\n    my $fd_dup = POSIX::dup($mdb-\u003efd()) or die \"dup: $!\";\n\n    open my $mdb_fh, '+\u003e\u0026', $fd_dup or die \"open(dup): $!\";\n\n(The `dup()` ensures that, when Perl closes $mdb\\_fh, it won’t affect\nmongoc.)\n\n# STATIC FUNCTIONS\n\n## $str = mongoc\\_version\\_string()\n\nReturns MongoC’s version as a string.\n\n## $json = bson2cejson( $BSON )\n\nConverts BSON to\n[Canonical Extended JSON](https://github.com/mongodb/specifications/blob/master/source/extended-json.rst).\n\n## $json = bson2rejson( $BSON )\n\nConverts BSON to\n[Relaxed Extended JSON](https://github.com/mongodb/specifications/blob/master/source/extended-json.rst).\n\n## $bson = ejson2bson( $EXT\\_JSON )\n\nConverts Extended JSON (either variant??) to a raw BSON string.\n\n# LICENSE \u0026 COPYRIGHT\n\nCopyright 2023 by Gasper Software Consulting. All rights reserved.\n\nThis library is licensed under the same license as Perl itself.\nSee [perlartistic](https://metacpan.org/pod/perlartistic).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffgasper%2Fp5-mongodb-xs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffgasper%2Fp5-mongodb-xs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffgasper%2Fp5-mongodb-xs/lists"}