xbot.plugins.pgsql 0.1.0__py3-none-any.whl

tests/run.py

@@ -0,0 +1,36 @@
+"""
+Run tests against a caller-provided PostgreSQL server.
+"""
+
+import argparse
+import unittest
+from pathlib import Path
+
+from test_pgsql import TestPGSQLConnection
+
+
+def create_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("-H", "--host", required=True)
+    parser.add_argument("-P", "--port", type=int, default=5432)
+    parser.add_argument("-u", "--user", required=True)
+    parser.add_argument("-p", "--password", required=True)
+    parser.add_argument("-d", "--database", required=True)
+    return parser
+
+
+def main() -> int:
+    args = create_parser().parse_args()
+    TestPGSQLConnection.HOST = args.host
+    TestPGSQLConnection.PORT = args.port
+    TestPGSQLConnection.USER = args.user
+    TestPGSQLConnection.PASSWORD = args.password
+    TestPGSQLConnection.DATABASE = args.database
+
+    suite = unittest.TestLoader().discover(str(Path(__file__).parent))
+    result = unittest.TextTestRunner(verbosity=2).run(suite)
+    return 0 if result.wasSuccessful() else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

tests/test_pgsql.py

@@ -0,0 +1,254 @@
+import unittest
+
+import uuid
+from typing import ClassVar
+from unittest.mock import patch
+
+from xbot.plugins.pgsql import PGCodes
+from xbot.plugins.pgsql import PGSQLCommandError
+from xbot.plugins.pgsql import PGSQLCommandResult
+from xbot.plugins.pgsql import PGSQLConnectError
+from xbot.plugins.pgsql import PGSQLConnection
+
+
+class TestPGSQLCommandResult(unittest.TestCase):
+    def test_is_list_with_metadata(self) -> None:
+        result = PGSQLCommandResult(
+            [(1, 'alice'), (2, 'bob')],
+            header=('id', 'name'),
+            rc='00000',
+            cmd='SELECT id, name FROM users ORDER BY id',
+        )
+
+        self.assertIsInstance(result, list)
+        self.assertEqual(result, [(1, 'alice'), (2, 'bob')])
+        self.assertEqual(result.header, ('id', 'name'))
+        self.assertEqual(result.rc, '00000')
+        self.assertEqual(result.cmd, 'SELECT id, name FROM users ORDER BY id')
+        self.assertEqual(repr(result), "[(1, 'alice'), (2, 'bob')]")
+
+    def test_str_is_live_psql_table_with_header(self) -> None:
+        result = PGSQLCommandResult(
+            [(1, 'alice')],
+            header=('id', 'name'),
+            rc='00000',
+            cmd="SELECT 1, 'alice'",
+        )
+        first_render = str(result)
+        self.assertIn('id', first_render)
+        self.assertIn('name', first_render)
+        self.assertIn('alice', first_render)
+
+        result.append((2, 'bob'))
+        self.assertIn('bob', str(result))
+
+
+class TestPGSQLConnection(unittest.TestCase):
+    HOST: ClassVar[str] = ''
+    PORT: ClassVar[int] = 5432
+    USER: ClassVar[str] = ''
+    PASSWORD: ClassVar[str] = ''
+    DATABASE: ClassVar[str] = ''
+    connection: ClassVar[PGSQLConnection]
+    schema: ClassVar[str] = f'xbot_pgsql_{uuid.uuid4().hex}'
+
+    @classmethod
+    def setUpClass(cls) -> None:
+        cls.connection = cls.new_connection()
+        cls.connection.exec(f'CREATE SCHEMA "{cls.schema}"')
+        cls.connection.exec(f'SET search_path TO "{cls.schema}"')
+
+    @classmethod
+    def tearDownClass(cls) -> None:
+        if cls.connection is not None:
+            cls.connection.exec(
+                f'DROP SCHEMA IF EXISTS "{cls.schema}" CASCADE',
+                expect=None,
+            )
+            cls.connection.disconnect()
+
+    @classmethod
+    def new_connection(cls) -> PGSQLConnection:
+        connection = PGSQLConnection()
+        connection.connect(
+            cls.HOST,
+            cls.USER,
+            cls.PASSWORD,
+            cls.DATABASE,
+            cls.PORT,
+        )
+        return connection
+
+    def test_connect_is_idempotent(self) -> None:
+        connection = self.new_connection()
+        try:
+            first = connection._conn
+            connection.connect(
+                self.HOST,
+                self.USER,
+                self.PASSWORD,
+                self.DATABASE,
+                self.PORT,
+            )
+            self.assertIs(connection._conn, first)
+        finally:
+            connection.disconnect()
+
+    def test_disconnect_is_idempotent(self) -> None:
+        connection = self.new_connection()
+        connection.disconnect()
+        connection.disconnect()
+
+    def test_invalid_database_raises_connect_error(self) -> None:
+        connection = PGSQLConnection()
+        invalid_database = f'xbot_missing_{uuid.uuid4().hex}'
+        with self.assertRaises(PGSQLConnectError) as caught:
+            connection.connect(
+                self.HOST,
+                self.USER,
+                self.PASSWORD,
+                invalid_database,
+                self.PORT,
+            )
+
+    def test_exec_select_returns_rows_and_header(self) -> None:
+        result = self.connection.exec(
+            "SELECT 1::integer AS id, 'alice'::text AS name"
+        )
+        self.assertEqual(result, [(1, 'alice')])
+        self.assertEqual(result.header, ('id', 'name'))
+        self.assertEqual(result.rc, '00000')
+        self.assertIn('alice', str(result))
+
+    def test_exec_ddl_dml_returning(self) -> None:
+        table = f'items_{uuid.uuid4().hex}'
+        ddl = self.connection.exec(
+            f'CREATE TABLE "{table}" (id integer, name text)'
+        )
+        self.assertEqual(ddl, [])
+        self.assertEqual(ddl.header, ())
+
+        inserted = self.connection.exec(
+            f"""INSERT INTO "{table}" VALUES (1, 'alice') RETURNING id, name""",
+        )
+        self.assertEqual(inserted, [(1, 'alice')])
+        self.assertEqual(inserted.header, ('id', 'name'))
+
+    def test_exec_expected_sqlstate_returns_result(self) -> None:
+        result = self.connection.exec(
+            'SELECT * FROM missing_table_expected',
+            expect=PGCodes.UNDEFINED_TABLE,
+        )
+        self.assertEqual(result, [])
+        self.assertEqual(result.header, ())
+        self.assertEqual(result.rc, '42P01')
+
+    def test_exec_none_expect_accepts_success_and_failure(self) -> None:
+        success = self.connection.exec('SELECT 1', expect=None)
+        failure = self.connection.exec(
+            'SELECT * FROM missing_table_none',
+            expect=None,
+        )
+        self.assertEqual(success.rc, '00000')
+        self.assertEqual(failure.rc, '42P01')
+
+    def test_exec_default_expect_raises_on_error(self) -> None:
+        with self.assertRaises(PGSQLCommandError) as caught:
+            self.connection.exec('SELECT * FROM missing_table_default')
+
+        self.assertEqual(caught.exception.result.rc, '42P01')
+        self.assertEqual(caught.exception.expect, PGCodes.SUCCESSFUL_COMPLETION)
+
+    def test_exec_mismatched_expect_raises(self) -> None:
+        with self.assertRaises(PGSQLCommandError) as caught:
+            self.connection.exec(
+                'SELECT 1',
+                expect=PGCodes.UNDEFINED_TABLE,
+            )
+        self.assertEqual(caught.exception.result.rc, '00000')
+        self.assertIs(caught.exception.expect, PGCodes.UNDEFINED_TABLE)
+
+    def test_exec_multiple_statements_returns_syntax_error(self) -> None:
+        result = self.connection.exec(
+            'SELECT 1; SELECT 2',
+            expect=PGCodes.SYNTAX_ERROR,
+        )
+        self.assertEqual(result.rc, '42601')
+
+    def test_transaction_commits(self) -> None:
+        table = f'tx_commit_{uuid.uuid4().hex}'
+        self.connection.exec(
+            f'CREATE TABLE "{table}" (id integer PRIMARY KEY)'
+        )
+
+        with self.connection.transaction():
+            self.connection.exec(f'INSERT INTO "{table}" VALUES (1)')
+
+        rows = self.connection.exec(
+            f'SELECT id FROM "{table}" ORDER BY id'
+        )
+        self.assertEqual(rows, [(1,)])
+
+    def test_transaction_rolls_back_on_exception(self) -> None:
+        table = f'tx_rollback_{uuid.uuid4().hex}'
+        self.connection.exec(
+            f'CREATE TABLE "{table}" (id integer PRIMARY KEY)'
+        )
+
+        with self.assertRaises(RuntimeError):
+            with self.connection.transaction():
+                self.connection.exec(f'INSERT INTO "{table}" VALUES (1)')
+                raise RuntimeError('rollback')
+
+        rows = self.connection.exec(
+            f'SELECT id FROM "{table}" ORDER BY id'
+        )
+        self.assertEqual(rows, [])
+
+    def test_nested_transaction_uses_savepoint(self) -> None:
+        table = f'nested_{uuid.uuid4().hex}'
+        self.connection.exec(
+            f'CREATE TABLE "{table}" (id integer PRIMARY KEY)'
+        )
+
+        with self.connection.transaction():
+            self.connection.exec(f'INSERT INTO "{table}" VALUES (1)')
+            with self.assertRaises(RuntimeError):
+                with self.connection.transaction():
+                    self.connection.exec(
+                        f'INSERT INTO "{table}" VALUES (2)'
+                    )
+                    raise RuntimeError('rollback inner')
+            self.connection.exec(f'INSERT INTO "{table}" VALUES (3)')
+
+        rows = self.connection.exec(
+            f'SELECT id FROM "{table}" ORDER BY id'
+        )
+        self.assertEqual(rows, [(1,), (3,)])
+
+    def test_complete_public_api(self) -> None:
+        self.assertTrue(issubclass(PGSQLCommandError, Exception))
+        self.assertTrue(issubclass(PGSQLConnectError, Exception))
+        self.assertTrue(issubclass(PGSQLCommandResult, list))
+        self.assertTrue(issubclass(PGSQLConnection, object))
+        self.assertEqual(PGCodes.SUCCESSFUL_COMPLETION.value, '00000')
+
+    def test_connect_log_does_not_contain_password(self) -> None:
+        connection = PGSQLConnection()
+        with patch.object(connection._logger, 'info') as info:
+            connection.connect(
+                self.HOST,
+                self.USER,
+                self.PASSWORD,
+                self.DATABASE,
+                self.PORT,
+            )
+        try:
+            calls = '\n'.join(str(call) for call in info.call_args_list)
+            self.assertNotIn(self.PASSWORD, calls)
+        finally:
+            connection.disconnect()
+
+
+if __name__ == '__main__':
+    unittest.main(verbosity=2)

