C API reference

Use this page to look up an exact type, constant, structure, or function after reading the C SDK overview. For a first program, follow the static C quickstart.

Looking for	Section
Handle ownership and release functions	Opaque handles
Return codes and capabilities	Constants
Structure initialization	Common macros
Options and record layouts	Public structures
Exact function signatures	Functions

This reference is generated from the frozen ABI contract, public headers, and documentation summaries. Signatures come from Doxygen's parse of the shipped headers. The documentation build rejects a missing, stale, or duplicate public function.

The loaded ABI is version 1.3 and embeds PostgreSQL 19. Borrowed views and handle ownership follow the contracts below.

Opaque handles

Handle	Parent	Constructors	Destructor
pgm_instance	Library	pgm_instance_open, pgm_instance_open_with_mode	pgm_instance_close
pgm_connection	pgm_instance	pgm_connection_open	pgm_connection_close
pgm_statement	pgm_connection	pgm_statement_prepare	pgm_statement_close
pgm_request	pgm_connection	pgm_execute_async, pgm_execute_async_ex, pgm_execute_script_async, pgm_statement_execute_async	pgm_request_free
pgm_result	pgm_request	pgm_execute, pgm_request_wait, pgm_request_next_result	pgm_result_free
pgm_copy	pgm_request	pgm_result_take_copy	pgm_copy_close
pgm_event	pgm_instance	pgm_instance_next_event	pgm_event_free
pgm_operation	pgm_instance	pgm_instance_checkpoint_async, pgm_instance_logical_dump_async, pgm_instance_logical_restore_async, pgm_instance_maintenance_async	pgm_operation_free
pgm_error	Library	internal:error-output	pgm_error_free

Constants

Open Mode

Name	Value
PGM_OPEN_EXISTING	0
PGM_OPEN_OR_CREATE	1
PGM_CREATE_NEW	2

Abi

Name	Value
PGM_ABI_VERSION	65540
PGM_ABI_VERSION_MAJOR	1
PGM_ABI_VERSION_MINOR	4

Status

Name	Value
PGM_STATUS_OK	0
PGM_STATUS_INVALID_ARGUMENT	1
PGM_STATUS_BUSY	2
PGM_STATUS_TIMEOUT	3
PGM_STATUS_CANCELED	4
PGM_STATUS_IO_ERROR	5
PGM_STATUS_POSTGRES_ERROR	6
PGM_STATUS_CONNECTION_FAILED	7
PGM_STATUS_INSTANCE_FAILED	8
PGM_STATUS_FORKED_PROCESS	9
PGM_STATUS_VERSION_MISMATCH	10
PGM_STATUS_UNSUPPORTED	11
PGM_STATUS_OUT_OF_MEMORY	12
PGM_STATUS_INTERNAL_ERROR	13
PGM_STATUS_REENTRANT_CALL	14

Format

Name	Value
PGM_FORMAT_TEXT	0
PGM_FORMAT_BINARY	1

Shutdown

Name	Value
PGM_SHUTDOWN_SMART	0
PGM_SHUTDOWN_FAST	1
PGM_SHUTDOWN_IMMEDIATE	2

Request

Name	Value
PGM_REQUEST_PENDING	0
PGM_REQUEST_RUNNING	1
PGM_REQUEST_COMPLETED	2
PGM_REQUEST_CANCELED	3
PGM_REQUEST_FAILED	4

Availability

Name	Value
PGM_AVAILABILITY_READY	0
PGM_AVAILABILITY_AGAIN	1
PGM_AVAILABILITY_END	2

Io

Name	Value
PGM_IO_PROGRESS	0
PGM_IO_AGAIN	1
PGM_IO_END	2

Result

Name	Value
PGM_RESULT_COMMAND_OK	0
PGM_RESULT_TUPLES_OK	1
PGM_RESULT_COPY_IN	2
PGM_RESULT_COPY_OUT	3
PGM_RESULT_EMPTY_QUERY	4
PGM_RESULT_TUPLES_CHUNK	5
PGM_RESULT_ERROR	6

Transaction

Name	Value
PGM_TRANSACTION_IDLE	0
PGM_TRANSACTION_ACTIVE	1
PGM_TRANSACTION_INTRANS	2
PGM_TRANSACTION_INERROR	3
PGM_TRANSACTION_UNKNOWN	4

Pin

Name	Value
PGM_PIN_TRANSACTION	1
PGM_PIN_ADVISORY_LOCK	2
PGM_PIN_PORTAL	4
PGM_PIN_COPY	8
PGM_PIN_OTHER	16

Values in this group may be combined as a bit mask.

Delivery

Name	Value
PGM_DELIVERY_MATERIALIZED	0
PGM_DELIVERY_CHUNKED	1

Event

Name	Value
PGM_EVENT_LOG	0
PGM_EVENT_NOTICE	1
PGM_EVENT_NOTIFICATION	2
PGM_EVENT_OVERFLOW	3

Diagnostic

Name	Value
PGM_DIAG_SQLSTATE	1
PGM_DIAG_SEVERITY	2
PGM_DIAG_MESSAGE	3
PGM_DIAG_DETAIL	4
PGM_DIAG_HINT	5
PGM_DIAG_POSITION	6
PGM_DIAG_INTERNAL_POSITION	7
PGM_DIAG_INTERNAL_QUERY	8
PGM_DIAG_CONTEXT	9
PGM_DIAG_SCHEMA	10
PGM_DIAG_TABLE	11
PGM_DIAG_COLUMN	12
PGM_DIAG_DATATYPE	13
PGM_DIAG_CONSTRAINT	14
PGM_DIAG_SOURCE_FILE	15
PGM_DIAG_SOURCE_LINE	16
PGM_DIAG_SOURCE_FUNCTION	17

Operation

Name	Value
PGM_OPERATION_PENDING	0
PGM_OPERATION_RUNNING	1
PGM_OPERATION_COMPLETED	2
PGM_OPERATION_CANCELED	3
PGM_OPERATION_FAILED	4

Operation Kind

Name	Value
PGM_OPERATION_CHECKPOINT	0
PGM_OPERATION_LOGICAL_DUMP	1
PGM_OPERATION_LOGICAL_RESTORE	2
PGM_OPERATION_MAINTENANCE	3

Operation Phase

Name	Value
PGM_OPERATION_PHASE_PENDING	0
PGM_OPERATION_PHASE_STARTING	1
PGM_OPERATION_PHASE_DATABASE	2
PGM_OPERATION_PHASE_ARCHIVE_IO	3
PGM_OPERATION_PHASE_HOST_IO	4
PGM_OPERATION_PHASE_FINALIZING	5
PGM_OPERATION_PHASE_TERMINAL	6

Maintenance Kind

Name	Value
PGM_MAINTENANCE_VACUUM	0
PGM_MAINTENANCE_ANALYZE	1
PGM_MAINTENANCE_VACUUM_ANALYZE	2
PGM_MAINTENANCE_REINDEX_DATABASE	3

Logical Flag

Name	Value
PGM_LOGICAL_SCHEMA_ONLY	1
PGM_LOGICAL_DATA_ONLY	2
PGM_LOGICAL_CLEAN	4
PGM_LOGICAL_CREATE	8
PGM_LOGICAL_NO_OWNER	16
PGM_LOGICAL_NO_PRIVILEGES	32

Values in this group may be combined as a bit mask.

Logical Flag Mask

Name	Value
PGM_LOGICAL_FLAGS_ALL	63

Capability

