Line data Source code
1 : /*-------------------------------------------------------------------------
2 : *
3 : * uuid.c
4 : * Functions for the built-in type "uuid".
5 : *
6 : * Copyright (c) 2007-2024, PostgreSQL Global Development Group
7 : *
8 : * IDENTIFICATION
9 : * src/backend/utils/adt/uuid.c
10 : *
11 : *-------------------------------------------------------------------------
12 : */
13 :
14 : #include "postgres.h"
15 :
16 : #include "common/hashfn.h"
17 : #include "lib/hyperloglog.h"
18 : #include "libpq/pqformat.h"
19 : #include "port/pg_bswap.h"
20 : #include "utils/fmgrprotos.h"
21 : #include "utils/guc.h"
22 : #include "utils/sortsupport.h"
23 : #include "utils/timestamp.h"
24 : #include "utils/uuid.h"
25 :
26 : /* sortsupport for uuid */
27 : typedef struct
28 : {
29 : int64 input_count; /* number of non-null values seen */
30 : bool estimating; /* true if estimating cardinality */
31 :
32 : hyperLogLogState abbr_card; /* cardinality estimator */
33 : } uuid_sortsupport_state;
34 :
35 : static void string_to_uuid(const char *source, pg_uuid_t *uuid, Node *escontext);
36 : static int uuid_internal_cmp(const pg_uuid_t *arg1, const pg_uuid_t *arg2);
37 : static int uuid_fast_cmp(Datum x, Datum y, SortSupport ssup);
38 : static bool uuid_abbrev_abort(int memtupcount, SortSupport ssup);
39 : static Datum uuid_abbrev_convert(Datum original, SortSupport ssup);
40 :
41 : Datum
42 585872 : uuid_in(PG_FUNCTION_ARGS)
43 : {
44 585872 : char *uuid_str = PG_GETARG_CSTRING(0);
45 : pg_uuid_t *uuid;
46 :
47 585872 : uuid = (pg_uuid_t *) palloc(sizeof(*uuid));
48 585872 : string_to_uuid(uuid_str, uuid, fcinfo->context);
49 585836 : PG_RETURN_UUID_P(uuid);
50 : }
51 :
52 : Datum
53 4662 : uuid_out(PG_FUNCTION_ARGS)
54 : {
55 4662 : pg_uuid_t *uuid = PG_GETARG_UUID_P(0);
56 : static const char hex_chars[] = "0123456789abcdef";
57 : char *buf,
58 : *p;
59 : int i;
60 :
61 : /* counts for the four hyphens and the zero-terminator */
62 4662 : buf = palloc(2 * UUID_LEN + 5);
63 4662 : p = buf;
64 79254 : for (i = 0; i < UUID_LEN; i++)
65 : {
66 : int hi;
67 : int lo;
68 :
69 : /*
70 : * We print uuid values as a string of 8, 4, 4, 4, and then 12
71 : * hexadecimal characters, with each group is separated by a hyphen
72 : * ("-"). Therefore, add the hyphens at the appropriate places here.
73 : */
74 74592 : if (i == 4 || i == 6 || i == 8 || i == 10)
75 18648 : *p++ = '-';
76 :
77 74592 : hi = uuid->data[i] >> 4;
78 74592 : lo = uuid->data[i] & 0x0F;
79 :
80 74592 : *p++ = hex_chars[hi];
81 74592 : *p++ = hex_chars[lo];
82 : }
83 4662 : *p = '\0';
84 :
85 4662 : PG_RETURN_CSTRING(buf);
86 : }
87 :
88 : /*
89 : * We allow UUIDs as a series of 32 hexadecimal digits with an optional dash
90 : * after each group of 4 hexadecimal digits, and optionally surrounded by {}.
91 : * (The canonical format 8x-4x-4x-4x-12x, where "nx" means n hexadecimal
92 : * digits, is the only one used for output.)
93 : */
94 : static void
95 585872 : string_to_uuid(const char *source, pg_uuid_t *uuid, Node *escontext)
96 : {
97 585872 : const char *src = source;
98 585872 : bool braces = false;
99 : int i;
100 :
101 585872 : if (src[0] == '{')
102 : {
103 24 : src++;
104 24 : braces = true;
105 : }
106 :
107 9959410 : for (i = 0; i < UUID_LEN; i++)
108 : {
109 : char str_buf[3];
110 :
111 9373574 : if (src[0] == '\0' || src[1] == '\0')
112 36 : goto syntax_error;
113 9373562 : memcpy(str_buf, src, 2);
114 9373562 : if (!isxdigit((unsigned char) str_buf[0]) ||
115 9373550 : !isxdigit((unsigned char) str_buf[1]))
116 24 : goto syntax_error;
117 :
118 9373538 : str_buf[2] = '\0';
119 9373538 : uuid->data[i] = (unsigned char) strtoul(str_buf, NULL, 16);
120 9373538 : src += 2;
121 9373538 : if (src[0] == '-' && (i % 2) == 1 && i < UUID_LEN - 1)
122 1935314 : src++;
123 : }
124 :
125 585836 : if (braces)
126 : {
127 18 : if (*src != '}')
128 6 : goto syntax_error;
129 12 : src++;
130 : }
131 :
132 585830 : if (*src != '\0')
133 6 : goto syntax_error;
134 :
135 585824 : return;
136 :
137 48 : syntax_error:
138 48 : ereturn(escontext,,
139 : (errcode(ERRCODE_INVALID_TEXT_REPRESENTATION),
140 : errmsg("invalid input syntax for type %s: \"%s\"",
141 : "uuid", source)));
142 : }
143 :
144 : Datum
145 0 : uuid_recv(PG_FUNCTION_ARGS)
146 : {
147 0 : StringInfo buffer = (StringInfo) PG_GETARG_POINTER(0);
148 : pg_uuid_t *uuid;
149 :
150 0 : uuid = (pg_uuid_t *) palloc(UUID_LEN);
151 0 : memcpy(uuid->data, pq_getmsgbytes(buffer, UUID_LEN), UUID_LEN);
152 0 : PG_RETURN_POINTER(uuid);
153 : }
154 :
155 : Datum
156 0 : uuid_send(PG_FUNCTION_ARGS)
157 : {
158 0 : pg_uuid_t *uuid = PG_GETARG_UUID_P(0);
159 : StringInfoData buffer;
160 :
161 0 : pq_begintypsend(&buffer);
162 0 : pq_sendbytes(&buffer, uuid->data, UUID_LEN);
163 0 : PG_RETURN_BYTEA_P(pq_endtypsend(&buffer));
164 : }
165 :
166 : /* internal uuid compare function */
167 : static int
168 41772788 : uuid_internal_cmp(const pg_uuid_t *arg1, const pg_uuid_t *arg2)
169 : {
170 41772788 : return memcmp(arg1->data, arg2->data, UUID_LEN);
171 : }
172 :
173 : Datum
174 84206 : uuid_lt(PG_FUNCTION_ARGS)
175 : {
176 84206 : pg_uuid_t *arg1 = PG_GETARG_UUID_P(0);
177 84206 : pg_uuid_t *arg2 = PG_GETARG_UUID_P(1);
178 :
179 84206 : PG_RETURN_BOOL(uuid_internal_cmp(arg1, arg2) < 0);
180 : }
181 :
182 : Datum
183 17046 : uuid_le(PG_FUNCTION_ARGS)
184 : {
185 17046 : pg_uuid_t *arg1 = PG_GETARG_UUID_P(0);
186 17046 : pg_uuid_t *arg2 = PG_GETARG_UUID_P(1);
187 :
188 17046 : PG_RETURN_BOOL(uuid_internal_cmp(arg1, arg2) <= 0);
189 : }
190 :
191 : Datum
192 154418 : uuid_eq(PG_FUNCTION_ARGS)
193 : {
194 154418 : pg_uuid_t *arg1 = PG_GETARG_UUID_P(0);
195 154418 : pg_uuid_t *arg2 = PG_GETARG_UUID_P(1);
196 :
197 154418 : PG_RETURN_BOOL(uuid_internal_cmp(arg1, arg2) == 0);
198 : }
199 :
200 : Datum
201 12914 : uuid_ge(PG_FUNCTION_ARGS)
202 : {
203 12914 : pg_uuid_t *arg1 = PG_GETARG_UUID_P(0);
204 12914 : pg_uuid_t *arg2 = PG_GETARG_UUID_P(1);
205 :
206 12914 : PG_RETURN_BOOL(uuid_internal_cmp(arg1, arg2) >= 0);
207 : }
208 :
209 : Datum
210 16290 : uuid_gt(PG_FUNCTION_ARGS)
211 : {
212 16290 : pg_uuid_t *arg1 = PG_GETARG_UUID_P(0);
213 16290 : pg_uuid_t *arg2 = PG_GETARG_UUID_P(1);
214 :
215 16290 : PG_RETURN_BOOL(uuid_internal_cmp(arg1, arg2) > 0);
216 : }
217 :
218 : Datum
219 18 : uuid_ne(PG_FUNCTION_ARGS)
220 : {
221 18 : pg_uuid_t *arg1 = PG_GETARG_UUID_P(0);
222 18 : pg_uuid_t *arg2 = PG_GETARG_UUID_P(1);
223 :
224 18 : PG_RETURN_BOOL(uuid_internal_cmp(arg1, arg2) != 0);
225 : }
226 :
227 : /* handler for btree index operator */
228 : Datum
229 9272 : uuid_cmp(PG_FUNCTION_ARGS)
230 : {
231 9272 : pg_uuid_t *arg1 = PG_GETARG_UUID_P(0);
232 9272 : pg_uuid_t *arg2 = PG_GETARG_UUID_P(1);
233 :
234 9272 : PG_RETURN_INT32(uuid_internal_cmp(arg1, arg2));
235 : }
236 :
237 : /*
238 : * Sort support strategy routine
239 : */
240 : Datum
241 350 : uuid_sortsupport(PG_FUNCTION_ARGS)
242 : {
243 350 : SortSupport ssup = (SortSupport) PG_GETARG_POINTER(0);
244 :
245 350 : ssup->comparator = uuid_fast_cmp;
246 350 : ssup->ssup_extra = NULL;
247 :
248 350 : if (ssup->abbreviate)
249 : {
250 : uuid_sortsupport_state *uss;
251 : MemoryContext oldcontext;
252 :
253 278 : oldcontext = MemoryContextSwitchTo(ssup->ssup_cxt);
254 :
255 278 : uss = palloc(sizeof(uuid_sortsupport_state));
256 278 : uss->input_count = 0;
257 278 : uss->estimating = true;
258 278 : initHyperLogLog(&uss->abbr_card, 10);
259 :
260 278 : ssup->ssup_extra = uss;
261 :
262 278 : ssup->comparator = ssup_datum_unsigned_cmp;
263 278 : ssup->abbrev_converter = uuid_abbrev_convert;
264 278 : ssup->abbrev_abort = uuid_abbrev_abort;
265 278 : ssup->abbrev_full_comparator = uuid_fast_cmp;
266 :
267 278 : MemoryContextSwitchTo(oldcontext);
268 : }
269 :
270 350 : PG_RETURN_VOID();
271 : }
272 :
273 : /*
274 : * SortSupport comparison func
275 : */
276 : static int
277 41478624 : uuid_fast_cmp(Datum x, Datum y, SortSupport ssup)
278 : {
279 41478624 : pg_uuid_t *arg1 = DatumGetUUIDP(x);
280 41478624 : pg_uuid_t *arg2 = DatumGetUUIDP(y);
281 :
282 41478624 : return uuid_internal_cmp(arg1, arg2);
283 : }
284 :
285 : /*
286 : * Callback for estimating effectiveness of abbreviated key optimization.
287 : *
288 : * We pay no attention to the cardinality of the non-abbreviated data, because
289 : * there is no equality fast-path within authoritative uuid comparator.
290 : */
291 : static bool
292 2322 : uuid_abbrev_abort(int memtupcount, SortSupport ssup)
293 : {
294 2322 : uuid_sortsupport_state *uss = ssup->ssup_extra;
295 : double abbr_card;
296 :
297 2322 : if (memtupcount < 10000 || uss->input_count < 10000 || !uss->estimating)
298 2130 : return false;
299 :
300 192 : abbr_card = estimateHyperLogLog(&uss->abbr_card);
301 :
302 : /*
303 : * If we have >100k distinct values, then even if we were sorting many
304 : * billion rows we'd likely still break even, and the penalty of undoing
305 : * that many rows of abbrevs would probably not be worth it. Stop even
306 : * counting at that point.
307 : */
308 192 : if (abbr_card > 100000.0)
309 : {
310 0 : if (trace_sort)
311 0 : elog(LOG,
312 : "uuid_abbrev: estimation ends at cardinality %f"
313 : " after " INT64_FORMAT " values (%d rows)",
314 : abbr_card, uss->input_count, memtupcount);
315 0 : uss->estimating = false;
316 0 : return false;
317 : }
318 :
319 : /*
320 : * Target minimum cardinality is 1 per ~2k of non-null inputs. 0.5 row
321 : * fudge factor allows us to abort earlier on genuinely pathological data
322 : * where we've had exactly one abbreviated value in the first 2k
323 : * (non-null) rows.
324 : */
325 192 : if (abbr_card < uss->input_count / 2000.0 + 0.5)
326 : {
327 96 : if (trace_sort)
328 0 : elog(LOG,
329 : "uuid_abbrev: aborting abbreviation at cardinality %f"
330 : " below threshold %f after " INT64_FORMAT " values (%d rows)",
331 : abbr_card, uss->input_count / 2000.0 + 0.5, uss->input_count,
332 : memtupcount);
333 96 : return true;
334 : }
335 :
336 96 : if (trace_sort)
337 0 : elog(LOG,
338 : "uuid_abbrev: cardinality %f after " INT64_FORMAT
339 : " values (%d rows)", abbr_card, uss->input_count, memtupcount);
340 :
341 96 : return false;
342 : }
343 :
344 : /*
345 : * Conversion routine for sortsupport. Converts original uuid representation
346 : * to abbreviated key representation. Our encoding strategy is simple -- pack
347 : * the first `sizeof(Datum)` bytes of uuid data into a Datum (on little-endian
348 : * machines, the bytes are stored in reverse order), and treat it as an
349 : * unsigned integer.
350 : */
351 : static Datum
352 3384090 : uuid_abbrev_convert(Datum original, SortSupport ssup)
353 : {
354 3384090 : uuid_sortsupport_state *uss = ssup->ssup_extra;
355 3384090 : pg_uuid_t *authoritative = DatumGetUUIDP(original);
356 : Datum res;
357 :
358 3384090 : memcpy(&res, authoritative->data, sizeof(Datum));
359 3384090 : uss->input_count += 1;
360 :
361 3384090 : if (uss->estimating)
362 : {
363 : uint32 tmp;
364 :
365 : #if SIZEOF_DATUM == 8
366 3384090 : tmp = (uint32) res ^ (uint32) ((uint64) res >> 32);
367 : #else /* SIZEOF_DATUM != 8 */
368 : tmp = (uint32) res;
369 : #endif
370 :
371 3384090 : addHyperLogLog(&uss->abbr_card, DatumGetUInt32(hash_uint32(tmp)));
372 : }
373 :
374 : /*
375 : * Byteswap on little-endian machines.
376 : *
377 : * This is needed so that ssup_datum_unsigned_cmp() (an unsigned integer
378 : * 3-way comparator) works correctly on all platforms. If we didn't do
379 : * this, the comparator would have to call memcmp() with a pair of
380 : * pointers to the first byte of each abbreviated key, which is slower.
381 : */
382 3384090 : res = DatumBigEndianToNative(res);
383 :
384 3384090 : return res;
385 : }
386 :
387 : /* hash index support */
388 : Datum
389 2388 : uuid_hash(PG_FUNCTION_ARGS)
390 : {
391 2388 : pg_uuid_t *key = PG_GETARG_UUID_P(0);
392 :
393 2388 : return hash_any(key->data, UUID_LEN);
394 : }
395 :
396 : Datum
397 60 : uuid_hash_extended(PG_FUNCTION_ARGS)
398 : {
399 60 : pg_uuid_t *key = PG_GETARG_UUID_P(0);
400 :
401 60 : return hash_any_extended(key->data, UUID_LEN, PG_GETARG_INT64(1));
402 : }
403 :
404 : Datum
405 24 : gen_random_uuid(PG_FUNCTION_ARGS)
406 : {
407 24 : pg_uuid_t *uuid = palloc(UUID_LEN);
408 :
409 24 : if (!pg_strong_random(uuid, UUID_LEN))
410 0 : ereport(ERROR,
411 : (errcode(ERRCODE_INTERNAL_ERROR),
412 : errmsg("could not generate random values")));
413 :
414 : /*
415 : * Set magic numbers for a "version 4" (pseudorandom) UUID, see
416 : * http://tools.ietf.org/html/rfc4122#section-4.4
417 : */
418 24 : uuid->data[6] = (uuid->data[6] & 0x0f) | 0x40; /* time_hi_and_version */
419 24 : uuid->data[8] = (uuid->data[8] & 0x3f) | 0x80; /* clock_seq_hi_and_reserved */
420 :
421 24 : PG_RETURN_UUID_P(uuid);
422 : }
423 :
424 : #define UUIDV1_EPOCH_JDATE 2299161 /* == date2j(1582,10,15) */
425 :
426 : /*
427 : * Extract timestamp from UUID.
428 : *
429 : * Returns null if not RFC 4122 variant or not a version that has a timestamp.
430 : */
431 : Datum
432 18 : uuid_extract_timestamp(PG_FUNCTION_ARGS)
433 : {
434 18 : pg_uuid_t *uuid = PG_GETARG_UUID_P(0);
435 : int version;
436 : uint64 tms;
437 : TimestampTz ts;
438 :
439 : /* check if RFC 4122 variant */
440 18 : if ((uuid->data[8] & 0xc0) != 0x80)
441 6 : PG_RETURN_NULL();
442 :
443 12 : version = uuid->data[6] >> 4;
444 :
445 12 : if (version == 1)
446 : {
447 6 : tms = ((uint64) uuid->data[0] << 24)
448 6 : + ((uint64) uuid->data[1] << 16)
449 6 : + ((uint64) uuid->data[2] << 8)
450 6 : + ((uint64) uuid->data[3])
451 6 : + ((uint64) uuid->data[4] << 40)
452 6 : + ((uint64) uuid->data[5] << 32)
453 6 : + (((uint64) uuid->data[6] & 0xf) << 56)
454 6 : + ((uint64) uuid->data[7] << 48);
455 :
456 : /* convert 100-ns intervals to us, then adjust */
457 6 : ts = (TimestampTz) (tms / 10) -
458 : ((uint64) POSTGRES_EPOCH_JDATE - UUIDV1_EPOCH_JDATE) * SECS_PER_DAY * USECS_PER_SEC;
459 :
460 6 : PG_RETURN_TIMESTAMPTZ(ts);
461 : }
462 :
463 : /* not a timestamp-containing UUID version */
464 6 : PG_RETURN_NULL();
465 : }
466 :
467 : /*
468 : * Extract UUID version.
469 : *
470 : * Returns null if not RFC 4122 variant.
471 : */
472 : Datum
473 18 : uuid_extract_version(PG_FUNCTION_ARGS)
474 : {
475 18 : pg_uuid_t *uuid = PG_GETARG_UUID_P(0);
476 : uint16 version;
477 :
478 : /* check if RFC 4122 variant */
479 18 : if ((uuid->data[8] & 0xc0) != 0x80)
480 6 : PG_RETURN_NULL();
481 :
482 12 : version = uuid->data[6] >> 4;
483 :
484 12 : PG_RETURN_UINT16(version);
485 : }
|
