{"id":"ac723f17698550bc","repo":"jackc/pgx","slug":"simple-protocol-queries-must-be-run-with-client-en","errorCode":null,"errorMessage":"simple protocol queries must be run with client_encoding=UTF8","messagePattern":"simple protocol queries must be run with client_encoding=UTF8","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"conn.go","lineNumber":1270,"sourceCode":"\tif err != nil {\n\t\treturn &pipelineBatchResults{ctx: ctx, conn: c, err: err, closed: true}\n\t}\n\n\treturn &pipelineBatchResults{\n\t\tctx:      ctx,\n\t\tconn:     c,\n\t\tpipeline: pipeline,\n\t\tb:        b,\n\t}\n}\n\nfunc (c *Conn) sanitizeForSimpleQuery(sql string, args ...any) (string, error) {\n\tif c.pgConn.ParameterStatus(\"standard_conforming_strings\") != \"on\" {\n\t\treturn \"\", errors.New(\"simple protocol queries must be run with standard_conforming_strings=on\")\n\t}\n\n\tif c.pgConn.ParameterStatus(\"client_encoding\") != \"UTF8\" {\n\t\treturn \"\", errors.New(\"simple protocol queries must be run with client_encoding=UTF8\")\n\t}\n\n\tvar err error\n\tvalueArgs := make([]any, len(args))\n\tfor i, a := range args {\n\t\tvalueArgs[i], err = convertSimpleArgument(c.typeMap, a)\n\t\tif err != nil {\n\t\t\treturn \"\", err\n\t\t}\n\t}\n\n\treturn sanitize.SanitizeSQL(sql, valueArgs...)\n}\n\n// LoadType inspects the database for typeName and produces a [pgtype.Type] suitable for registration. typeName must be\n// the name of a type where the underlying type(s) is already understood by pgx. It is for derived types. In particular,\n// typeName must be one of the following:\n//   - An array type name of a type that is already registered. e.g. \"_foo\" when \"foo\" is registered.","sourceCodeStart":1252,"sourceCodeEnd":1288,"githubUrl":"https://github.com/jackc/pgx/blob/ec1a0befd22592cffffdeeb0a50311b506372f4c/conn.go#L1252-L1288","documentation":"Returned by sanitizeForSimpleQuery when the session's client_encoding is not 'UTF8'. Client-side SQL sanitization (simple protocol) assumes UTF-8 so byte-level escaping of string literals is correct; any other encoding could mis-escape and produce malformed or injectable SQL. pgx refuses rather than guess.","triggerScenarios":"Running simple-protocol queries against a session whose client_encoding GUC has been changed away from UTF8 (e.g. SET client_encoding='LATIN1'; or a server/pooler that negotiates a non-UTF8 client encoding).","commonSituations":"A legacy database or middleware that sets client_encoding to a regional encoding (LATIN1, SQL_ASCII, WIN1252); a connection pooler that injects encoding setup; restoring a dump that ran SET client_encoding.","solutions":["Remove any SET client_encoding=... that moves away from UTF8; let it default to UTF8.","Set the server default client_encoding to UTF8 in postgresql.conf.","Switch DefaultQueryExecMode to an extended-protocol mode so pgx binds parameters binary-wise and encoding of literal text no longer matters to sanitization.","After connect, verify SHOW client_encoding returns UTF8 and fail fast otherwise."],"exampleFix":"// before\nconfig.DefaultQueryExecMode = pgx.QueryExecModeExec\n// session has SET client_encoding='LATIN1'\n\n// after\nconfig.DefaultQueryExecMode = pgx.QueryExecModeCacheStatement\n// and ensure client_encoding stays UTF8","handlingStrategy":"validation","validationCode":"var ce string\nif err := conn.QueryRow(ctx, \"SHOW client_encoding\").Scan(&ce); err != nil { return err }\nif ce != \"UTF8\" { return fmt.Errorf(\"refusing simple-protocol: client_encoding=%q\", ce) }","typeGuard":"func utf8ForSimpleProtocol(c *pgx.Conn) bool {\n    return c.PgConn().ParameterStatus(\"client_encoding\") == \"UTF8\"\n}","tryCatchPattern":"if err != nil && strings.Contains(err.Error(), \"client_encoding=UTF8\") {\n    cfg.DefaultQueryExecMode = pgx.QueryExecModeCacheStatement // bypass sanitization\n}","preventionTips":["Keep client_encoding at UTF8 server-wide.","Avoid SET client_encoding=... to regional encodings.","Use extended-protocol modes so sanitization is not involved."],"tags":["simple-protocol","encoding","guc","sanitization"],"analyzedSha":"ec1a0befd22592cffffdeeb0a50311b506372f4c","analyzedAt":"2026-08-04T22:52:11.263Z","schemaVersion":2}