Name	Value
PGM_CAP_PREPARED_STATEMENTS	1
PGM_CAP_CHUNKED_RESULTS	2
PGM_CAP_COPY_IN	4
PGM_CAP_COPY_OUT	8
PGM_CAP_ARROW_C_DATA	16
PGM_CAP_NOTIFICATIONS	32
PGM_CAP_REQUEST_NOTICES	64
PGM_CAP_STATUS_TELEMETRY	128
PGM_CAP_INSTANCE_EVENTS	256
PGM_CAP_MANAGEMENT_OPERATIONS	512
PGM_CAP_MULTIPLE_INSTANCES	1024
PGM_CAP_NATIVE_EXTENSION_LOADING	2048
PGM_CAP_LOGICAL_BACKUP	4096
PGM_CAP_LOGICAL_RESTORE	8192
PGM_CAP_PHYSICAL_BACKUP	16384
PGM_CAP_MAINTENANCE	32768
PGM_CAP_BUNDLED_EXTENSIONS	65536

Values in this group may be combined as a bit mask.

Extension Capability

Name	Value
PGM_EXTENSION_CAP_THREAD_SAFE	1
PGM_EXTENSION_CAP_MULTI_INSTANCE_SAFE	2
PGM_EXTENSION_CAP_SESSION_MOBILITY_SAFE	4
PGM_EXTENSION_CAP_PARALLEL_WORKER_SAFE	8
PGM_EXTENSION_CAP_INSTANCE_SHMEM	16
PGM_EXTENSION_CAP_BACKGROUND_WORKER	32
PGM_EXTENSION_CAP_FILESYSTEM_READ	64
PGM_EXTENSION_CAP_FILESYSTEM_WRITE	128
PGM_EXTENSION_CAP_HOST_LIBRARY_DEPENDENCY	256
PGM_EXTENSION_CAP_PROCESS_GLOBAL_STATE	512

Values in this group may be combined as a bit mask.

Common macros

Macro	Contract
PGM_ABI_VERSION_ENCODE(major, minor)	Encode an ABI major and minor in the same form as PGM_ABI_VERSION.
PGM_NO_TIMEOUT	Select no deadline for a C API timeout measured in milliseconds.
PGM_API	Portable public-symbol declaration annotation; host code must not redefine it.

Public typedefs

pgm_availability

typedef int32_t pgm_availability;

pgm_bundled_extension_info

typedef struct pgm_bundled_extension_info pgm_bundled_extension_info;

pgm_checkpoint_options

typedef struct pgm_checkpoint_options pgm_checkpoint_options;

pgm_column

typedef struct pgm_column pgm_column;

pgm_connection_id

typedef uint64_t pgm_connection_id;

pgm_connection_options

typedef struct pgm_connection_options pgm_connection_options;

pgm_connection_status_snapshot

typedef struct pgm_connection_status_snapshot pgm_connection_status_snapshot;

pgm_delivery_mode

typedef int32_t pgm_delivery_mode;

pgm_diagnostic_field

typedef int32_t pgm_diagnostic_field;

pgm_event_kind

typedef int32_t pgm_event_kind;

pgm_event_overflow_record

typedef struct pgm_event_overflow_record pgm_event_overflow_record;

pgm_execute_options

typedef struct pgm_execute_options pgm_execute_options;

pgm_instance_options

typedef struct pgm_instance_options pgm_instance_options;

pgm_instance_telemetry

typedef struct pgm_instance_telemetry pgm_instance_telemetry;

pgm_io_state

typedef int32_t pgm_io_state;

pgm_log_callback

typedef void(* pgm_log_callback) (void *user_data, const pgm_log_record *record);

pgm_log_record

typedef struct pgm_log_record pgm_log_record;

pgm_logical_dump_options

typedef struct pgm_logical_dump_options pgm_logical_dump_options;

pgm_logical_restore_options

typedef struct pgm_logical_restore_options pgm_logical_restore_options;

pgm_maintenance_kind

typedef int32_t pgm_maintenance_kind;

pgm_maintenance_options

typedef struct pgm_maintenance_options pgm_maintenance_options;

pgm_notice

typedef struct pgm_notice pgm_notice;

pgm_notice_callback

typedef void(* pgm_notice_callback) (void *user_data, const pgm_notice *notice);

pgm_notification

typedef struct pgm_notification pgm_notification;

pgm_notification_callback

typedef void(* pgm_notification_callback) (void *user_data, const pgm_notification *notification);

pgm_open_mode

typedef int32_t pgm_open_mode;

pgm_operation_kind

typedef int32_t pgm_operation_kind;

pgm_operation_phase

typedef int32_t pgm_operation_phase;

pgm_operation_progress_snapshot

typedef struct pgm_operation_progress_snapshot pgm_operation_progress_snapshot;

pgm_operation_state

typedef int32_t pgm_operation_state;

pgm_parameter

typedef struct pgm_parameter pgm_parameter;

pgm_prepare_options

typedef struct pgm_prepare_options pgm_prepare_options;

pgm_request_id

typedef uint64_t pgm_request_id;

pgm_request_state

typedef int32_t pgm_request_state;

pgm_result_status

typedef int32_t pgm_result_status;

pgm_script_options

typedef struct pgm_script_options pgm_script_options;

pgm_setting

typedef struct pgm_setting pgm_setting;

pgm_shutdown_mode

typedef int32_t pgm_shutdown_mode;

pgm_statement_description

typedef struct pgm_statement_description pgm_statement_description;

pgm_status

typedef int32_t pgm_status;

pgm_stream_read_callback

typedef pgm_io_state(* pgm_stream_read_callback) (void *user_data, void *buffer, size_t capacity, size_t *produced);

pgm_stream_write_callback

typedef pgm_io_state(* pgm_stream_write_callback) (void *user_data, const void *data, size_t size, size_t *consumed);

pgm_transaction_status

typedef int32_t pgm_transaction_status;

pgm_value_view

typedef struct pgm_value_view pgm_value_view;

Public structures

Every extensible public structure must be initialized with its matching PGM_*_INIT macro before use.

pgm_bundled_extension_info

Initializer: PGM_BUNDLED_EXTENSION_INFO_INIT

Field	Type
struct_size	uint32_t
postgresql_major	uint32_t
sdk_abi_version	uint32_t
reserved	uint32_t
capabilities	uint64_t
id	const char *
sql_name	const char *
version	const char *

pgm_checkpoint_options

Initializer: PGM_CHECKPOINT_OPTIONS_INIT

Field	Type
struct_size	uint32_t
flags	uint32_t

pgm_column

Initializer: PGM_COLUMN_INIT

Field	Type
struct_size	uint32_t
name	const char *
table_oid	uint32_t
table_column	int32_t
type_oid	uint32_t
type_size	int32_t
type_modifier	int32_t
format	uint16_t
reserved	uint16_t

pgm_connection_options

Initializer: PGM_CONNECTION_OPTIONS_INIT

Field	Type
struct_size	uint32_t
reserved	uint32_t
user	const char *
database	const char *
application_name	const char *
settings	const pgm_setting *
setting_count	size_t
notice_callback	pgm_notice_callback
notification_callback	pgm_notification_callback
user_data	void *

pgm_connection_status_snapshot

Initializer: PGM_CONNECTION_STATUS_SNAPSHOT_INIT

Field	Type
struct_size	uint32_t
transaction_status	pgm_transaction_status
pin_reasons	uint32_t
carrier_retained	uint32_t
virtual_backend_pid	int32_t
connection_id	pgm_connection_id
active_request_id	pgm_request_id

pgm_event_overflow_record

Initializer: PGM_EVENT_OVERFLOW_RECORD_INIT

Field	Type
struct_size	uint32_t
dropped_kind	pgm_event_kind
dropped_count	uint64_t

pgm_execute_options

Initializer: PGM_EXECUTE_OPTIONS_INIT

