Metadata-Version: 2.4
Name: xbot.plugins.pgsql
Version: 0.1.1
Summary: PostgreSQL library for xbot.framework
Author-email: zhaowcheng <zhaowcheng@163.com>
License-Expression: BSD-2-Clause
Project-URL: Homepage, https://github.com/zhaowcheng/xbot.plugins.pgsql
Project-URL: Issues, https://github.com/zhaowcheng/xbot.plugins.pgsql/issues
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: xbot.framework>=0.5.1
Requires-Dist: psycopg[binary]<4,>=3
Requires-Dist: cli_helpers
Provides-Extra: dev
Requires-Dist: build; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Dynamic: description
Dynamic: description-content-type
Dynamic: license-file

# xbot.plugins.pgsql

PostgreSQL library for xbot.framework.

## Introduction

A synchronous PostgreSQL client library for [xbot.framework](https://pypi.org/project/xbot.framework/), built on Psycopg 3. It provides a thin connection wrapper with SQLSTATE-based expectation checking, psql-style result rendering, and explicit transaction support.

Python >= 3.10, PostgreSQL >= 14. For full API documentation, refer to the docstrings in each module.

## Installation

```bash
pip install xbot.plugins.pgsql
```

## Getting Started

```python
from xbot.plugins.pgsql import PGCodes, PGSQLConnection

db = PGSQLConnection()
db.connect(
    host="127.0.0.1",
    user="postgres",
    password="secret",
    database="postgres",
)

result = db.exec(
    "SELECT 1::integer AS id, 'alice'::text AS name",
)
print(result)
print(result.header)
print(result.rc)
print(result.cmd)

missing = db.exec(
    "SELECT * FROM missing_table",
    expect=PGCodes.UNDEFINED_TABLE,
)
assert missing.rc == "42P01"

with db.transaction():
    db.exec("INSERT INTO accounts(id, balance) VALUES (1, 100)")

db.disconnect()
```

***

# xbot.plugins.pgsql

xbot.framework 的 PostgreSQL 客户端库。

## 简介

基于 Psycopg 3 的同步 PostgreSQL 客户端库，面向 [xbot.framework](https://pypi.org/project/xbot.framework/)。提供薄封装连接，支持基于 SQLSTATE 的预期检查、psql 风格结果渲染和显式事务。

Python >= 3.10，PostgreSQL >= 14。完整 API 文档请参阅各模块的 docstring。

## 安装

```bash
pip install xbot.plugins.pgsql
```

## 入门

```python
from xbot.plugins.pgsql import PGCodes, PGSQLConnection

db = PGSQLConnection()
db.connect(
    host="127.0.0.1",
    user="postgres",
    password="secret",
    database="postgres",
)

result = db.exec(
    "SELECT 1::integer AS id, 'alice'::text AS name",
)
print(result)
print(result.header)
print(result.rc)
print(result.cmd)

missing = db.exec(
    "SELECT * FROM missing_table",
    expect=PGCodes.UNDEFINED_TABLE,
)
assert missing.rc == "42P01"

with db.transaction():
    db.exec("INSERT INTO accounts(id, balance) VALUES (1, 100)")

db.disconnect()
```
