tsiry-sandratraina.com
PostgreSQL extension for generating Xata-style xata_id unique identifiers (rec_<20_chars>) using Rust and pgrx.
add README file
+1
-4
.tangled/workflows/ci.yml
+1
-4
.tangled/workflows/ci.yml
+19
LICENSE
+19
LICENSE
···
1
+
Copyright (c) 2025 Tsiry Sandratraina <tsiry.sndr@rocksky.app>
2
+
3
+
Permission is hereby granted, free of charge, to any person obtaining a copy
4
+
of this software and associated documentation files (the "Software"), to deal
5
+
in the Software without restriction, including without limitation the rights
6
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
7
+
copies of the Software, and to permit persons to whom the Software is
8
+
furnished to do so, subject to the following conditions:
9
+
10
+
The above copyright notice and this permission notice shall be included in all
11
+
copies or substantial portions of the Software.
12
+
13
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
14
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
15
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
16
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
17
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
18
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
19
+
SOFTWARE.
+100
README.md
+100
README.md
···
1
+
# xata_id PostgreSQL Extension
2
+
[](https://github.com/tsirysndr/xata_id_extension/actions/workflows/ci.yml)
3
+
4
+
A PostgreSQL extension written in Rust using pgrx to generate Xata-style unique identifiers (xata_id) in the format rec_<20_random_chars>. The IDs consist of a rec_ prefix followed by a 20-character random string using the alphabet a-z0-9, mimicking Xata's ID format (e.g., ` rec_cug4h6ibhfbm7uq5dte0`).
5
+
6
+
## Features
7
+
- Generates 24-character unique IDs with a rec_ prefix and 20 random characters (a-z0-9).
8
+
- Safe integration with PostgreSQL via pgrx for robust memory management.
9
+
- Comprehensive unit and integration tests to verify ID format, length, and uniqueness.
10
+
- Lightweight and performant, suitable for use as a primary key default value.
11
+
12
+
## Requirements
13
+
- PostgreSQL 13–18
14
+
- Rust and cargo-pgrx (version 0.15)
15
+
- A compatible operating system (Linux, macOS, or Windows with WSL)
16
+
17
+
## Installation
18
+
**1. Install Dependencies**
19
+
20
+
Install Rust and pgrx:
21
+
22
+
```bash
23
+
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
24
+
cargo install cargo-pgrx
25
+
cargo pgrx init
26
+
```
27
+
28
+
**2. Clone the repository:**
29
+
30
+
```bash
31
+
git clone https://github.com/tsirysndr/xata_id_extension
32
+
cd xata_id_extension
33
+
```
34
+
35
+
**3. Build the Extension**
36
+
37
+
Compile the extension for your PostgreSQL version (e.g., PostgreSQL 16):
38
+
39
+
```bash
40
+
cargo pgrx package
41
+
```
42
+
43
+
**4. Install the Extension**
44
+
45
+
Install the extension to your PostgreSQL instance:
46
+
47
+
```bash
48
+
cargo pgrx install
49
+
```
50
+
51
+
**5. Enable the Extension in PostgreSQL**
52
+
53
+
Connect to your PostgreSQL database and run:
54
+
55
+
```bash
56
+
psql -d your_database_name
57
+
```
58
+
59
+
Then, enable the extension:
60
+
61
+
```sql
62
+
CREATE EXTENSION xata_id_extension;
63
+
```
64
+
65
+
## Usage
66
+
67
+
The extension provides a `xata_id()` function that generates a unique ID. Use it as the default value for a primary key in a table:
68
+
69
+
**Create a Table**
70
+
71
+
```sql
72
+
CREATE TABLE users (
73
+
id TEXT PRIMARY KEY DEFAULT xata_id(),
74
+
username VARCHAR(50) NOT NULL,
75
+
email VARCHAR(255) UNIQUE,
76
+
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
77
+
);
78
+
```
79
+
**Insert Data**
80
+
81
+
Insert rows, and the id column will automatically use xata_id():
82
+
83
+
```sql
84
+
INSERT INTO users (username, email) VALUES ('alice', 'alice@example.com');
85
+
INSERT INTO users (username, email) VALUES ('bob', 'bob@example.com');
86
+
SELECT * FROM users;
87
+
```
88
+
89
+
**Example Output**
90
+
91
+
```plaintext
92
+
id | username | email | created_at
93
+
--------------------------+----------+-------------------+------------------------
94
+
rec_cug4h6ibhfbm7uq5dte0 | alice | alice@example.com | 2025-07-25 12:00:00
95
+
rec_4h6ibhfbm7uq5dte0cug | bob | bob@example.com | 2025-07-25 12:01:00
96
+
```
97
+
98
+
## License
99
+
100
+
This project is licensed under the MIT License. See the [LICENSE](./LICENSE) file for details.