PQspecPrepare(3)

💖 PQspecPrepare(3) — the libpqtypes manual, bestie edition 💖

okay so real quick: this is a page from the libpqtypes Manual, and we're talking about PQspecPrepare(3) and its little cleanup bestie PQclearSpecs. it's giving ✨precompiled type specs✨ and honestly? iconic. let's get into it 🫶

---

✨ NAME ✨

PQspecPrepare — prepares a libpqtypes specifier format string. 💅

---

🌸 SYNOPSIS 🌸

#include <libpqtypes.h>

int PQspecPrepare(PGconn *conn, const char *name,
                      const char *format, int is_stmt);
void PQclearSpecs(PGconn *conn);

---

🦋 DESCRIPTION 🦋

so PQspecPrepare lets your app prepare specifier format strings that you're gonna use over and over and over again. and like… why would you? because preparing one means you skip the parsing and the type handler lookup costs entirely. no cap. and that becomes a HUGE win when you're managing big result sets or arrays, where a specifier format like "%int4 %text %bytea" would otherwise have to be prepared for every single tuple or element. 😭 the way that adds up…

and listen, same energy as PQregisterXXX: only specifier format strings prepared before a PGresult or PGparam gets created will actually be available for use. why? because the prepared type spec is cached inside a PGconn object and then copied into all the subsequent PGparam and PGresult objects. so like, timing is everything bestie. ⏰

every prepared type spec gets a name, and that name is its unique identifier. to actually use a prepared type spec, you drop that name anywhere a regular specifier format string is allowed — like in PQputf or PQgetf. the name has to be preceded by a @ AT sign. for the full syntax tea, go check the pqt-specs(3) man page. 💜

the format argument is the specifier format string you're preparing. and when format is NULL? the named prepared type spec gets removed from the PGconn's internal array. bye girl 👋

the is_stmt argument says whether a parameterized statement version of format should get cached alongside the prepared type spec. meaning every type specifier in format — like "%int4" — gets converted into "$1" syntax. when is_stmt is non-zero, a statement gets created and cached. for more on specifier format string → parameterized statements, peep the PQputf(3) man page.

NOTE: to use a prepared type spec with execution functions like PQexecf, is_stmt must be set to non-zero. no exceptions, bestie, it's literally the rule. 🔥

PQclearSpecs removes ALL the prepared specifiers from the given PGconn — as opposed to removing them one by one by setting PQspecPrepare's format argument to NULL. a really good use for this is after a PQresetXXX call, when you might wanna re-prepare all your type specifiers. spring cleaning energy 🧹✨

the functions that support the use of a prepared type spec are: PQputf, PQputvf, PQgetf, PQgetvf, PQexecf, PQexecvf, PQsendf, PQsendvf, PQparamExec, PQparamSendQuery. 💅

HINT: a good rule of thumb for using prepared type specs is when there are a large number of PQputf/PQgetf calls per statement execution. this commonly happens when you're dealing with large result sets and arrays. iykyk. 👑

---

🎀 RETURN VALUE 🎀

PQspecPrepare and PQclearSpecs return a nonzero value on success and zero if it fails. use PQgeterror() to get the error message. that's it, that's the tea. 🍓

---

🌈 EXAMPLES 🌈

this example prepares a type spec and issues some PQputf calls. slay.

       int i;
       PQparam *param;

       if(!PQspecPrepare(conn, "prepared_spec", "%int4 %text", 0))
       {
            fprintf(stderr, "PQspecPrepare: %s0, PQgeterror());
            exit(1);
       }

       /* create after preparing spec */
       param = PQparamCreate(conn);

       for(i=0; i < 100000; i++)
       {
            /* NOTE: nothing else can be in format string */
            PQputf(param, "@prepared_spec", 4, "text");
       }

       /* This elects to prepare a statement as well.  After this returns,
        * "SELECT myfunc($1, $2)" will be cached along with the prepared spec.
        */
       PQspecPrepare(conn, "myfunc", "SELECT myfunc(%int4, %text)", 1);

       /* "myfunc" tells execf to execute "SELECT myfunc($1, $2)".  If is_stmt
        * was set to zero during the PQspecPrepare, the below would be invalid
        * because execf doesn't know what to execute.
        */
       PQexecf(conn, "@myfunc", 123, "text");

       /* clear'm all */
       PQclearSpecs(conn);

---

💀 RATIONALE 💀

None.

(yeah that's literally it. nothing. the void. i respect the honesty honestly 💜)

---

👑 AUTHOR 👑

a contribution of eSilo, LLC. for the PostgreSQL Database Management System. written by Andrew Chernow. 🫶

---

🙈 REPORTING BUGS 🙈

report bugs to <libpqtypes@esilo.com>. don't be shy, they wanna hear it. 😌

---

⭐ 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… no promises bestie. 💀

---

🌸 SEE ALSO 🌸

pqt-specs(3), PQgetf(3), PQputf(3). go read 'em, they're cute. 💖

---

and that's the whole page!! mwah 💋 this was libpqtypes, version 2011, and we are so done here. stay prepared, stay spec'd, and clear your specs after a reset. periodt. 🎀✨