PQregisterTypes(3)

📦 version 1.5.1, in debian bookworm, ubuntu jammy, ubuntu noble

💖 PQregisterTypes(3) — the libpqtypes one, bestie 💖

okay so we're in the libpqtypes Manual and this is PQregisterTypes, and it is literally the function that teaches libpqtypes about your types before anything else can use them. sit down, hydrate, let's go 🫶

✨ NAME ✨

PQregisterTypes — registers sub-classes, composites and user-defined types. no cap, that's the whole job description 💅

🌸 SYNOPSIS 🌸

#include <libpqtypes.h>
int PQregisterTypes(PGconn *conn, int which, PGregisterType *types,
                    int count, int async);

🦋 DESCRIPTION 🦋

So PQregisterTypes() is the vibe check for your types. It lets an app register one or more PQT_SUBCLASS, PQT_COMPOSITE or PQT_USERDEFINED types — and which flavour you're registering is decided by the which argument. that's it, that's the assignment ✨

When which is PQT_COMPOSITE or PQT_USERDEFINED, this function must execute a query against the backend to retrieve type information, which means... yeah, do not call this from inside a transaction. 😭

lowkey important: it is recommended to register multiple composites at the same time to avoid round trip overhead. batch it, girlie, the network is not your friend 🧚

The types argument is an array containing count types to register. here's the tea per flavour:

  • composites — do not use the typput or typget members of the PGregisterType structure, so those members are ignored. and if any composite does not exist, the register is aborted. 💀
  • user-defined types — must set either typput and/or typget for each type. non-negotiable, bestie.
  • sub-classes — the typname member of the PGregisterType structure must specify an inheritance relationship: ex. "myint=int4" where myint inherits from int4. the = is called the inheritance operator 👑

and the cute part: if both the typput and typget members of the PGregisterType structure are NULL, the type at that element will behave identically to the type it is inheriting from — that's an alias 🎀. otherwise, the base type's put and/or get routines get overridden.

The async argument indicates if the asynchronous type registration should be used. when it's non-zero, the caller must proceed in the normal async libpq fashion (PQconsumeInput, PQisBusy, PQgetResult) and provide a PGresult to PQregisterResult when obtained to complete the registration. main character async energy, fr fr 💅

NOTE: the typname member of the PGregisterType structure can optionally contain the type's schema: schema.typname. ✨
WARNING: PQparamCreate is only aware of types that have already been registered. if you need to put a type into a param, make sure it is first registered. otherwise you're gonna have a bad time 🙈

🌈 EXAMPLES 🌈

🍓 Using PQregisterTypes

this example registers two composite types. iconic.

PGregisterType comp_types[] = {
     {"myschema.simple", NULL, NULL},
     {"complex", NULL, NULL}
};

if (!PQregisterTypes(conn, PQT_COMPOSITE, comp_types, 2, 0))
     fprintf(stderr, "PQregisterTypes: %s\n", PQgeterror());

⭐ RETURN VALUE ⭐

On success, PQregisterTypes returns a non-zero value 🎉. On error, zero is returned and PQgeterror(3) will contain an error message. check it, always, bestie 😭

🎀 EXAMPLES 🎀

None.

yes it's a second EXAMPLES section and yes it says "None." — the manpage said it, not me, I don't make the rules 💅

👑 AUTHOR 👑

A contribution of eSilo, LLC. for the PostgreSQL Database Management System. Written by Andrew Chernow. king behaviour 🫶

🌸 REPORTING BUGS 🌸

Report bugs to <libpqtypes@esilo.com>. be nice, be specific, include the receipts 💖

Copyright (c) 2011 eSilo, LLC. All rights reserved.

This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

🦋 SEE ALSO 🦋

go read them, iykyk 🔥

okay bestie that's the whole page, and this was libpqtypes, dated 2011, and it's the PQregisterTypes(3) page — slay, register your types, stay out of transactions, periodt 💅✨🦋

📦 where this page comes from