pgwire 0.11.1

Postgresql wire protocol implemented as a library
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92

# pgwire

[![CI](https://github.com/sunng87/pgwire/actions/workflows/ci.yml/badge.svg)](https://github.com/sunng87/pgwire/actions/workflows/ci.yml)
[![](https://img.shields.io/crates/v/pgwire)](https://crates.io/crates/pgwire)
[![Docs](https://docs.rs/pgwire/badge.svg)](https://docs.rs/pgwire/latest/pgwire/)


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

This library is a work in progress and in its relatively early stage. There is
no guarantee for API stability. I'm constantly introducing break changes during
this period. And also sorry for lack of API docs, examples may get you familiar
with its usage.

## Status

- [x] Message format
- [x] Backend TCP/TLS server on Tokio
- [ ] Frontend-Backend interaction over TCP
  - [x] SSL Request and Response
  - [x] Startup
    - [x] No authentication
    - [x] Clear-text password authentication
    - [x] Md5 Password authentication
    - [x] SASL SCRAM authentication
      - [x] SCRAM-SHA-256
      - [x] SCRAM-SHA-256-PLUS
  - [x] Simple Query and Response
  - [x] Extended Query and Response
    - [x] Parse
    - [x] Bind
    - [x] Execute
    - [x] Describe
    - [x] Sync
  - [x] Termination
  - [x] Cancel
  - [x] Error and Notice
  - [ ] Copy
- [ ] APIs
  - [x] Startup APIs
    - [x] AuthSource API, fetching and hashing passwords
    - [x] Server parameters API, ready but not very good
  - [x] Simple Query API
  - [x] Extended Query API
    - [x] QueryParser API, for transforming prepared statement
    - [x] PortalStore API, for caching statements and portals
  - [x] ResultSet builder/encoder API
  - [ ] Query Cancellation API
  - [x] 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](https://github.com/gluesql/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](https://github.com/sfackler/rust-postgres) should fit your
scenarios. Please rise an issue if there is a scenario.

## Projects using pgwire

* [GreptimeDB](https://github.com/GrepTimeTeam/greptimedb): Cloud-native
  time-series database
* [sqld](https://github.com/libsql/sqld): A server frontend for
  [libSQL](https://github.com/libsql/libsql)
* [risinglight](https://github.com/risinglightdb/risinglight): OLAP database
  system for educational purpose

## License

This library is released under MIT/Apache dual license.