Field	Type
struct_size	uint32_t
flags	uint32_t
parameters	const pgm_parameter *
parameter_count	size_t
result_format	uint16_t
reserved16	uint16_t
delivery_mode	pgm_delivery_mode
target_chunk_rows	uint32_t
result_buffer_limit	size_t
notice_callback	pgm_notice_callback
notice_user_data	void *

pgm_instance_options

Initializer: PGM_INSTANCE_OPTIONS_INIT

Field	Type
struct_size	uint32_t
create	uint32_t
path	const char *
executable_path	const char *
resource_root	const char *
settings	const pgm_setting *
setting_count	size_t
control_queue_capacity	size_t
transport_queue_capacity	size_t
executor_worker_count	uint32_t
execution_queue_capacity	uint32_t
logical_umask	uint32_t
reserved	uint32_t
user_data	void *
result_buffer_limit	size_t
maximum_value_size	size_t
event_queue_capacity	size_t
log_callback	pgm_log_callback
log_user_data	void *

pgm_instance_telemetry

Initializer: PGM_INSTANCE_TELEMETRY_INIT

Field	Type
struct_size	uint32_t
executor_worker_count	uint32_t
connection_count	uint64_t
active_request_count	uint64_t
running_session_count	uint64_t
pinned_session_count	uint64_t
runnable_session_count	uint64_t
queued_request_count	uint64_t
parallel_tokens_in_use	uint64_t
event_queue_depth	uint64_t
event_queue_capacity	uint64_t
request_count	uint64_t
completed_request_count	uint64_t
canceled_request_count	uint64_t
failed_request_count	uint64_t
execution_token_rejections	uint64_t
queue_wait_ns_max	uint64_t
dropped_log_count	uint64_t
dropped_notice_count	uint64_t
dropped_notification_count	uint64_t

pgm_log_record

Initializer: PGM_LOG_RECORD_INIT

Field	Type
struct_size	uint32_t
virtual_backend_pid	int32_t
connection_id	pgm_connection_id
request_id	pgm_request_id
severity	const char *
sqlstate	const char *
message	const char *
detail	const char *

pgm_logical_dump_options

Initializer: PGM_LOGICAL_DUMP_OPTIONS_INIT

Field	Type
struct_size	uint32_t
flags	uint32_t
database	const char *
user	const char *
channel_capacity	size_t
progress_quantum	size_t
write	pgm_stream_write_callback
user_data	void *

pgm_logical_restore_options

Initializer: PGM_LOGICAL_RESTORE_OPTIONS_INIT

Field	Type
struct_size	uint32_t
flags	uint32_t
database	const char *
user	const char *
channel_capacity	size_t
progress_quantum	size_t
read	pgm_stream_read_callback
user_data	void *

pgm_maintenance_options

Initializer: PGM_MAINTENANCE_OPTIONS_INIT

Field	Type
struct_size	uint32_t
flags	uint32_t
kind	pgm_maintenance_kind
reserved	uint32_t
database	const char *
user	const char *

pgm_notice

Initializer: PGM_NOTICE_INIT

Field	Type
struct_size	uint32_t
sqlstate	const char *
severity	const char *
message	const char *
detail	const char *
hint	const char *
connection_id	pgm_connection_id
request_id	pgm_request_id

pgm_notification

Initializer: PGM_NOTIFICATION_INIT

Field	Type
struct_size	uint32_t
virtual_backend_pid	int32_t
channel	const char *
payload	const char *
connection_id	pgm_connection_id

pgm_operation_progress_snapshot

Initializer: PGM_OPERATION_PROGRESS_SNAPSHOT_INIT

Field	Type
struct_size	uint32_t
kind	pgm_operation_kind
state	pgm_operation_state
phase	pgm_operation_phase
bytes_received	uint64_t
bytes_produced	uint64_t
total_bytes	uint64_t
objects_completed	uint64_t
objects_total	uint64_t

pgm_parameter

Initializer: PGM_PARAMETER_INIT

Field	Type
struct_size	uint32_t
type_oid	uint32_t
format	uint16_t
is_null	uint16_t
data	const void *
size	size_t

pgm_prepare_options

Initializer: PGM_PREPARE_OPTIONS_INIT

Field	Type
struct_size	uint32_t
flags	uint32_t
parameter_type_oids	const uint32_t *
parameter_count	size_t

pgm_script_options

Initializer: PGM_SCRIPT_OPTIONS_INIT

Field	Type
struct_size	uint32_t
flags	uint32_t
delivery_mode	pgm_delivery_mode
target_chunk_rows	uint32_t
result_buffer_limit	size_t
notice_callback	pgm_notice_callback
notice_user_data	void *

pgm_setting

Field	Type
name	const char *
value	const char *

pgm_statement_description

Initializer: PGM_STATEMENT_DESCRIPTION_INIT

Field	Type
struct_size	uint32_t
reserved	uint32_t
parameter_count	size_t
column_count	size_t

pgm_value_view

Initializer: PGM_VALUE_VIEW_INIT

Field	Type
struct_size	uint32_t
type_oid	uint32_t
format	uint16_t
is_null	uint16_t
data	const void *
size	size_t

Functions

Library metadata

pgm_abi_version

uint32_t pgm_abi_version(void);

Return the encoded major and minor version of the loaded host ABI.

Introduced in session-execution. Contract profile: metadata.

Property	Contract
Ownership	returns a borrowed static value or an integer value
Blocking	never blocks
Thread Safety	safe from any host thread
Callback Context	does not dispatch callbacks
Errors	has no error output

pgm_build_id

const char * pgm_build_id(void);

Return the immutable build identity of the loaded PostGamma kernel.

Introduced in session-execution. Contract profile: metadata.

Property	Contract
Ownership	returns a borrowed static value or an integer value
Blocking	never blocks
Thread Safety	safe from any host thread
Callback Context	does not dispatch callbacks
Errors	has no error output

pgm_capabilities

uint64_t pgm_capabilities(void);

Return the capability-bit mask advertised by the loaded kernel.

Introduced in c-api-foundation. Contract profile: metadata.

Property	Contract
Ownership	returns a borrowed static value or an integer value
Blocking	never blocks
Thread Safety	safe from any host thread
Callback Context	does not dispatch callbacks
Errors	has no error output

pgm_postgresql_version

const char * pgm_postgresql_version(void);

Return the PostgreSQL major version embedded in the loaded kernel.

Introduced in session-execution. Contract profile: metadata.

Property	Contract
Ownership	returns a borrowed static value or an integer value
Blocking	never blocks
Thread Safety	safe from any host thread
Callback Context	does not dispatch callbacks
Errors	has no error output

pgm_status_name

const char * pgm_status_name(pgm_status status);

Return a borrowed stable name for a PostGamma status value.

Introduced in session-execution. Contract profile: metadata.

Property	Contract
Ownership	returns a borrowed static value or an integer value
Blocking	never blocks
Thread Safety	safe from any host thread
Callback Context	does not dispatch callbacks
Errors	has no error output

pgm_bundled_extension_count

size_t pgm_bundled_extension_count(void);

Return the number of reviewed native extensions compiled into this kernel.

Introduced in embedded-release. Contract profile: metadata.

Property	Contract
Ownership	returns a borrowed static value or an integer value
Blocking	never blocks
Thread Safety	safe from any host thread
Callback Context	does not dispatch callbacks
Errors	has no error output

pgm_bundled_extension_get

pgm_status pgm_bundled_extension_get(size_t index, pgm_bundled_extension_info *info);

Copy borrowed metadata for one bundled extension into an initialized output structure.

Introduced in embedded-release. Contract profile: metadata.

Property	Contract
Ownership	returns a borrowed static value or an integer value
Blocking	never blocks
Thread Safety	safe from any host thread
Callback Context	does not dispatch callbacks
Errors	has no error output

