Parameter · Client Connection Defaults / Locale and Formatting
client_encoding
Sets the client's character set encoding.
- Default:
SQL_ASCII - Type: string
- Applies: Session (any user)
In plain words
Text is stored in the database's encoding (server_encoding, usually UTF8). client_encoding tells the server which character set your application uses, so it can convert in both directions.
If they disagree with reality you get "invalid byte sequence" errors or garbled text (mojibake).
For DBAs and operators
The default is the database encoding, but libpq clients normally set it at connect time (psql uses PGCLIENTENCODING or the terminal locale; \encoding changes it). It is reported to the client on change.
Conversion happens in the backend for every value sent or received. Two failure modes:
- The client sends bytes that are not valid in the declared encoding: ERROR: invalid byte sequence for encoding "UTF8": 0xe9 0x20 0x... Typical cause: a Latin-1 file loaded with client_encoding UTF8.
- A stored character has no equivalent in the client encoding: ERROR: character with byte sequence 0xe0 0xa4 0xa8 in encoding "UTF8" has no equivalent in encoding "LATIN1"
A SQL_ASCII database performs no conversion and no validation at all: whatever bytes arrive are stored. Migrating such databases to UTF8 is a classic support project because invalid bytes surface only at dump/restore time.
For COPY you can set ENCODING per command instead of changing the session.
How to change it
Any user can change it for their session with SET.