CREATE_CONVERSION(7)

💖 CREATE_CONVERSION — okay bestie, let's build a whole encoding converter 💖

So this is page CREATE CONVERSION(7) from the PostgreSQL 18.6 Documentation, and yes we are doing encoding conversions today, get comfy. 🧚

---

✨ NAME ✨

CREATE_CONVERSION — bestie, it defines a brand new encoding conversion, like literally teaching your database how to translate between two character sets 💅

---

🌸 SYNOPSIS 🌸

CREATE [ DEFAULT ] CONVERSION name
    FOR source_encoding TO dest_encoding FROM function_name

That's the whole vibe. Short. Iconic. Does exactly one thing and ate. 👑

---

🦋 DESCRIPTION 🦋

Okay so CREATE CONVERSION defines a new conversion between two character set encodings. That's it, that's the whole job, and it's lowkey powerful.

Now, conversions marked DEFAULT? Those are the ones that can be used for automatic encoding conversion between client and server. But here's the catch bestie: to support that usage, you need two conversions defined — one going from encoding A to B, and one going from encoding B to A. Both. No skipping, it's a two-way street fr fr. 🫶

And to even be allowed to create a conversion in the first place, you need:

• EXECUTE privilege on the function
• CREATE privilege on the destination schema

That's the permission vibe check and you gotta pass it. ✨

---

💜 PARAMETERS 💜

• DEFAULT — this clause is you saying "yes, this one, this is THE default conversion for this particular source-to-destination encoding pair." Heads up though: there should be only one default encoding in a schema for the encoding pair. One. Singular. Don't be greedy. 🙈
• name — the name of the conversion. It can be schema-qualified, and if it isn't, the conversion gets defined in the current schema. Also the conversion name must be unique within a schema — no duplicates, we don't do that here. 💅
• source_encoding — the source encoding name. Where you're coming from. 💖
• dest_encoding — the destination encoding name. Where you're going. 🦋
• function_name — the function that actually does the converting. The function name can be schema-qualified, and if it isn't, the function will be looked up in the path.

The function must have this exact signature, no cap:

conv_proc(
    integer,  -- source encoding ID
    integer,  -- destination encoding ID
    cstring,  -- source string (null terminated C string)
    internal, -- destination (fill with a null terminated C string)
    integer,  -- source string length
    boolean   -- if true, don't throw an error if conversion fails
) RETURNS integer;

And the return value? That's the number of source bytes that were successfully converted. But listen — if that last argument is false, the function must throw an error on invalid input, and then the return value is always equal to the source string length. Always. Periodt. ⭐

---

🎀 NOTES 🎀

Okay important things, pay attention bestie, this part matters.

Neither the source nor the destination encoding can be SQL_ASCII, because the server's behavior for cases involving the SQL_ASCII "encoding" is hard-wired. So like, don't even try it. 💀

Use DROP CONVERSION to remove user-defined conversions. That's your undo button.

And the privileges required to create a conversion might be changed in a future release. So like, bookmark this page, iykyk. 👑

---

🌈 EXAMPLES 🌈

Wanna create a conversion from encoding UTF8 to LATIN1 using myfunc? Say less:

CREATE CONVERSION myconv FOR 'UTF8' TO 'LATIN1' FROM myfunc;

Look at her go. Main character energy fr fr. 🔥

---

⭐ COMPATIBILITY ⭐

CREATE CONVERSION is a PostgreSQL extension. There is no CREATE CONVERSION statement in the SQL standard — BUT, the standard does have a CREATE TRANSLATION statement that is very similar in purpose and syntax. So like, cousins basically. Not the same, but spiritually adjacent. 🌸

---

💅 SEE ALSO 💅

• ALTER CONVERSION (ALTER_CONVERSION(7))
• CREATE FUNCTION (CREATE_FUNCTION(7))
• DROP CONVERSION (DROP_CONVERSION(7))

Go read those too, they're all in the group chat. 🫶

---

Okay that's the whole page, you're officially educated on encoding conversions, I'm so proud of you. This was PostgreSQL 18.6, dated 2026, and this page is CREATE CONVERSION(7). Now go forth and convert some encodings responsibly bestie, mwah 💖✨🎀