Pgm Instance

pgm_instance_open_with_mode

pgm_status pgm_instance_open_with_mode(const pgm_instance_options *options, pgm_open_mode mode, pgm_instance **instance, pgm_error **error);

Open an existing cluster, open or create one, or atomically create a new cluster with an explicit policy; never replace an existing path in CREATE_NEW mode.

Introduced in embedded-release. Contract profile: open.

Property	Contract
Ownership	returns one caller-owned handle on success and no handle on failure
Blocking	may block within the documented startup deadline
Thread Safety	the output handle is unpublished until success
Callback Context	does not dispatch user callbacks before publication
Errors	clears error first and returns one owned diagnostic when allocation permits

pgm_instance_open

pgm_status pgm_instance_open(const pgm_instance_options *options, pgm_instance **instance, pgm_error **error);

Create or open a cluster and return one caller-owned in-process database instance.

Introduced in cluster-lifecycle. Contract profile: open.

Property	Contract
Ownership	returns one caller-owned handle on success and no handle on failure
Blocking	may block within the documented startup deadline
Thread Safety	the output handle is unpublished until success
Callback Context	does not dispatch user callbacks before publication
Errors	clears error first and returns one owned diagnostic when allocation permits

pgm_instance_close

pgm_status pgm_instance_close(pgm_instance *instance, pgm_shutdown_mode mode, int64_t timeout_ms, pgm_error **error);

Shut down an instance within the supplied deadline and consume it only on success.

Introduced in cluster-lifecycle. Contract profile: close.

Property	Contract
Ownership	consumes the handle only on PGM_STATUS_OK and permits retry otherwise
Blocking	may block only within the supplied deadline
Thread Safety	requires external serialization except for documented cancel or inspection
Callback Context	callbacks caused by progress run on the calling host thread
Errors	returns BUSY while public children exist and an owned diagnostic on failure

pgm_instance_get_telemetry

pgm_status pgm_instance_get_telemetry(pgm_instance *instance, pgm_instance_telemetry *telemetry, pgm_error **error);

Copy a synchronized executor, request, event, and resource snapshot for an instance.

Introduced in runtime-events. Contract profile: inspect.

Property	Contract
Ownership	returns a borrowed view or copies a value into caller storage
Blocking	never performs SQL progress and takes only bounded internal locks
Thread Safety	read-only inspection is allowed from the documented secondary thread
Callback Context	does not dispatch callbacks
Errors	invalid handles or output storage return a deterministic status

pgm_instance_waitable

pgm_status pgm_instance_waitable(pgm_instance *instance, int *file_descriptor, pgm_error **error);

Return the stable level-triggered descriptor for the instance event queue.

Introduced in runtime-events. Contract profile: event.

Property	Contract
Ownership	returns or inspects one caller-owned routed event
Blocking	next-event honors its deadline; accessors never block
Thread Safety	one event consumer model per instance
Callback Context	dispatch invokes callbacks only on the calling host thread
Errors	queue overflow is an observable event and monotonic telemetry, never silent loss

pgm_instance_next_event

pgm_status pgm_instance_next_event(pgm_instance *instance, int64_t timeout_ms, pgm_event **event, pgm_availability *availability, pgm_error **error);

Dequeue one owned instance event, respecting the supplied timeout.

Introduced in runtime-events. Contract profile: event.

Property	Contract
Ownership	returns or inspects one caller-owned routed event
Blocking	next-event honors its deadline; accessors never block
Thread Safety	one event consumer model per instance
Callback Context	dispatch invokes callbacks only on the calling host thread
Errors	queue overflow is an observable event and monotonic telemetry, never silent loss

pgm_instance_dispatch

pgm_status pgm_instance_dispatch(pgm_instance *instance, size_t maximum_events, size_t *dispatched_events, pgm_error **error);

Drain queued events and invoke configured callbacks on the calling host thread.

Introduced in runtime-events. Contract profile: event.

Property	Contract
Ownership	returns or inspects one caller-owned routed event
Blocking	next-event honors its deadline; accessors never block
Thread Safety	one event consumer model per instance
Callback Context	dispatch invokes callbacks only on the calling host thread
Errors	queue overflow is an observable event and monotonic telemetry, never silent loss

pgm_instance_checkpoint_async

pgm_status pgm_instance_checkpoint_async(pgm_instance *instance, const pgm_checkpoint_options *options, pgm_operation **operation, pgm_error **error);

Create a caller-driven in-process checkpoint operation.

Introduced in arrow-management. Contract profile: management.

Property	Contract
Ownership	returns or progresses one instance-owned operation handle
Blocking	progress is caller-driven and waitable access never runs a subprocess
Thread Safety	one progress owner and one documented cancellation thread
Callback Context	callbacks run only on the progressing host thread
Errors	unsupported operations fail closed without subprocesses or network endpoints

pgm_instance_logical_dump_async

pgm_status pgm_instance_logical_dump_async(pgm_instance *instance, const pgm_logical_dump_options *options, pgm_operation **operation, pgm_error **error);

Create a caller-driven logical dump that writes a PostgreSQL custom archive through a host callback.

Introduced in logical-management. Contract profile: management_stream.

Property	Contract
Ownership	copies operation options and returns one caller-owned operation handle
Blocking	submission is bounded; progress transfers at most one quantum and reports backpressure
Thread Safety	one progress owner and one documented cancellation thread per operation
Callback Context	stream callbacks run only on the host thread calling progress
Errors	callback, archive, and PostgreSQL failures become owned operation diagnostics

pgm_instance_logical_restore_async

pgm_status pgm_instance_logical_restore_async(pgm_instance *instance, const pgm_logical_restore_options *options, pgm_operation **operation, pgm_error **error);

Create a caller-driven logical restore that reads a PostgreSQL custom archive through a host callback.

Introduced in logical-management. Contract profile: management_stream.

Property	Contract
Ownership	copies operation options and returns one caller-owned operation handle
Blocking	submission is bounded; progress transfers at most one quantum and reports backpressure
Thread Safety	one progress owner and one documented cancellation thread per operation
Callback Context	stream callbacks run only on the host thread calling progress
Errors	callback, archive, and PostgreSQL failures become owned operation diagnostics

pgm_instance_maintenance_async

pgm_status pgm_instance_maintenance_async(pgm_instance *instance, const pgm_maintenance_options *options, pgm_operation **operation, pgm_error **error);

Create a caller-driven VACUUM, ANALYZE, VACUUM ANALYZE, or database REINDEX operation.

Introduced in logical-management. Contract profile: management.

Property	Contract
Ownership	returns or progresses one instance-owned operation handle
Blocking	progress is caller-driven and waitable access never runs a subprocess
Thread Safety	one progress owner and one documented cancellation thread
Callback Context	callbacks run only on the progressing host thread
Errors	unsupported operations fail closed without subprocesses or network endpoints

Pgm Event

pgm_event_type

pgm_event_kind pgm_event_type(const pgm_event *event);

Return the kind of an owned event.

Introduced in runtime-events. Contract profile: accessor.

Property	Contract
Ownership	returns a borrowed view whose lifetime is bounded by its owner handle
Blocking	never blocks
Thread Safety	requires the owner not to be concurrently mutated or freed
Callback Context	does not dispatch callbacks
Errors	status-returning accessors reject invalid indexes and storage

pgm_event_connection

pgm_connection_id pgm_event_connection(const pgm_event *event);

Return the logical connection identity associated with an event, or zero when absent.

Introduced in runtime-events. Contract profile: accessor.

Property	Contract
Ownership	returns a borrowed view whose lifetime is bounded by its owner handle
Blocking	never blocks
Thread Safety	requires the owner not to be concurrently mutated or freed
Callback Context	does not dispatch callbacks
Errors	status-returning accessors reject invalid indexes and storage