xbot/plugins/pgsql/__init__.py

@@ -0,0 +1,17 @@
+"""
+PostgreSQL plugin for xbot.framework.
+"""
+
+from xbot.plugins.pgsql.codes import PGCodes
+from xbot.plugins.pgsql.errors import PGSQLCommandError, PGSQLConnectError
+from xbot.plugins.pgsql.pgsql import PGSQLCommandResult, PGSQLConnection
+from xbot.plugins.pgsql.version import __version__
+
+__all__ = [
+    'PGCodes',
+    'PGSQLCommandError',
+    'PGSQLCommandResult',
+    'PGSQLConnectError',
+    'PGSQLConnection',
+    '__version__',
+]

xbot/plugins/pgsql/codes.py

@@ -0,0 +1,363 @@
+"""
+PostgreSQL 14-18 SQLSTATE codes.
+"""
+
+from enum import Enum, unique
+
+
+@unique
+class PGCodes(str, Enum):
+    """
+    PostgreSQL 14-18 official SQLSTATE codes.
+    """
+
+    # Class 00 - Successful Completion
+    SUCCESSFUL_COMPLETION = '00000'
+
+    # Class 01 - Warning
+    WARNING = '01000'
+    NULL_VALUE_ELIMINATED_IN_SET_FUNCTION = '01003'
+    STRING_DATA_RIGHT_TRUNCATION_01 = '01004'
+    PRIVILEGE_NOT_REVOKED = '01006'
+    PRIVILEGE_NOT_GRANTED = '01007'
+    IMPLICIT_ZERO_BIT_PADDING = '01008'
+    DYNAMIC_RESULT_SETS_RETURNED = '0100C'
+    DEPRECATED_FEATURE = '01P01'
+
+    # Class 02 - No Data (this is also a warning class per the SQL standard)
+    NO_DATA = '02000'
+    NO_ADDITIONAL_DYNAMIC_RESULT_SETS_RETURNED = '02001'
+
+    # Class 03 - SQL Statement Not Yet Complete
+    SQL_STATEMENT_NOT_YET_COMPLETE = '03000'
+
+    # Class 08 - Connection Exception
+    CONNECTION_EXCEPTION = '08000'
+    SQLCLIENT_UNABLE_TO_ESTABLISH_SQLCONNECTION = '08001'
+    CONNECTION_DOES_NOT_EXIST = '08003'
+    SQLSERVER_REJECTED_ESTABLISHMENT_OF_SQLCONNECTION = '08004'
+    CONNECTION_FAILURE = '08006'
+    TRANSACTION_RESOLUTION_UNKNOWN = '08007'
+    PROTOCOL_VIOLATION = '08P01'
+
+    # Class 09 - Triggered Action Exception
+    TRIGGERED_ACTION_EXCEPTION = '09000'
+
+    # Class 0A - Feature Not Supported
+    FEATURE_NOT_SUPPORTED = '0A000'
+
+    # Class 0B - Invalid Transaction Initiation
+    INVALID_TRANSACTION_INITIATION = '0B000'
+
+    # Class 0F - Locator Exception
+    LOCATOR_EXCEPTION = '0F000'
+    INVALID_LOCATOR_SPECIFICATION = '0F001'
+
+    # Class 0L - Invalid Grantor
+    INVALID_GRANTOR = '0L000'
+    INVALID_GRANT_OPERATION = '0LP01'
+
+    # Class 0P - Invalid Role Specification
+    INVALID_ROLE_SPECIFICATION = '0P000'
+
+    # Class 0Z - Diagnostics Exception
+    DIAGNOSTICS_EXCEPTION = '0Z000'
+    STACKED_DIAGNOSTICS_ACCESSED_WITHOUT_ACTIVE_HANDLER = '0Z002'
+
+    # Class 10 - XQuery Error
+    INVALID_ARGUMENT_FOR_XQUERY = '10608'
+
+    # Class 20 - Case Not Found
+    CASE_NOT_FOUND = '20000'
+
+    # Class 21 - Cardinality Violation
+    CARDINALITY_VIOLATION = '21000'
+
+    # Class 22 - Data Exception
+    DATA_EXCEPTION = '22000'
+    STRING_DATA_RIGHT_TRUNCATION_22 = '22001'
+    NULL_VALUE_NO_INDICATOR_PARAMETER = '22002'
+    NUMERIC_VALUE_OUT_OF_RANGE = '22003'
+    NULL_VALUE_NOT_ALLOWED_22 = '22004'
+    ERROR_IN_ASSIGNMENT = '22005'
+    INVALID_DATETIME_FORMAT = '22007'
+    DATETIME_FIELD_OVERFLOW = '22008'
+    INVALID_TIME_ZONE_DISPLACEMENT_VALUE = '22009'
+    ESCAPE_CHARACTER_CONFLICT = '2200B'
+    INVALID_USE_OF_ESCAPE_CHARACTER = '2200C'
+    INVALID_ESCAPE_OCTET = '2200D'
+    ZERO_LENGTH_CHARACTER_STRING = '2200F'
+    MOST_SPECIFIC_TYPE_MISMATCH = '2200G'
+    SEQUENCE_GENERATOR_LIMIT_EXCEEDED = '2200H'
+    NOT_AN_XML_DOCUMENT = '2200L'
+    INVALID_XML_DOCUMENT = '2200M'
+    INVALID_XML_CONTENT = '2200N'
+    INVALID_XML_COMMENT = '2200S'
+    INVALID_XML_PROCESSING_INSTRUCTION = '2200T'
+    INVALID_INDICATOR_PARAMETER_VALUE = '22010'
+    SUBSTRING_ERROR = '22011'
+    DIVISION_BY_ZERO = '22012'
+    INVALID_PRECEDING_OR_FOLLOWING_SIZE = '22013'
+    INVALID_ARGUMENT_FOR_NTILE_FUNCTION = '22014'
+    INTERVAL_FIELD_OVERFLOW = '22015'
+    INVALID_ARGUMENT_FOR_NTH_VALUE_FUNCTION = '22016'
+    INVALID_CHARACTER_VALUE_FOR_CAST = '22018'
+    INVALID_ESCAPE_CHARACTER = '22019'
+    INVALID_REGULAR_EXPRESSION = '2201B'
+    INVALID_ARGUMENT_FOR_LOGARITHM = '2201E'
+    INVALID_ARGUMENT_FOR_POWER_FUNCTION = '2201F'
+    INVALID_ARGUMENT_FOR_WIDTH_BUCKET_FUNCTION = '2201G'
+    INVALID_ROW_COUNT_IN_LIMIT_CLAUSE = '2201W'
+    INVALID_ROW_COUNT_IN_RESULT_OFFSET_CLAUSE = '2201X'
+    CHARACTER_NOT_IN_REPERTOIRE = '22021'
+    INDICATOR_OVERFLOW = '22022'
+    INVALID_PARAMETER_VALUE = '22023'
+    UNTERMINATED_C_STRING = '22024'
+    INVALID_ESCAPE_SEQUENCE = '22025'
+    STRING_DATA_LENGTH_MISMATCH = '22026'
+    TRIM_ERROR = '22027'
+    ARRAY_SUBSCRIPT_ERROR = '2202E'
+    INVALID_TABLESAMPLE_REPEAT = '2202G'
+    INVALID_TABLESAMPLE_ARGUMENT = '2202H'
+    DUPLICATE_JSON_OBJECT_KEY_VALUE = '22030'
+    INVALID_ARGUMENT_FOR_SQL_JSON_DATETIME_FUNCTION = '22031'
+    INVALID_JSON_TEXT = '22032'
+    INVALID_SQL_JSON_SUBSCRIPT = '22033'
+    MORE_THAN_ONE_SQL_JSON_ITEM = '22034'
+    NO_SQL_JSON_ITEM = '22035'
+    NON_NUMERIC_SQL_JSON_ITEM = '22036'
+    NON_UNIQUE_KEYS_IN_A_JSON_OBJECT = '22037'
+    SINGLETON_SQL_JSON_ITEM_REQUIRED = '22038'
+    SQL_JSON_ARRAY_NOT_FOUND = '22039'
+    SQL_JSON_MEMBER_NOT_FOUND = '2203A'
+    SQL_JSON_NUMBER_NOT_FOUND = '2203B'
+    SQL_JSON_OBJECT_NOT_FOUND = '2203C'
+    TOO_MANY_JSON_ARRAY_ELEMENTS = '2203D'
+    TOO_MANY_JSON_OBJECT_MEMBERS = '2203E'
+    SQL_JSON_SCALAR_REQUIRED = '2203F'
+    SQL_JSON_ITEM_CANNOT_BE_CAST_TO_TARGET_TYPE = '2203G'
+    FLOATING_POINT_EXCEPTION = '22P01'
+    INVALID_TEXT_REPRESENTATION = '22P02'
+    INVALID_BINARY_REPRESENTATION = '22P03'
+    BAD_COPY_FILE_FORMAT = '22P04'
+    UNTRANSLATABLE_CHARACTER = '22P05'
+    NONSTANDARD_USE_OF_ESCAPE_CHARACTER = '22P06'
+
+    # Class 23 - Integrity Constraint Violation
+    INTEGRITY_CONSTRAINT_VIOLATION = '23000'
+    RESTRICT_VIOLATION = '23001'
+    NOT_NULL_VIOLATION = '23502'
+    FOREIGN_KEY_VIOLATION = '23503'
+    UNIQUE_VIOLATION = '23505'
+    CHECK_VIOLATION = '23514'
+    EXCLUSION_VIOLATION = '23P01'
+
+    # Class 24 - Invalid Cursor State
+    INVALID_CURSOR_STATE = '24000'
+
+    # Class 25 - Invalid Transaction State
+    INVALID_TRANSACTION_STATE = '25000'
+    ACTIVE_SQL_TRANSACTION = '25001'
+    BRANCH_TRANSACTION_ALREADY_ACTIVE = '25002'
+    INAPPROPRIATE_ACCESS_MODE_FOR_BRANCH_TRANSACTION = '25003'
+    INAPPROPRIATE_ISOLATION_LEVEL_FOR_BRANCH_TRANSACTION = '25004'
+    NO_ACTIVE_SQL_TRANSACTION_FOR_BRANCH_TRANSACTION = '25005'
+    READ_ONLY_SQL_TRANSACTION = '25006'
+    SCHEMA_AND_DATA_STATEMENT_MIXING_NOT_SUPPORTED = '25007'
+    HELD_CURSOR_REQUIRES_SAME_ISOLATION_LEVEL = '25008'
+    NO_ACTIVE_SQL_TRANSACTION = '25P01'
+    IN_FAILED_SQL_TRANSACTION = '25P02'
+    IDLE_IN_TRANSACTION_SESSION_TIMEOUT = '25P03'
+    TRANSACTION_TIMEOUT = '25P04'
+
+    # Class 26 - Invalid SQL Statement Name
+    INVALID_SQL_STATEMENT_NAME = '26000'
+
+    # Class 27 - Triggered Data Change Violation
+    TRIGGERED_DATA_CHANGE_VIOLATION = '27000'
+
+    # Class 28 - Invalid Authorization Specification
+    INVALID_AUTHORIZATION_SPECIFICATION = '28000'
+    INVALID_PASSWORD = '28P01'
+
+    # Class 2B - Dependent Privilege Descriptors Still Exist
+    DEPENDENT_PRIVILEGE_DESCRIPTORS_STILL_EXIST = '2B000'
+    DEPENDENT_OBJECTS_STILL_EXIST = '2BP01'
+
+    # Class 2D - Invalid Transaction Termination
+    INVALID_TRANSACTION_TERMINATION = '2D000'
+
+    # Class 2F - SQL Routine Exception
+    SQL_ROUTINE_EXCEPTION = '2F000'
+    MODIFYING_SQL_DATA_NOT_PERMITTED_2F = '2F002'
+    PROHIBITED_SQL_STATEMENT_ATTEMPTED_2F = '2F003'
+    READING_SQL_DATA_NOT_PERMITTED_2F = '2F004'
+    FUNCTION_EXECUTED_NO_RETURN_STATEMENT = '2F005'
+
+    # Class 34 - Invalid Cursor Name
+    INVALID_CURSOR_NAME = '34000'
+
+    # Class 38 - External Routine Exception
+    EXTERNAL_ROUTINE_EXCEPTION = '38000'
+    CONTAINING_SQL_NOT_PERMITTED = '38001'
+    MODIFYING_SQL_DATA_NOT_PERMITTED_38 = '38002'
+    PROHIBITED_SQL_STATEMENT_ATTEMPTED_38 = '38003'
+    READING_SQL_DATA_NOT_PERMITTED_38 = '38004'
+
+    # Class 39 - External Routine Invocation Exception
+    EXTERNAL_ROUTINE_INVOCATION_EXCEPTION = '39000'
+    INVALID_SQLSTATE_RETURNED = '39001'
+    NULL_VALUE_NOT_ALLOWED_39 = '39004'
+    TRIGGER_PROTOCOL_VIOLATED = '39P01'
+    SRF_PROTOCOL_VIOLATED = '39P02'
+    EVENT_TRIGGER_PROTOCOL_VIOLATED = '39P03'
+
+    # Class 3B - Savepoint Exception
+    SAVEPOINT_EXCEPTION = '3B000'
+    INVALID_SAVEPOINT_SPECIFICATION = '3B001'
+
+    # Class 3D - Invalid Catalog Name
+    INVALID_CATALOG_NAME = '3D000'
+
+    # Class 3F - Invalid Schema Name
+    INVALID_SCHEMA_NAME = '3F000'
+
+    # Class 40 - Transaction Rollback
+    TRANSACTION_ROLLBACK = '40000'
+    SERIALIZATION_FAILURE = '40001'
+    TRANSACTION_INTEGRITY_CONSTRAINT_VIOLATION = '40002'
+    STATEMENT_COMPLETION_UNKNOWN = '40003'
+    DEADLOCK_DETECTED = '40P01'
+
+    # Class 42 - Syntax Error or Access Rule Violation
+    SYNTAX_ERROR_OR_ACCESS_RULE_VIOLATION = '42000'
+    INSUFFICIENT_PRIVILEGE = '42501'
+    SYNTAX_ERROR = '42601'
+    INVALID_NAME = '42602'
+    INVALID_COLUMN_DEFINITION = '42611'
+    NAME_TOO_LONG = '42622'
+    DUPLICATE_COLUMN = '42701'
+    AMBIGUOUS_COLUMN = '42702'
+    UNDEFINED_COLUMN = '42703'
+    UNDEFINED_OBJECT = '42704'
+    DUPLICATE_OBJECT = '42710'
+    DUPLICATE_ALIAS = '42712'
+    DUPLICATE_FUNCTION = '42723'
+    AMBIGUOUS_FUNCTION = '42725'
+    GROUPING_ERROR = '42803'
+    DATATYPE_MISMATCH = '42804'
+    WRONG_OBJECT_TYPE = '42809'
+    INVALID_FOREIGN_KEY = '42830'
+    CANNOT_COERCE = '42846'
+    UNDEFINED_FUNCTION = '42883'
+    GENERATED_ALWAYS = '428C9'
+    RESERVED_NAME = '42939'
+    UNDEFINED_TABLE = '42P01'
+    UNDEFINED_PARAMETER = '42P02'
+    DUPLICATE_CURSOR = '42P03'
+    DUPLICATE_DATABASE = '42P04'
+    DUPLICATE_PREPARED_STATEMENT = '42P05'
+    DUPLICATE_SCHEMA = '42P06'
+    DUPLICATE_TABLE = '42P07'
+    AMBIGUOUS_PARAMETER = '42P08'
+    AMBIGUOUS_ALIAS = '42P09'
+    INVALID_COLUMN_REFERENCE = '42P10'
+    INVALID_CURSOR_DEFINITION = '42P11'
+    INVALID_DATABASE_DEFINITION = '42P12'
+    INVALID_FUNCTION_DEFINITION = '42P13'
+    INVALID_PREPARED_STATEMENT_DEFINITION = '42P14'
+    INVALID_SCHEMA_DEFINITION = '42P15'
+    INVALID_TABLE_DEFINITION = '42P16'
+    INVALID_OBJECT_DEFINITION = '42P17'
+    INDETERMINATE_DATATYPE = '42P18'
+    INVALID_RECURSION = '42P19'
+    WINDOWING_ERROR = '42P20'
+    COLLATION_MISMATCH = '42P21'
+    INDETERMINATE_COLLATION = '42P22'
+
+    # Class 44 - WITH CHECK OPTION Violation
+    WITH_CHECK_OPTION_VIOLATION = '44000'
+
+    # Class 53 - Insufficient Resources
+    INSUFFICIENT_RESOURCES = '53000'
+    DISK_FULL = '53100'
+    OUT_OF_MEMORY = '53200'
+    TOO_MANY_CONNECTIONS = '53300'
+    CONFIGURATION_LIMIT_EXCEEDED = '53400'
+
+    # Class 54 - Program Limit Exceeded
+    PROGRAM_LIMIT_EXCEEDED = '54000'
+    STATEMENT_TOO_COMPLEX = '54001'
+    TOO_MANY_COLUMNS = '54011'
+    TOO_MANY_ARGUMENTS = '54023'
+
+    # Class 55 - Object Not In Prerequisite State
+    OBJECT_NOT_IN_PREREQUISITE_STATE = '55000'
+    OBJECT_IN_USE = '55006'
+    CANT_CHANGE_RUNTIME_PARAM = '55P02'
+    LOCK_NOT_AVAILABLE = '55P03'
+    UNSAFE_NEW_ENUM_VALUE_USAGE = '55P04'
+
+    # Class 57 - Operator Intervention
+    OPERATOR_INTERVENTION = '57000'
+    QUERY_CANCELED = '57014'
+    ADMIN_SHUTDOWN = '57P01'
+    CRASH_SHUTDOWN = '57P02'
+    CANNOT_CONNECT_NOW = '57P03'
+    DATABASE_DROPPED = '57P04'
+    IDLE_SESSION_TIMEOUT = '57P05'
+
+    # Class 58 - System Error (errors external to PostgreSQL itself)
+    SYSTEM_ERROR = '58000'
+    IO_ERROR = '58030'
+    UNDEFINED_FILE = '58P01'
+    DUPLICATE_FILE = '58P02'
+    FILE_NAME_TOO_LONG = '58P03'
+
+    # Class 72 - Snapshot Failure
+    SNAPSHOT_TOO_OLD = '72000'
+
+    # Class F0 - Configuration File Error
+    CONFIG_FILE_ERROR = 'F0000'
+    LOCK_FILE_EXISTS = 'F0001'
+
+    # Class HV - Foreign Data Wrapper Error (SQL/MED)
+    FDW_ERROR = 'HV000'
+    FDW_OUT_OF_MEMORY = 'HV001'
+    FDW_DYNAMIC_PARAMETER_VALUE_NEEDED = 'HV002'
+    FDW_INVALID_DATA_TYPE = 'HV004'
+    FDW_COLUMN_NAME_NOT_FOUND = 'HV005'
+    FDW_INVALID_DATA_TYPE_DESCRIPTORS = 'HV006'
+    FDW_INVALID_COLUMN_NAME = 'HV007'
+    FDW_INVALID_COLUMN_NUMBER = 'HV008'
+    FDW_INVALID_USE_OF_NULL_POINTER = 'HV009'
+    FDW_INVALID_STRING_FORMAT = 'HV00A'
+    FDW_INVALID_HANDLE = 'HV00B'
+    FDW_INVALID_OPTION_INDEX = 'HV00C'
+    FDW_INVALID_OPTION_NAME = 'HV00D'
+    FDW_OPTION_NAME_NOT_FOUND = 'HV00J'
+    FDW_REPLY_HANDLE = 'HV00K'
+    FDW_UNABLE_TO_CREATE_EXECUTION = 'HV00L'
+    FDW_UNABLE_TO_CREATE_REPLY = 'HV00M'
+    FDW_UNABLE_TO_ESTABLISH_CONNECTION = 'HV00N'
+    FDW_NO_SCHEMAS = 'HV00P'
+    FDW_SCHEMA_NOT_FOUND = 'HV00Q'
+    FDW_TABLE_NOT_FOUND = 'HV00R'
+    FDW_FUNCTION_SEQUENCE_ERROR = 'HV010'
+    FDW_TOO_MANY_HANDLES = 'HV014'
+    FDW_INCONSISTENT_DESCRIPTOR_INFORMATION = 'HV021'
+    FDW_INVALID_ATTRIBUTE_VALUE = 'HV024'
+    FDW_INVALID_STRING_LENGTH_OR_BUFFER_LENGTH = 'HV090'
+    FDW_INVALID_DESCRIPTOR_FIELD_IDENTIFIER = 'HV091'
+
+    # Class P0 - PL/pgSQL Error
+    PLPGSQL_ERROR = 'P0000'
+    RAISE_EXCEPTION = 'P0001'
+    NO_DATA_FOUND = 'P0002'
+    TOO_MANY_ROWS = 'P0003'
+    ASSERT_FAILURE = 'P0004'
+
+    # Class XX - Internal Error
+    INTERNAL_ERROR = 'XX000'
+    DATA_CORRUPTED = 'XX001'
+    INDEX_CORRUPTED = 'XX002'

