PQparamCreate(3)

💖 NAME 💖

PQparamCreate, PQparamCount PQparamReset, PQparamClear — the PGparam management girlies. Bestie, this whole squad is here to handle your PGparam object situation.

(also lowkey PQparamDup is in this friend group, she just wasn't invited to the NAME line. rude, but okay. we'll get to her.)

---

✨ SYNOPSIS ✨

#include <libpqtypes.h>

PGparam *PQparamCreate(const PGconn *conn);
PGparam *PQparamDup(PGparam *param);
int PQparamCount(PGparam *param);
void PQparamReset(PGparam *param);
void PQparamClear(PGparam *param);

---

🫶 DESCRIPTION 🫶

Okay so. These functions manage the opaque PGparam object. Opaque means you don't get to peek inside her — she's mysterious, she's private, she's giving main character energy. You just use the functions and she handles the rest. 💅

• PQparamCreate() — allocates and initializes a brand new PGparam object. The second this call returns, she's ready for use, no warm-up needed, she's already dressed and out the door.

⚠️ WARNING bestie, listen to me: only types that have been registered via PQregisterXXX will be available to the param. Which means — the param is not updated with types registered after the param is created. She is frozen in time, she does not get new info later, periodt. So register your types FIRST, then create your param. Order matters, no cap.

• PQparamDup() — duplicates a given PGparam, and yes that includes any internal values that have already been put in there. Why is this iconic? Because you can queue up queries to execute at a later time — think connection pooler vibes. The problem: PQparamCreate requires a connection object, and a connection object might not be available when you're trying to enqueue a query with its PGparam object. 😭 Instead, a PGparam object can be used for the sole purpose of creating duplicates while there are no available PGconn objects. So she's like a template, a blueprint, a little queen sitting on the shelf making copies. Obsessed.
• PQparamCount() — gets the number of parameters in a PGparam object. Just the count. That's it. Simple, honest, reliable.
• PQparamReset() — clears out any previously put parameters, but will not free any memory. This is for the application that wants to "reuse" a PGparam object. Reuse era. ♻️
• PQparamClear() — releases all resources being used by a PGparam object. And then? The object should not be used after a clear. She's gone. Do not text her back. 🪦

🚨 It is very important to call PQparamReset() if you plan on reusing a PGparam object. Not "kinda important", not "if you feel like it" — VERY important. Do it. I'm not mad, I'm just disappointed. 💀

---

🎀 RETURN VALUE 🎀

• PQparamCreate() returns a pointer to a PGparam object on success, and NULL if something failed. If you got NULL, go check PQgeterror(3) for more information — she'll tell you what went wrong. 🙈
• PQparamCount() returns the number of parameters in a PGparam object.
• PQparamReset() and PQparamClear() have no return values. And if either function is provided a NULL PGparam pointer, it will silently fail. No drama, no error, no nothing. Just quiet. The way that silence is so loud honestly.

---

🌸 EXAMPLES 🌸

None.

Yeah. Bestie, I know. We're all a little disappointed. No examples, just vibes. You'll figure it out. ✨

---

👑 AUTHOR 👑

A contribution of eSilo, LLC. for the PostgreSQL Database Management System. Written by Andrew Chernow and Merlin Moncure. Kings. Absolute icons. 🫶

---

🦋 REPORTING BUGS 🦋

Report bugs to <libpqtypes@esilo.com>. Tell them everything, don't be shy. 💌

---

🌈 COPYRIGHT 🌈

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.

So like. She's free, she's generous, she's giving. But if she breaks? Not their problem. NO warranty. Zero. None. Read the source, bestie. 💅

---

💜 SEE ALSO 💜

• pqt-specs(3)
• PQputf(3)
• PQgeterror(3)
• PQparamExec(3)

---

That's the whole page, bestie! This one's from the libpqtypes manual, dated 2011. Go forth and manage your params responsibly. Mwah. 💖✨🎀