pgm_event_request

pgm_request_id pgm_event_request(const pgm_event *event);

Return the request identity associated with an event, or zero when absent.

Introduced in runtime-events. Contract profile: accessor.

Property	Contract
Ownership	returns a borrowed view whose lifetime is bounded by its owner handle
Blocking	never blocks
Thread Safety	requires the owner not to be concurrently mutated or freed
Callback Context	does not dispatch callbacks
Errors	status-returning accessors reject invalid indexes and storage

pgm_event_log

pgm_status pgm_event_log(const pgm_event *event, pgm_log_record *record, pgm_error **error);

Copy borrowed log fields from a log event into an initialized view.

Introduced in runtime-events. Contract profile: accessor.

Property	Contract
Ownership	returns a borrowed view whose lifetime is bounded by its owner handle
Blocking	never blocks
Thread Safety	requires the owner not to be concurrently mutated or freed
Callback Context	does not dispatch callbacks
Errors	status-returning accessors reject invalid indexes and storage

pgm_event_notice

pgm_status pgm_event_notice(const pgm_event *event, pgm_notice *notice, pgm_error **error);

Copy borrowed PostgreSQL notice fields from a notice event into an initialized view.

Introduced in runtime-events. Contract profile: accessor.

Property	Contract
Ownership	returns a borrowed view whose lifetime is bounded by its owner handle
Blocking	never blocks
Thread Safety	requires the owner not to be concurrently mutated or freed
Callback Context	does not dispatch callbacks
Errors	status-returning accessors reject invalid indexes and storage

pgm_event_notification

pgm_status pgm_event_notification(const pgm_event *event, pgm_notification *notification, pgm_error **error);

Copy borrowed LISTEN/NOTIFY fields from a notification event into an initialized view.

Introduced in runtime-events. Contract profile: accessor.

Property	Contract
Ownership	returns a borrowed view whose lifetime is bounded by its owner handle
Blocking	never blocks
Thread Safety	requires the owner not to be concurrently mutated or freed
Callback Context	does not dispatch callbacks
Errors	status-returning accessors reject invalid indexes and storage

pgm_event_overflow

pgm_status pgm_event_overflow(const pgm_event *event, pgm_event_overflow_record *overflow, pgm_error **error);

Copy the dropped event kind and cumulative count from an overflow event.

Introduced in runtime-events. Contract profile: accessor.

Property	Contract
Ownership	returns a borrowed view whose lifetime is bounded by its owner handle
Blocking	never blocks
Thread Safety	requires the owner not to be concurrently mutated or freed
Callback Context	does not dispatch callbacks
Errors	status-returning accessors reject invalid indexes and storage

pgm_event_free

void pgm_event_free(pgm_event *event);

Release an event dequeued from an instance.

Introduced in runtime-events. Contract profile: free.

Property	Contract
Ownership	consumes the owned handle and accepts NULL or an invalidated no-op only where documented
Blocking	ordinary values do not block; request retirement is bounded
Thread Safety	must not race an operation on the same handle
Callback Context	request retirement may dispatch only on the calling host thread
Errors	void destructors cannot report failure and follow their fail-closed contract

Pgm Connection

pgm_connection_open

pgm_status pgm_connection_open(pgm_instance *instance, const pgm_connection_options *options, pgm_connection **connection, pgm_error **error);

Open one logical PostgreSQL session owned by an instance.

Introduced in cluster-lifecycle. Contract profile: open.

Property	Contract
Ownership	returns one caller-owned handle on success and no handle on failure
Blocking	may block within the documented startup deadline
Thread Safety	the output handle is unpublished until success
Callback Context	does not dispatch user callbacks before publication
Errors	clears error first and returns one owned diagnostic when allocation permits

pgm_connection_close

pgm_status pgm_connection_close(pgm_connection *connection, int64_t timeout_ms, pgm_error **error);

Close a logical session within the supplied deadline and consume it only on success.

Introduced in cluster-lifecycle. Contract profile: close.

Property	Contract
Ownership	consumes the handle only on PGM_STATUS_OK and permits retry otherwise
Blocking	may block only within the supplied deadline
Thread Safety	requires external serialization except for documented cancel or inspection
Callback Context	callbacks caused by progress run on the calling host thread
Errors	returns BUSY while public children exist and an owned diagnostic on failure

pgm_connection_transaction_status

pgm_status pgm_connection_transaction_status(pgm_connection *connection, pgm_transaction_status *transaction_status, pgm_error **error);

Return the current PostgreSQL transaction state for a connection.

Introduced in ordered-results. Contract profile: inspect.

Property	Contract
Ownership	returns a borrowed view or copies a value into caller storage
Blocking	never performs SQL progress and takes only bounded internal locks
Thread Safety	read-only inspection is allowed from the documented secondary thread
Callback Context	does not dispatch callbacks
Errors	invalid handles or output storage return a deterministic status

pgm_connection_get_status

pgm_status pgm_connection_get_status(pgm_connection *connection, pgm_connection_status_snapshot *status, pgm_error **error);

Copy transaction, pinning, carrier, and active-request state for a connection.

Introduced in ordered-results. Contract profile: inspect.

Property	Contract
Ownership	returns a borrowed view or copies a value into caller storage
Blocking	never performs SQL progress and takes only bounded internal locks
Thread Safety	read-only inspection is allowed from the documented secondary thread
Callback Context	does not dispatch callbacks
Errors	invalid handles or output storage return a deterministic status

pgm_connection_identity

pgm_connection_id pgm_connection_identity(const pgm_connection *connection);

Return the stable PostGamma identity of a logical connection.

Introduced in ordered-results. Contract profile: inspect.

Property	Contract
Ownership	returns a borrowed view or copies a value into caller storage
Blocking	never performs SQL progress and takes only bounded internal locks
Thread Safety	read-only inspection is allowed from the documented secondary thread
Callback Context	does not dispatch callbacks
Errors	invalid handles or output storage return a deterministic status

pgm_connection_parameter_status

pgm_status pgm_connection_parameter_status(pgm_connection *connection, const char *name, const char **value, pgm_error **error);

Return a borrowed value for a PostgreSQL parameter-status name.

Introduced in runtime-events. Contract profile: inspect.

Property	Contract
Ownership	returns a borrowed view or copies a value into caller storage
Blocking	never performs SQL progress and takes only bounded internal locks
Thread Safety	read-only inspection is allowed from the documented secondary thread
Callback Context	does not dispatch callbacks
Errors	invalid handles or output storage return a deterministic status

pgm_execute

pgm_status pgm_execute(pgm_connection *connection, const char *sql, const pgm_parameter *parameters, size_t parameter_count, uint16_t result_format, int64_t timeout_ms, pgm_result **result, pgm_error **error);

Execute one extended-protocol statement synchronously and return one materialized result.

Introduced in session-execution. Contract profile: progress.

Property	Contract
Ownership	does not transfer ownership unless an explicit output says so
Blocking	poll and progress are nonblocking; wait honors its deadline
Thread Safety	one progress or wait thread per request
Callback Context	dispatches callbacks only on the calling host thread
Errors	normal AGAIN or END is reported through availability state, not pgm_status

pgm_execute_async

pgm_status pgm_execute_async(pgm_connection *connection, const char *sql, const pgm_parameter *parameters, size_t parameter_count, uint16_t result_format, pgm_request **request, pgm_error **error);

Submit one extended-protocol statement with the compact asynchronous options surface.

Introduced in session-execution. Contract profile: submit.

