pgwire 0.6.1

Postgresql wire protocol implemented as a library
Documentation

pgwire

CI Docs

This library implements PostgreSQL Wire Protocol, and provide essential APIs to write PostgreSQL comptible servers and clients.

This library is a work in progress.

Status

  • Message format
  • Backend TCP/TLS server on Tokio
  • Frontend-Backend interaction over TCP
    • SSL Request and Response
    • Startup
      • No authentication
      • Clear-text password authentication
      • Md5 Password authentication
      • SASL SCRAM authentication
    • Simple Query and Response
    • Extended Query and Response
      • Parse
      • Bind
      • Execute
      • Describe
      • Sync
    • Termination
    • Cancel
    • Error and Notice
    • Copy
  • APIs
    • Startup APIs
      • Password authentication
      • Server parameters API, ready but not very good
    • Simple Query API
    • Extended Query API, verification required
      • Portal API, implemented but not perfect
    • ResultSet builder/encoder API
    • Query Cancellation API
    • Error and Notice API

Usage

Server/Backend

To use pgwire in your server application, you will need to implement two key components: startup processor and query processor. For query processing, there are two kinds of queries: simple and extended. In simple mode, the sql command is passed to postgresql server as a string. In extended query mode, a sql command follows parse-bind-describe(optional)-execute lifecycle.

Examples are provided to demo the very basic usage of pgwire on server side:

  • examples/sqlite.rs: uses an in-memory sqlite database at its core and serves it with postgresql protocol.
  • examples/gluesql.rs: uses an in-memory gluesql at its core and serves it with postgresql protocol.
  • examples/server.rs: demos a server that always returns fixed results.
  • examples/secure_server.rs: demos a server with ssl support and always returns fixed results.

Client/Frontend

I think in most case you do not need pgwire to build a postgresql client, existing postgresql client like rust-postgres should fit your scenarios. Please rise an issue if there is a scenario.

License

This library is released under MIT/Apache dual license.