{"id":17674124,"url":"https://github.com/leont/protocol-postgres","last_synced_at":"2025-03-30T16:25:31.215Z","repository":{"id":66522635,"uuid":"456575347","full_name":"Leont/protocol-postgres","owner":"Leont","description":"A asynchronous postgres client library for Raku","archived":false,"fork":false,"pushed_at":"2023-07-10T11:56:02.000Z","size":118,"stargazers_count":1,"open_issues_count":1,"forks_count":2,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-02-05T18:05:53.543Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Raku","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"artistic-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Leont.png","metadata":{"files":{"readme":"README.md","changelog":"Changes","contributing":null,"funding":null,"license":"LICENSE","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":"2022-02-07T15:59:20.000Z","updated_at":"2022-02-21T15:08:08.000Z","dependencies_parsed_at":null,"dependency_job_id":"df3a44e5-2fdd-4ea1-9b05-ab51e43de1a9","html_url":"https://github.com/Leont/protocol-postgres","commit_stats":null,"previous_names":[],"tags_count":12,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Leont%2Fprotocol-postgres","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Leont%2Fprotocol-postgres/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Leont%2Fprotocol-postgres/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Leont%2Fprotocol-postgres/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Leont","download_url":"https://codeload.github.com/Leont/protocol-postgres/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246345076,"owners_count":20762324,"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-24T06:42:09.637Z","updated_at":"2025-03-30T16:25:31.190Z","avatar_url":"https://github.com/Leont.png","language":"Raku","readme":"[![Actions Status](https://github.com/Leont/protocol-postgres/workflows/test/badge.svg)](https://github.com/Leont/protocol-postgres/actions)\n\nName\n====\n\nProtocol::Postgres - a sans-io postgresql client\n\nSynopsis\n========\n\n```raku\nuse v6.d;\nuse Protocol::Postgres;\n\nmy $socket = await IO::Socket::Async.connect($host, $port);\nmy $client = Protocol::Postgres::Client.new;\n$socket.Supply(:bin).act({ $client.incoming-data($^data) });\n$client.outbound-data.act({ $socket.write($^data) });\n\nawait $client.startup($user, $database, $password);\n\nmy $resultset = await $client.query('SELECT * FROM foo WHERE id = $1', [ 42 ]);\nreact {\n\twhenever $resultset.hash-rows -\u003e (:$name, :$description, :$id) {\n\t\tsay \"$name is $description\";\n\t}\n}\n```\n\nDescription\n===========\n\nProtocol::Postgres is sans-io implementation of (the client side of) the postgresql protocol. It is typically used through the `Protocol::Postgres::Client` class.\n\nClient\n======\n\n`Protocol::Postgres::Client` has the following methods\n\nnew(--\u003e Protocol::Postgres::Client)\n-----------------------------------\n\nThis creates a new postgres client. It supports one optional named argument:\n\n  * TypeMap :$typemap = TypeMap::JSON\n\n    This is the typemap that is used to translate between Raku's and Postgres' typesystem. The default mapping supports common built-in types such as strings, numbers, bools, dates, datetimes, blobs, arrays and hashes. Other options include `TypeMap::Native` if you want arrays to map to postgres' native arrays and `TypeMap::Minimal` if one wants all values to map to strings.\n\noutgoing-data(--\u003e Supply)\n-------------------------\n\nThis returns a `Supply` of `Blob`s to be written to the server.\n\nincoming-data(Blob --\u003e Nil)\n---------------------------\n\nThis consumes bytes received from the server.\n\nstartup($user, $database?, $password? --\u003e Promise)\n--------------------------------------------------\n\nThis starts the handshake to the server. `$database` may be left undefined, the server will use `$user` as database name. If a `$password` is defined, any of clearnext, md5 or SCRAM-SHA-256 based authentication is supported.\n\nThe resulting promise will finish when the connection is ready for queries.\n\nquery($query, @bind-values --\u003e Promise)\n---------------------------------------\n\nThis will issue a query with the given bind values, and return a promise to the result.\n\nFor fetching queries such as `SELECT` the result in the promise will be a `ResultSet` object, for manipulation (e.g. `INSERT`) and definition (e.g. `CREATE`) queries it will result a string describing the change (e.g. `DELETE 3`). For a `COPY FROM` query it will `Supply` with the data stream, and for `COPY TO` it will be a `Supplier`.\n\nBoth the input types and the output types will be typemapped between Raku types and Postgres types using the typemapper.\n\nquery-multiple($query --\u003e Supply[ResultSet])\n--------------------------------------------\n\nThis will issue a complex query that may contain multiple statements, but can not use bind values. It will return a `Supply` to the results of each query.\n\nprepare($query, :@input-types --\u003e Promise[PreparedStatement])\n-------------------------------------------------------------\n\nThis prepares the query, and returns a Promise to the PreparedStatement object. `@input-types` can be used to pass on hints about the types you're passing in during `execute`.\n\nmethod get-channel(Str $name --\u003e Supply)\n----------------------------------------\n\nThis returns the `Supply` for the given channel.\n\nadd-enum-type(Str $name, ::Enum --\u003e Promise)\n--------------------------------------------\n\nThis looks up the `oid` of postgres enum `$name`, and adds an appriopriate `Type` object to the typemap to convert it from/to `Enum`.\n\nadd-composite-type(Str $name, ::Composite, Bool :$positional --\u003e Promise)\n-------------------------------------------------------------------------\n\nThis looks up the `oid` of the postgres composite type \u003c$name\u003e, and maps it to `Composite`; if `$positional` is set it will use positional constructor arguments, otherwise named ones are used; it will use a heuristic by default.\n\nadd-custom-type(Str $name, ::Custom, \u0026from-string?, \u0026to-string?)\n----------------------------------------------------------------\n\nThis adds a custom converter from postgres type `$name` from/to Raku type `Custom`. By default `\u0026from-string` will do a coercion, and `\u0026to-string` will do stringification.\n\nstartTls(--\u003e Blob)\n------------------\n\nThis will return the marker that should be written to the server to start upgrading the connection to use TLS. If the server responds with a single `S` byte the proposal is accepted and the client is expected to initiate the TLS handshake. If the server responds with an `N` it is rejected, and the connection proceeds in cleartext.\n\nterminate(--\u003e Nil)\n------------------\n\nThis sends a message to the server to terminate the connection\n\ndisconnected(--\u003e Promise)\n-------------------------\n\nThis returns a `Promise` that must be be kept or broken to signal the connection is lost.\n\nquery-status(--\u003e Protocol::Postgres::QueryStatus)\n-------------------------------------------------\n\nThis returns the query status as of the last finished query as a `enum Protocol::Postgres::QueryStatus` value: `Idle` (No transaction is active), `Transaction` (A transaction is currently in progress) or `Error` (The current transaction has failed and needs to be rolled back).\n\nprocess-id(--\u003e Int)\n-------------------\n\nThis returns the process id of the backend of this connection. This is useful for debugging purposes and for notifications.\n\nget-parameter(Str $name --\u003e Str)\n--------------------------------\n\nThis returns various parameters, currently known parameters are: `server_version`, `server_encoding`, `client_encoding`, `application_name`, `default_transaction_read_only`, `in_hot_standby`, `is_superuser`, `session_authorization`, `DateStyle`, `IntervalStyle`, `TimeZone`, `integer_datetimes`, and `standard_conforming_strings`.\n\nResultSet\n=========\n\nA `Protocol::Postgres::ResultSet` represents the results of a query, if any.\n\ncolumns(--\u003e List)\n-----------------\n\nThis returns the column names for this resultset.\n\nrows(--\u003e Supply[List])\n----------------------\n\nThis returns a Supply of rows. Each row is a list of values.\n\nhash-rows(--\u003e Supply[Hash])\n---------------------------\n\nThis returns a Supply of rows. Each row is a hash with the column names as keys and the row values as values.\n\nobject-rows(::Class, Bool :$positional --\u003e Supply[Class])\n---------------------------------------------------------\n\nThis returns a Supply of objects of class `Class`, each object is constructed form the row hash unless positional is true in which case it's constructed from the row list.\n\narrays\n------\n\nThis returns a sequence of arrays of results from all rows. This may `await`.\n\narray\n-----\n\nThis returns a single array of results from one row. This may `await`.\n\nvalue\n-----\n\nThis returns a single value from a single row. This may `await`.\n\nhashes\n------\n\nThis returns a sequence of hashes of the results from all rows. This may `await`.\n\nhash\n----\n\nThis returns a single hash of the results from one rows. This may `await`.\n\nobjects(::Class, Bool :$positional)\n-----------------------------------\n\nThis returns a sequence of objects based on all the rows. This may `await`.\n\nobject(:Class, Bool :$positional)\n---------------------------------\n\nThis returns a single object based on a single row. This may `await`.\n\nPreparedStatement\n=================\n\nA `Protocol::Postgres::PreparedStatement` represents a prepated statement. Its reason of existence is to call `execute` on it.\n\nexecute(@arguments --\u003e Promise[ResultSet])\n------------------------------------------\n\nThis runs the prepared statement, much like the `query` method would have done.\n\nclose()\n-------\n\nThis closes the prepared statement.\n\ncolumns()\n---------\n\nThis returns the columns of the result once executed.\n\nNotification\n============\n\n`Protocol::Postgres::Notification` has the following methods:\n\nsender(--\u003e Int)\n---------------\n\nThis is the process-id of the sender\n\nchannel(--\u003e Str)\n----------------\n\nThis is the name of the channel that the notification was sent on\n\nmessage(--\u003e Str)\n----------------\n\nThis is the message of the notification\n\nAuthor\n======\n\nLeon Timmermans \u003cfawaka@gmail.com\u003e\n\nCopyright and License\n=====================\n\nCopyright 2022 Leon Timmermans\n\nThis library is free software; you can redistribute it and/or modify it under the Artistic License 2.0.\n\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fleont%2Fprotocol-postgres","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fleont%2Fprotocol-postgres","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fleont%2Fprotocol-postgres/lists"}