Property	Contract
Ownership	copies submission inputs and returns one caller-owned request on success
Blocking	does bounded submission work but does not wait for SQL completion
Thread Safety	one submitting thread per connection with one active request
Callback Context	does not invoke a user callback before returning
Errors	rejects invalid options before submission and returns an owned diagnostic

pgm_execute_async_ex

pgm_status pgm_execute_async_ex(pgm_connection *connection, const char *sql, size_t sql_size, const pgm_execute_options *options, pgm_request **request, pgm_error **error);

Submit one extended-protocol statement with typed parameters, delivery policy, and notice routing.

Introduced in ordered-results. Contract profile: submit.

Property	Contract
Ownership	copies submission inputs and returns one caller-owned request on success
Blocking	does bounded submission work but does not wait for SQL completion
Thread Safety	one submitting thread per connection with one active request
Callback Context	does not invoke a user callback before returning
Errors	rejects invalid options before submission and returns an owned diagnostic

pgm_execute_script_async

pgm_status pgm_execute_script_async(pgm_connection *connection, const char *sql, size_t sql_size, const pgm_script_options *options, pgm_request **request, pgm_error **error);

Submit simple-protocol SQL that may produce multiple ordered results.

Introduced in ordered-results. Contract profile: submit.

Property	Contract
Ownership	copies submission inputs and returns one caller-owned request on success
Blocking	does bounded submission work but does not wait for SQL completion
Thread Safety	one submitting thread per connection with one active request
Callback Context	does not invoke a user callback before returning
Errors	rejects invalid options before submission and returns an owned diagnostic

Pgm Statement

pgm_statement_prepare

pgm_status pgm_statement_prepare(pgm_connection *connection, const char *sql, size_t sql_size, const pgm_prepare_options *options, pgm_statement **statement, pgm_error **error);

Prepare an extended-protocol statement owned by one logical connection.

Introduced in ordered-results. Contract profile: open.

Property	Contract
Ownership	returns one caller-owned handle on success and no handle on failure
Blocking	may block within the documented startup deadline
Thread Safety	the output handle is unpublished until success
Callback Context	does not dispatch user callbacks before publication
Errors	clears error first and returns one owned diagnostic when allocation permits

pgm_statement_execute_async

pgm_status pgm_statement_execute_async(pgm_statement *statement, const pgm_execute_options *options, pgm_request **request, pgm_error **error);

Execute a prepared statement and return a caller-driven request.

Introduced in ordered-results. Contract profile: submit.

Property	Contract
Ownership	copies submission inputs and returns one caller-owned request on success
Blocking	does bounded submission work but does not wait for SQL completion
Thread Safety	one submitting thread per connection with one active request
Callback Context	does not invoke a user callback before returning
Errors	rejects invalid options before submission and returns an owned diagnostic

pgm_statement_describe

pgm_status pgm_statement_describe(const pgm_statement *statement, pgm_statement_description *description, pgm_error **error);

Copy the prepared statement's parameter and result-column counts.

Introduced in ordered-results. Contract profile: inspect.

Property	Contract
Ownership	returns a borrowed view or copies a value into caller storage
Blocking	never performs SQL progress and takes only bounded internal locks
Thread Safety	read-only inspection is allowed from the documented secondary thread
Callback Context	does not dispatch callbacks
Errors	invalid handles or output storage return a deterministic status

pgm_statement_parameter_type

pgm_status pgm_statement_parameter_type(const pgm_statement *statement, size_t parameter_index, uint32_t *type_oid, pgm_error **error);

Return one inferred or declared PostgreSQL parameter type OID.

Introduced in ordered-results. Contract profile: inspect.

Property	Contract
Ownership	returns a borrowed view or copies a value into caller storage
Blocking	never performs SQL progress and takes only bounded internal locks
Thread Safety	read-only inspection is allowed from the documented secondary thread
Callback Context	does not dispatch callbacks
Errors	invalid handles or output storage return a deterministic status

pgm_statement_column

pgm_status pgm_statement_column(const pgm_statement *statement, size_t column_index, pgm_column *column, pgm_error **error);

Copy metadata for one prepared statement result column.

Introduced in ordered-results. Contract profile: inspect.

Property	Contract
Ownership	returns a borrowed view or copies a value into caller storage
Blocking	never performs SQL progress and takes only bounded internal locks
Thread Safety	read-only inspection is allowed from the documented secondary thread
Callback Context	does not dispatch callbacks
Errors	invalid handles or output storage return a deterministic status

pgm_statement_close

pgm_status pgm_statement_close(pgm_statement *statement, pgm_error **error);

Release a prepared statement owned by a connection.

Introduced in ordered-results. Contract profile: close.

Property	Contract
Ownership	consumes the handle only on PGM_STATUS_OK and permits retry otherwise
Blocking	may block only within the supplied deadline
Thread Safety	requires external serialization except for documented cancel or inspection
Callback Context	callbacks caused by progress run on the calling host thread
Errors	returns BUSY while public children exist and an owned diagnostic on failure

Pgm Request

pgm_request_poll

pgm_status pgm_request_poll(pgm_request *request, pgm_request_state *state, pgm_error **error);

Inspect request state without driving protocol or PostgreSQL progress.

Introduced in session-execution. Contract profile: progress.

Property	Contract
Ownership	does not transfer ownership unless an explicit output says so
Blocking	poll and progress are nonblocking; wait honors its deadline
Thread Safety	one progress or wait thread per request
Callback Context	dispatches callbacks only on the calling host thread
Errors	normal AGAIN or END is reported through availability state, not pgm_status

pgm_request_progress

pgm_status pgm_request_progress(pgm_request *request, pgm_request_state *state, pgm_error **error);

Perform one nonblocking unit of caller-driven request progress.

Introduced in session-execution. Contract profile: progress.

Property	Contract
Ownership	does not transfer ownership unless an explicit output says so
Blocking	poll and progress are nonblocking; wait honors its deadline
Thread Safety	one progress or wait thread per request
Callback Context	dispatches callbacks only on the calling host thread
Errors	normal AGAIN or END is reported through availability state, not pgm_status

pgm_request_waitable

pgm_status pgm_request_waitable(pgm_request *request, int *file_descriptor, pgm_error **error);

Return the stable level-triggered descriptor for a request.

Introduced in session-execution. Contract profile: inspect.

Property	Contract
Ownership	returns a borrowed view or copies a value into caller storage
Blocking	never performs SQL progress and takes only bounded internal locks
Thread Safety	read-only inspection is allowed from the documented secondary thread
Callback Context	does not dispatch callbacks
Errors	invalid handles or output storage return a deterministic status

pgm_request_wait

pgm_status pgm_request_wait(pgm_request *request, int64_t timeout_ms, pgm_result **result, pgm_error **error);

Wait within a deadline for the next synchronous request result.

Introduced in session-execution. Contract profile: progress.

Property	Contract
Ownership	does not transfer ownership unless an explicit output says so
Blocking	poll and progress are nonblocking; wait honors its deadline
Thread Safety	one progress or wait thread per request
Callback Context	dispatches callbacks only on the calling host thread
Errors	normal AGAIN or END is reported through availability state, not pgm_status

pgm_request_cancel

pgm_status pgm_request_cancel(pgm_request *request, pgm_error **error);

Route cancellation to the owning PostgreSQL request without signaling the host process.

Introduced in session-execution. Contract profile: progress.

Property	Contract
Ownership	does not transfer ownership unless an explicit output says so
Blocking	poll and progress are nonblocking; wait honors its deadline
Thread Safety	one progress or wait thread per request
Callback Context	dispatches callbacks only on the calling host thread
Errors	normal AGAIN or END is reported through availability state, not pgm_status

pgm_request_next_result

pgm_status pgm_request_next_result(pgm_request *request, int64_t timeout_ms, pgm_result **result, pgm_availability *availability, pgm_error **error);