xbot/plugins/pgsql/errors.py

@@ -0,0 +1,44 @@
+"""
+Public exceptions.
+"""
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from xbot.plugins.pgsql.codes import PGCodes
+    from xbot.plugins.pgsql.pgsql import PGSQLCommandResult
+
+
+class PGSQLConnectError(Exception):
+    """
+    Raised when a PostgreSQL connection cannot be established.
+
+    The original Psycopg exception is preserved via ``__cause__``.
+    """
+
+
+class PGSQLCommandError(Exception):
+    """
+    Raised when a SQL command result differs from the expectation.
+
+    Exposes ``.result`` (``PGSQLCommandResult``) and ``.expect``
+    (``PGCodes | None``). When the error originates from a caught
+    ``psycopg.Error``, the original exception is preserved via
+    ``__cause__``.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        result: 'PGSQLCommandResult',
+        expect: 'PGCodes | None',
+    ) -> None:
+        """
+        :param message: error message.
+        :param result: command result.
+        :param expect: expected SQLSTATE code.
+        """
+        super().__init__(message)
+        self.result = result
+        self.expect = expect

xbot/plugins/pgsql/pgsql.py

@@ -0,0 +1,213 @@
+"""
+Synchronous PostgreSQL connection and command result.
+"""
+
+import textwrap
+
+from collections.abc import Iterable, Generator
+from contextlib import contextmanager
+from typing import Any
+
+import psycopg
+from psycopg import Connection
+from psycopg.rows import tuple_row
+from xbot.framework.logger import ExtraAdapter, getlogger
+
+from cli_helpers import tabular_output
+
+from xbot.plugins.pgsql.codes import PGCodes
+from xbot.plugins.pgsql.errors import PGSQLCommandError, PGSQLConnectError
+
+
+logger = getlogger(__name__)
+
+
+class PGSQLCommandResult(list[tuple[Any, ...]]):
+    """
+    Rows and metadata produced by one SQL command.
+
+    A ``list[tuple[Any, ...]]`` subclass. Each element is a row tuple;
+    the object also carries ``header`` (column names), ``rc`` (SQLSTATE,
+    ``"00000"`` on success) and ``cmd`` (the SQL command for logging).
+    Calling ``str(result)`` renders rows as a psql-style table that
+    updates live as rows are appended.
+    """
+
+    def __init__(
+        self,
+        rows: Iterable[tuple[Any, ...]] = (),
+        *,
+        header: tuple[str, ...] = (),
+        rc: str | None = '00000',
+        cmd: str = ''
+    ) -> None:
+        """
+        :param rows: row tuples.
+        :param header: column names.
+        :param rc: SQLSTATE code.
+        :param cmd: SQL command.
+        """
+        super().__init__(rows)
+        self.header = header
+        self.rc = rc
+        self.cmd = cmd
+
+    def __str__(self) -> str:
+        """
+        Render the current rows as a psql-style table.
+        """
+        lines = tabular_output.format_output(
+            self,
+            self.header,
+            format_name='psql',
+        )
+        return '\n'.join(lines)
+
+
+class PGSQLConnection(object):
+    """
+    One synchronous PostgreSQL connection.
+    """
+
+    def __init__(self) -> None:
+        self._conn: Connection[tuple[Any, ...]] | None = None
+        self._logger = ExtraAdapter(logger, {})
+
+    def connect(
+        self,
+        host: str,
+        user: str,
+        password: str,
+        database: str,
+        port: int = 5432,
+        timeout: int = 5
+    ) -> None:
+        """
+        Open an autocommit PostgreSQL connection.
+
+        :param host: hostname or ip.
+        :param user: user name.
+        :param password: user password.
+        :param database: database name.
+        :param port: PostgreSQL port.
+       :param timeout: connect timeout(s).
+       """
+        if self._conn is not None and not self._conn.closed:
+            return
+        prefix = f'postgres://{user}@{host}:{port}/{database}'
+        self._logger.extra['prefix'] = prefix
+        self._logger.info('Connecting...')
+        try:
+            self._conn = psycopg.connect(
+                host=host,
+                user=user,
+                password=password,
+                dbname=database,
+                port=port,
+                connect_timeout=timeout,
+                autocommit=True,
+                row_factory=tuple_row,
+            )
+        except psycopg.Error as e:
+            raise PGSQLConnectError(f'Could not connect to {prefix}: {str(e)}') from e
+
+    def disconnect(self) -> None:
+        """
+        Close the connection; repeated calls are harmless.
+        """
+        if self._conn is not None and not self._conn.closed:
+            self._conn.close()
+        self._conn = None
+
+    @contextmanager
+    def transaction(self) -> Generator[None, None, None]:
+        """
+        Commit on success and roll back on exception.
+        Nested calls use savepoints automatically.
+
+        >>> db = PGSQLConnection()                                      # doctest: +SKIP
+        >>> db.connect('127.0.0.1', 'postgres', 'secret', 'postgres')
+        >>> with db.transaction():
+        ...     db.exec("INSERT INTO t VALUES (1)")  # commit on exit
+        >>> with db.transaction():
+        ...     db.exec("INSERT INTO t VALUES (2)")
+        ...     raise RuntimeError('rollback')  # row 2 is rolled back
+        """
+        with self._conn.transaction():
+            yield
+
+    def exec(
+        self,
+        cmd: str,
+        expect: PGCodes | None = PGCodes.SUCCESSFUL_COMPLETION
+    ) -> PGSQLCommandResult:
+        """
+        Execute one SQL command and check its SQLSTATE.
+
+        ``PGCodes`` is a ``str``-based enum with 263 PostgreSQL 14-18
+        SQLSTATE codes. Pass ``expect=None`` to accept any outcome
+        without raising.
+
+        :param cmd: SQL command.
+        :param expect: expected SQLSTATE code.
+            PGCodes.SUCCESSFUL_COMPLETION: expect SQLSTATE is '00000' (default).
+            PGCodes.UNDEFINED_TABLE: expect SQLSTATE is '42P01'.
+            None: do not check the result.
+
+        :return: command result (rows, header, rc, cmd).
+
+        :raises:
+            `.PGSQLCommandError` -- if the result is not as expected.
+
+        >>> db = PGSQLConnection()                                      # doctest: +SKIP
+        >>> db.connect('127.0.0.1', 'postgres', 'secret', 'postgres')
+        >>> db.exec('SELECT 1')  # successful
+        >>> db.exec('SELECT * FROM missing')  # PGSQLCommandError
+        >>> db.exec('SELECT * FROM missing', expect=PGCodes.UNDEFINED_TABLE)  # no error
+        >>> db.exec('SELECT * FROM missing', expect=None)  # no error
+        >>> db.exec('SELECT 1', expect=PGCodes.UNDEFINED_TABLE)  # PGSQLCommandError
+        """
+        extra: dict[str, Any] = {'hook': {}}
+        self._logger.info(f"Command: '{cmd}', Expect: '{expect}'", extra=extra)
+        cause: psycopg.Error | None = None
+        try:
+            with self._conn.cursor() as cursor:
+                cursor.execute(cmd, prepare=True)
+                if cursor.description is None:
+                    rows: list[tuple[Any, ...]] = []
+                    header: tuple[str, ...] = ()
+                else:
+                    rows = cursor.fetchall()
+                    header = tuple(
+                        column.name for column in cursor.description
+                    )
+            result = PGSQLCommandResult(
+                rows,
+                header=header,
+                rc=PGCodes.SUCCESSFUL_COMPLETION.value,
+                cmd=cmd,
+            )
+        except psycopg.Error as e:
+            cause = e
+            result = PGSQLCommandResult(
+                [],
+                header=(),
+                rc=getattr(e, 'sqlstate', None),
+                cmd=cmd,
+            )
+        extra['hook']['more'] = result
+        if expect != None and result.rc != expect.value:
+            msg = textwrap.dedent(f"""\
+            Expections not met:
+            Command: {cmd}
+            Excpect: {expect}
+            ReturnCode: {result.rc}
+            Output:
+                {result}
+            """)
+            raise PGSQLCommandError(
+                msg,
+                result=result,
+                expect=expect,
+            ) from cause
+        return result

xbot/plugins/pgsql/version.py

@@ -0,0 +1,5 @@
+"""
+Package version.
+"""
+
+__version__: str = '0.1.0'

xbot_plugins_pgsql-0.1.0.dist-info/METADATA

@@ -0,0 +1,134 @@
+Metadata-Version: 2.4
+Name: xbot.plugins.pgsql
+Version: 0.1.0
+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: license-file
+
+<p align="center">
+  <br>English | <a href="README.zh.md">中文</a>
+</p>
+
+---
+
+# 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()
+```
+
+<p align="center">
+  <br>中文 | <a href="README.md">English</a>
+</p>
+
+---
+
+# 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()
+```

xbot_plugins_pgsql-0.1.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+tests/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+tests/run.py,sha256=S7-Nt-cvKStKydBaJptLARRAE7Vs2ng6N-ubsGarhXs,1083
+tests/test_pgsql.py,sha256=3k6r5qb0cNQIjsH8ev1CpVVJ3LFdcw7W65g3d-HL6UA,8947
+xbot/plugins/pgsql/__init__.py,sha256=nSbwueWFzdbcmcENLAsnQiSqEbQ1yzvIG_jxJCrC27g,439
+xbot/plugins/pgsql/codes.py,sha256=5OEIs0YNHbZYGm9jIWczMVuQvu3TTQCn_GD04IAypyg,12400
+xbot/plugins/pgsql/errors.py,sha256=9SRtFCc5ee9r2OMS8SFd8ml8H1LcSlvO8O2WqjLh3WU,1103
+xbot/plugins/pgsql/pgsql.py,sha256=D31ULKlzwHLb2vdGenhPNnmItxpXeIok0ZLeNsQjCig,6877
+xbot/plugins/pgsql/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+xbot/plugins/pgsql/version.py,sha256=yUaeFX3keaqxK7DotElYbBSr-vs68q_f61nlL3WZisw,53
+xbot_plugins_pgsql-0.1.0.dist-info/licenses/LICENSE,sha256=QQgf5JlcyKhtVWQcDwDfv7aU_8RZ5qZKxLnpp3NEXos,1325
+xbot_plugins_pgsql-0.1.0.dist-info/METADATA,sha256=yOpUjIHYUG4J9DrwJ24w_C3ioX3bjj9kFWa5clI4KvQ,3235
+xbot_plugins_pgsql-0.1.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+xbot_plugins_pgsql-0.1.0.dist-info/top_level.txt,sha256=4uDSWEEQ4RLxZEPAyhoF4SDnil_CTMm2yOv0bRpEBNU,11
+xbot_plugins_pgsql-0.1.0.dist-info/RECORD,,

xbot_plugins_pgsql-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

xbot_plugins_pgsql-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,24 @@
+BSD 2-Clause License
+
+Copyright (c) 2022-2023, zhaowcheng <zhaowcheng@163.com>
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

xbot_plugins_pgsql-0.1.0.dist-info/top_level.txt

@@ -0,0 +1,2 @@
+tests
+xbot