Return the next ordered result or an explicit AGAIN or END availability state.

Introduced in ordered-results. Contract profile: progress.

Property	Contract
Ownership	does not transfer ownership unless an explicit output says so
Blocking	poll and progress are nonblocking; wait honors its deadline
Thread Safety	one progress or wait thread per request
Callback Context	dispatches callbacks only on the calling host thread
Errors	normal AGAIN or END is reported through availability state, not pgm_status

pgm_request_identity

pgm_request_id pgm_request_identity(const pgm_request *request);

Return the stable PostGamma identity of a request.

Introduced in ordered-results. Contract profile: inspect.

Property	Contract
Ownership	returns a borrowed view or copies a value into caller storage
Blocking	never performs SQL progress and takes only bounded internal locks
Thread Safety	read-only inspection is allowed from the documented secondary thread
Callback Context	does not dispatch callbacks
Errors	invalid handles or output storage return a deterministic status

pgm_request_free

void pgm_request_free(pgm_request *request);

Retire and release a request, performing bounded cancellation when it is still active.

Introduced in session-execution. Contract profile: free.

Property	Contract
Ownership	consumes the owned handle and accepts NULL or an invalidated no-op only where documented
Blocking	ordinary values do not block; request retirement is bounded
Thread Safety	must not race an operation on the same handle
Callback Context	request retirement may dispatch only on the calling host thread
Errors	void destructors cannot report failure and follow their fail-closed contract

Pgm Result

pgm_result_kind

pgm_result_status pgm_result_kind(const pgm_result *result);

Return the PostgreSQL protocol result kind.

Introduced in session-execution. Contract profile: accessor.

Property	Contract
Ownership	returns a borrowed view whose lifetime is bounded by its owner handle
Blocking	never blocks
Thread Safety	requires the owner not to be concurrently mutated or freed
Callback Context	does not dispatch callbacks
Errors	status-returning accessors reject invalid indexes and storage

pgm_result_row_count

size_t pgm_result_row_count(const pgm_result *result);

Return the number of rows owned by this result or tuple chunk.

Introduced in session-execution. Contract profile: accessor.

Property	Contract
Ownership	returns a borrowed view whose lifetime is bounded by its owner handle
Blocking	never blocks
Thread Safety	requires the owner not to be concurrently mutated or freed
Callback Context	does not dispatch callbacks
Errors	status-returning accessors reject invalid indexes and storage

pgm_result_column_count

size_t pgm_result_column_count(const pgm_result *result);

Return the number of columns described by this result.

Introduced in session-execution. Contract profile: accessor.

Property	Contract
Ownership	returns a borrowed view whose lifetime is bounded by its owner handle
Blocking	never blocks
Thread Safety	requires the owner not to be concurrently mutated or freed
Callback Context	does not dispatch callbacks
Errors	status-returning accessors reject invalid indexes and storage

pgm_result_command_status

const char * pgm_result_command_status(const pgm_result *result);

Return the borrowed PostgreSQL command-status string for a result.

Introduced in session-execution. Contract profile: accessor.

Property	Contract
Ownership	returns a borrowed view whose lifetime is bounded by its owner handle
Blocking	never blocks
Thread Safety	requires the owner not to be concurrently mutated or freed
Callback Context	does not dispatch callbacks
Errors	status-returning accessors reject invalid indexes and storage

pgm_result_column

pgm_status pgm_result_column(const pgm_result *result, size_t column_index, pgm_column *column, pgm_error **error);

Copy metadata for one result column.

Introduced in session-execution. Contract profile: accessor.

Property	Contract
Ownership	returns a borrowed view whose lifetime is bounded by its owner handle
Blocking	never blocks
Thread Safety	requires the owner not to be concurrently mutated or freed
Callback Context	does not dispatch callbacks
Errors	status-returning accessors reject invalid indexes and storage

pgm_result_value

pgm_status pgm_result_value(const pgm_result *result, size_t row_index, size_t column_index, pgm_value_view *value, pgm_error **error);

Return a borrowed typed view of one result value.

Introduced in session-execution. Contract profile: accessor.

Property	Contract
Ownership	returns a borrowed view whose lifetime is bounded by its owner handle
Blocking	never blocks
Thread Safety	requires the owner not to be concurrently mutated or freed
Callback Context	does not dispatch callbacks
Errors	status-returning accessors reject invalid indexes and storage

pgm_result_export_arrow

pgm_status pgm_result_export_arrow(const pgm_result *result, struct ArrowSchema *schema, struct ArrowArray *array, pgm_error **error);

Convert a tuple result to one caller-owned Arrow C Data schema and array without consuming the result.

Introduced in arrow-management. Contract profile: accessor.

Property	Contract
Ownership	returns a borrowed view whose lifetime is bounded by its owner handle
Blocking	never blocks
Thread Safety	requires the owner not to be concurrently mutated or freed
Callback Context	does not dispatch callbacks
Errors	status-returning accessors reject invalid indexes and storage

pgm_result_free

void pgm_result_free(pgm_result *result);

Release a materialized result or tuple chunk.

Introduced in session-execution. Contract profile: free.

Property	Contract
Ownership	consumes the owned handle and accepts NULL or an invalidated no-op only where documented
Blocking	ordinary values do not block; request retirement is bounded
Thread Safety	must not race an operation on the same handle
Callback Context	request retirement may dispatch only on the calling host thread
Errors	void destructors cannot report failure and follow their fail-closed contract

Pgm Copy

pgm_result_take_copy

pgm_status pgm_result_take_copy(pgm_result **result, pgm_copy **copy, pgm_error **error);

Consume a COPY result and transfer its stream handle to the caller.

Introduced in copy-streaming. Contract profile: open.

Property	Contract
Ownership	returns one caller-owned handle on success and no handle on failure
Blocking	may block within the documented startup deadline
Thread Safety	the output handle is unpublished until success
Callback Context	does not dispatch user callbacks before publication
Errors	clears error first and returns one owned diagnostic when allocation permits

pgm_copy_write

pgm_status pgm_copy_write(pgm_copy *copy, const void *data, size_t size, size_t *consumed, pgm_io_state *state, pgm_error **error);

Offer bytes to a COPY IN stream and report partial consumption and backpressure.

Introduced in copy-streaming. Contract profile: copy_io.

Property	Contract
Ownership	retains the COPY handle and reports partial byte ownership through consumed or produced
Blocking	never waits for unbounded queue capacity and reports AGAIN through pgm_io_state
Thread Safety	one I/O owner thread; one other thread may cancel or inspect
Callback Context	duplex progress dispatches callbacks only on the calling host thread
Errors	a failure leaves the connection reusable or explicitly failed after bounded retirement

pgm_copy_finish

pgm_status pgm_copy_finish(pgm_copy *copy, const char *failure_message, size_t failure_message_size, pgm_io_state *state, pgm_error **error);

Finish COPY IN successfully or with a caller-supplied PostgreSQL failure message.

Introduced in copy-streaming. Contract profile: copy_io.

Property	Contract
Ownership	retains the COPY handle and reports partial byte ownership through consumed or produced
Blocking	never waits for unbounded queue capacity and reports AGAIN through pgm_io_state
Thread Safety	one I/O owner thread; one other thread may cancel or inspect
Callback Context	duplex progress dispatches callbacks only on the calling host thread
Errors	a failure leaves the connection reusable or explicitly failed after bounded retirement

pgm_copy_read

pgm_status pgm_copy_read(pgm_copy *copy, void *buffer, size_t capacity, size_t *produced, pgm_io_state *state, pgm_error **error);

Pull bytes from a COPY OUT stream and report partial output, backpressure, or end.

Introduced in copy-streaming. Contract profile: copy_io.

Property	Contract
Ownership	retains the COPY handle and reports partial byte ownership through consumed or produced
Blocking	never waits for unbounded queue capacity and reports AGAIN through pgm_io_state
Thread Safety	one I/O owner thread; one other thread may cancel or inspect
Callback Context	duplex progress dispatches callbacks only on the calling host thread
Errors	a failure leaves the connection reusable or explicitly failed after bounded retirement

pgm_copy_abort

pgm_status pgm_copy_abort(pgm_copy *copy, const char *message, size_t message_size, pgm_error **error);

Abort an active COPY stream with a caller-owned diagnostic message.

Introduced in copy-streaming. Contract profile: copy_io.

Property	Contract
Ownership	retains the COPY handle and reports partial byte ownership through consumed or produced
Blocking	never waits for unbounded queue capacity and reports AGAIN through pgm_io_state
Thread Safety	one I/O owner thread; one other thread may cancel or inspect
Callback Context	duplex progress dispatches callbacks only on the calling host thread
Errors	a failure leaves the connection reusable or explicitly failed after bounded retirement

pgm_copy_close

pgm_status pgm_copy_close(pgm_copy *copy, int64_t timeout_ms, pgm_error **error);

Retire and release a COPY handle within the supplied deadline.

Introduced in copy-streaming. Contract profile: close.

Property	Contract
Ownership	consumes the handle only on PGM_STATUS_OK and permits retry otherwise
Blocking	may block only within the supplied deadline
Thread Safety	requires external serialization except for documented cancel or inspection
Callback Context	callbacks caused by progress run on the calling host thread
Errors	returns BUSY while public children exist and an owned diagnostic on failure

Pgm Error

pgm_error_status

pgm_status pgm_error_status(const pgm_error *error);

Return the PostGamma status stored in an owned diagnostic.

Introduced in session-execution. Contract profile: accessor.

Property	Contract
Ownership	returns a borrowed view whose lifetime is bounded by its owner handle
Blocking	never blocks
Thread Safety	requires the owner not to be concurrently mutated or freed
Callback Context	does not dispatch callbacks
Errors	status-returning accessors reject invalid indexes and storage

pgm_error_sqlstate

const char * pgm_error_sqlstate(const pgm_error *error);

Return the borrowed five-character PostgreSQL SQLSTATE when available.

Introduced in session-execution. Contract profile: accessor.

Property	Contract
Ownership	returns a borrowed view whose lifetime is bounded by its owner handle
Blocking	never blocks
Thread Safety	requires the owner not to be concurrently mutated or freed
Callback Context	does not dispatch callbacks
Errors	status-returning accessors reject invalid indexes and storage

pgm_error_severity

const char * pgm_error_severity(const pgm_error *error);

Return the borrowed PostgreSQL severity text when available.

Introduced in session-execution. Contract profile: accessor.

Property	Contract
Ownership	returns a borrowed view whose lifetime is bounded by its owner handle
Blocking	never blocks
Thread Safety	requires the owner not to be concurrently mutated or freed
Callback Context	does not dispatch callbacks
Errors	status-returning accessors reject invalid indexes and storage

pgm_error_message

const char * pgm_error_message(const pgm_error *error);

Return the borrowed primary diagnostic message.

Introduced in session-execution. Contract profile: accessor.

Property	Contract
Ownership	returns a borrowed view whose lifetime is bounded by its owner handle
Blocking	never blocks
Thread Safety	requires the owner not to be concurrently mutated or freed
Callback Context	does not dispatch callbacks
Errors	status-returning accessors reject invalid indexes and storage

pgm_error_detail

const char * pgm_error_detail(const pgm_error *error);

Return the borrowed diagnostic detail when available.

Introduced in session-execution. Contract profile: accessor.

Property	Contract
Ownership	returns a borrowed view whose lifetime is bounded by its owner handle
Blocking	never blocks
Thread Safety	requires the owner not to be concurrently mutated or freed
Callback Context	does not dispatch callbacks
Errors	status-returning accessors reject invalid indexes and storage

pgm_error_field

const char * pgm_error_field(const pgm_error *error, pgm_diagnostic_field field);

Return one borrowed PostgreSQL diagnostic field selected by its stable field identifier.

Introduced in runtime-events. Contract profile: accessor.

Property	Contract
Ownership	returns a borrowed view whose lifetime is bounded by its owner handle
Blocking	never blocks
Thread Safety	requires the owner not to be concurrently mutated or freed
Callback Context	does not dispatch callbacks
Errors	status-returning accessors reject invalid indexes and storage

pgm_error_free

void pgm_error_free(pgm_error *error);

Release an owned diagnostic.

Introduced in session-execution. Contract profile: free.

Property	Contract
Ownership	consumes the owned handle and accepts NULL or an invalidated no-op only where documented
Blocking	ordinary values do not block; request retirement is bounded
Thread Safety	must not race an operation on the same handle
Callback Context	request retirement may dispatch only on the calling host thread
Errors	void destructors cannot report failure and follow their fail-closed contract

Pgm Operation

pgm_operation_progress

pgm_status pgm_operation_progress(pgm_operation *operation, pgm_operation_state *state, pgm_error **error);

Submit or advance an operation and return its synchronized state.

Introduced in arrow-management. Contract profile: management.

Property	Contract
Ownership	returns or progresses one instance-owned operation handle
Blocking	progress is caller-driven and waitable access never runs a subprocess
Thread Safety	one progress owner and one documented cancellation thread
Callback Context	callbacks run only on the progressing host thread
Errors	unsupported operations fail closed without subprocesses or network endpoints

pgm_operation_get_progress

pgm_status pgm_operation_get_progress(pgm_operation *operation, pgm_operation_progress_snapshot *progress, pgm_error **error);

Copy operation phase and byte or object counters without changing ownership.

Introduced in logical-management. Contract profile: inspect.

Property	Contract
Ownership	returns a borrowed view or copies a value into caller storage
Blocking	never performs SQL progress and takes only bounded internal locks
Thread Safety	read-only inspection is allowed from the documented secondary thread
Callback Context	does not dispatch callbacks
Errors	invalid handles or output storage return a deterministic status

pgm_operation_waitable

pgm_status pgm_operation_waitable(pgm_operation *operation, int *file_descriptor, pgm_error **error);

Return the stable level-triggered descriptor for an operation.

Introduced in arrow-management. Contract profile: management.

Property	Contract
Ownership	returns or progresses one instance-owned operation handle
Blocking	progress is caller-driven and waitable access never runs a subprocess
Thread Safety	one progress owner and one documented cancellation thread
Callback Context	callbacks run only on the progressing host thread
Errors	unsupported operations fail closed without subprocesses or network endpoints

pgm_operation_cancel

pgm_status pgm_operation_cancel(pgm_operation *operation, pgm_error **error);

Request cancellation for a cancelable operation.

Introduced in arrow-management. Contract profile: management.

Property	Contract
Ownership	returns or progresses one instance-owned operation handle
Blocking	progress is caller-driven and waitable access never runs a subprocess
Thread Safety	one progress owner and one documented cancellation thread
Callback Context	callbacks run only on the progressing host thread
Errors	unsupported operations fail closed without subprocesses or network endpoints

pgm_operation_free

void pgm_operation_free(pgm_operation *operation);

Retire and release an operation handle.

Introduced in arrow-management. Contract profile: free.

Property	Contract
Ownership	consumes the owned handle and accepts NULL or an invalidated no-op only where documented
Blocking	ordinary values do not block; request retirement is bounded
Thread Safety	must not race an operation on the same handle
Callback Context	request retirement may dispatch only on the calling host thread
Errors	void destructors cannot report failure and follow their fail-closed contract