### Start Pogocache Server with Configuration Options

Source: https://context7.com/tidwall/pogocache/llms.txt

Demonstrates various ways to start the Pogocache server, including basic startup, binding to specific hosts, and applying full configuration options like memory limits, persistence, and threading. Also includes a Docker deployment example and version check.

```bash
# Basic startup on localhost:9401
./pogocache

# Bind to specific host for external access
./pogocache -h 172.30.2.84 -p 9401

# Full configuration with memory limits and persistence
./pogocache -h 0.0.0.0 -p 9401 \
    --threads 8 \
    --maxmemory 4G \
    --evict yes \
    --persist /data/cache.db \
    --maxconns 2048 \
    --shards 4096

# Docker deployment
docker run -p 9401:9401 pogocache/pogocache

# Show version
./pogocache --version
# Output: pogocache 1.x.x
```

--------------------------------

### Server Configuration and Startup

Source: https://context7.com/tidwall/pogocache/llms.txt

Instructions and examples for starting the Pogocache server with various configuration options, including host binding, memory limits, threading, persistence, and Docker deployment.

```APIDOC
## Server Configuration and Startup

Start Pogocache server with custom configuration options for host binding, memory limits, threading, and security.

### Basic startup on localhost:9401
```bash
./pogocache
```

### Bind to specific host for external access
```bash
./pogocache -h 172.30.2.84 -p 9401
```

### Full configuration with memory limits and persistence
```bash
./pogocache -h 0.0.0.0 -p 9401 \
    --threads 8 \
    --maxmemory 4G \
    --evict yes \
    --persist /data/cache.db \
    --maxconns 2048 \
    --shards 4096
```

### Docker deployment
```bash
docker run -p 9401:9401 pogocache/pogocache
```

### Show version
```bash
./pogocache --version
# Output: pogocache 1.x.x
```
```

--------------------------------

### Python Example: Storing and Retrieving Data with Pogocache (Postgres)

Source: https://github.com/tidwall/pogocache/blob/main/README.md

Demonstrates how to connect to Pogocache using the psycopg library in Python, store key-value pairs using SET commands, and retrieve them using GET and MGET commands. It also shows how to iterate over multiple retrieved values.

```python
import psycopg

# Connect to Pogocache
conn = psycopg.connect("host=localhost port=9401")

# Insert some values
conn.execute("SET first Tom")
conn.execute("SET last Anderson")
conn.execute("SET age 37")
conn.execute("SET city %s", ["Phoenix"])

# Get the values back
print(conn.execute("GET first").fetchone()[0])
print(conn.execute("GET last").fetchone()[0])
print(conn.execute("GET age").fetchone()[0])
print(conn.execute("GET %s", ["city"]).fetchone()[0])

# Loop over multiple values
for row in conn.execute("MGET first last city"):
    print(row[0], row[1])

conn.close()

# Output:
# Tom
# Anderson
# 37
# first Tom
# last Anderson
# city Phoenix
```

--------------------------------

### Go Example: Parameterized Queries with Pogocache (pgx)

Source: https://github.com/tidwall/pogocache/blob/main/README.md

Demonstrates using parameterized queries with the jackc/pgx Go client to interact with Pogocache. It shows setting and getting single values and multiple user-related fields using placeholders like $1 and $2.

```go
package main

import (
	"context"
	"fmt"
	"os"

	"github.com/jackc/pgx/v5"
)

func main() {
	// Connect to Pogocache
	url := "postgres://127.0.0.1:9401"
	conn, err := pgx.Connect(context.Background(), url)
	if err != nil {
		fmt.Fprintf(os.Stderr, "Unable to connect to cache: %v\n", err)
		os.Exit(1)
	}
	defer conn.Close(context.Background())

	conn.Exec(context.Background(), "SET $1 $2", "first", "Tom")
	row := conn.QueryRow(context.Background(), "GET $1", "first")

	var value string
	row.Scan(&value)
	println(value)

	userID := "1287"
	conn.Exec(context.Background(), "SET user:$1:first $2", userID, "Tom")
	conn.Exec(context.Background(), "SET user:$1:last $2", userID, "Anderson")
	conn.Exec(context.Background(), "SET user:$1:age $2", userID, "37")

	var first, last, age string

	conn.QueryRow(context.Background(), "GET user:$1:first", userID).Scan(&first)
	conn.QueryRow(context.Background(), "GET user:$1:last", userID).Scan(&last)
	conn.QueryRow(context.Background(), "GET user:$1:age", userID).Scan(&age)

	println(first)
	println(last)
	println(age)
}

// Output:
// Tom
// Tom
// Anderson
// 37
```

--------------------------------

### Configure Password Authentication for Pogocache

Source: https://context7.com/tidwall/pogocache/llms.txt

This section explains how to enable and use password authentication for the Pogocache server. It shows how to start the server with a specified password and how to connect using `valkey-cli`, either by providing the password directly or by authenticating after connection. Examples for HTTP authentication using headers and query strings are also provided.

```bash
# Start server with auth password
./pogocache --auth mypassword

# Connect with valkey-cli
valkey-cli -p 9401 -a mypassword

# Or authenticate after connection
valkey-cli -p 9401
> AUTH mypassword
OK
> GET mykey
"value"

# HTTP with auth via header
curl -H "Authorization: Bearer mypassword" "http://localhost:9401/mykey"

# HTTP with auth via query string
curl "http://localhost:9401/mykey?auth=mypassword"

```

--------------------------------

### Pogocache HTTP PUT Entry Example

Source: https://github.com/tidwall/pogocache/blob/main/README.md

Provides examples of storing an entry using the HTTP PUT method. It includes storing with a TTL and conditional storage.

```shell
curl -X PUT -d "my value" "http://localhost:9401/mykey"        # store entry
curl -X PUT -d "my value" "http://localhost:9401/mykey?ttl=15" # store with 15 second ttl

```

--------------------------------

### Configure Persistence (Save/Load) for Pogocache

Source: https://context7.com/tidwall/pogocache/llms.txt

This guide covers how to configure Pogocache for data persistence, allowing the cache state to be saved to disk and restored on startup. It demonstrates starting the server with a persistence file path and performing manual save and load operations using `valkey-cli`. The document also notes that data is automatically saved on shutdown and loaded on startup when persistence is enabled.

```bash
# Start with persistence file
./pogocache --persist /data/cache.db

# Manual save via client
valkey-cli -p 9401
> SAVE
OK
> SAVE TO /backup/snapshot.db
OK
> SAVE TO /backup/snapshot.db FAST
OK

# Manual load
> LOAD FROM /backup/snapshot.db
OK

# On shutdown, data is automatically saved if --persist is set
# On startup, data is automatically loaded from the persist file

```

--------------------------------

### Pogocache RESP (Valkey/Redis) Protocol Commands

Source: https://context7.com/tidwall/pogocache/llms.txt

Provides examples of using standard Redis/Valkey commands with Pogocache via clients like valkey-cli or redis-cli. Covers basic operations like SET, GET, DEL, and more advanced commands.

```redis
# Connect using valkey-cli
valkey-cli -p 9401

# SET - Store a value
> SET user:1001:name "John Doe"
OK

# SET with expiration (EX = seconds, PX = milliseconds)
> SET session:abc123 "token_data" EX 3600
OK

# SET with NX (only if not exists)
> SET unique:lock "locked" NX
OK

# SET with XX (only if exists)
> SET user:1001:name "Jane Doe" XX
OK

# GET - Retrieve a value
> GET user:1001:name
"Jane Doe"

# MGET - Get multiple keys
> MGET user:1001:name user:1001:email user:1001:age
1) "Jane Doe"
2) "jane@example.com"
3) "30"

# DEL - Delete keys
> DEL user:1001:name user:1001:email
(integer) 2

# EXISTS - Check if keys exist
> EXISTS user:1001:age session:abc123
(integer) 2

# TTL - Get remaining time to live in seconds
> TTL session:abc123
(integer) 3542

# PTTL - Get remaining time to live in milliseconds
> PTTL session:abc123
(integer) 3542000

# EXPIRE - Set expiration on existing key
> EXPIRE user:1001:age 86400
(integer) 1

# INCR/DECR - Atomic increment/decrement
> SET counter 100
OK
> INCR counter
(integer) 101
> DECR counter
(integer) 100
> INCRBY counter 50
(integer) 150
> DECRBY counter 25
(integer) 125

# APPEND/PREPEND - String manipulation
> SET greeting "Hello"
OK
> APPEND greeting " World"
(integer) 11
> GET greeting
"Hello World"

# KEYS - Pattern matching (use with caution)
> KEYS user:*
1) "user:1001:age"

# SCAN - Cursor-based iteration
> SCAN 0 MATCH user:* COUNT 100
1) "0"
2) 1) "user:1001:age"

# DBSIZE - Get total key count
> DBSIZE
(integer) 5

# FLUSHALL - Clear all data
> FLUSHALL
OK

# PING - Health check
> PING
PONG
> PING "hello"
"hello"
```

--------------------------------

### Pogocache HTTP DELETE Entry Example

Source: https://github.com/tidwall/pogocache/blob/main/README.md

Shows an example of deleting an entry using the HTTP DELETE method. Note: The provided example in the source text seems to be a duplicate of the PUT example, this reflects the intended DELETE operation.

```shell
curl -X DELETE "http://localhost:9401/mykey"

```

--------------------------------

### Pogocache HTTP API - Get Entry

Source: https://context7.com/tidwall/pogocache/llms.txt

Demonstrates retrieving values by key using HTTP GET requests. Includes examples for existing keys, non-existent keys, and authentication.

```bash
# Get existing key
curl "http://localhost:9401/mykey"
# Output: my value

# Get non-existent key
curl "http://localhost:9401/nonexistent"
# Output: Not Found (HTTP 404)

# Get with authentication
curl "http://localhost:9401/protected?auth=mypassword"
# Output: secure data

# Using Authorization header
curl -H "Authorization: Bearer mypassword" "http://localhost:9401/protected"
# Output: secure data
```

--------------------------------

### Shell Example: Basic Data Operations with Pogocache (psql)

Source: https://github.com/tidwall/pogocache/blob/main/README.md

Illustrates basic data storage operations using the psql command-line tool to interact with Pogocache. It shows how to set key-value pairs using the SET command.

```sh
psql -h localhost -p 9401
=> SET first Tom;
=> SET last Anderson;
=> SET age 37;
```

--------------------------------

### Interact with Pogocache using psql (Postgres)

Source: https://github.com/tidwall/pogocache/blob/main/README.md

Illustrates connecting to Pogocache with psql and using SQL-like commands to SET, GET, and DEL entries.

```shell
psql -h localhost -p 9401
=> SET mykey 'my value';
=> GET mykey;
=> DEL mykey;

```

--------------------------------

### Interact with Pogocache using valkey-cli (RESP)

Source: https://github.com/tidwall/pogocache/blob/main/README.md

Shows how to connect to Pogocache using valkey-cli and perform SET, GET, and DEL operations using the RESP protocol.

```shell
$ valkey-cli -p 9401
> SET mykey value
OK
> GET mykey
"my value"
> DEL mykey
(integer) 1

```

--------------------------------

### Python Example: Handling Binary Data with Pogocache (Postgres)

Source: https://github.com/tidwall/pogocache/blob/main/README.md

Shows how to store and retrieve binary data using Pogocache with the psycopg library. It demonstrates switching the output format to '::bytea' for binary data and back to '::text' for text data.

```python
import psycopg

conn = psycopg.connect("host=localhost port=9401")

conn.execute("SET name %s", ["Tom"])
conn.execute("SET binary %s", [b'\x00\x01\x02hello\xff'])

conn.execute("::bytea")
print(conn.execute("GET name").fetchone()[0])
print(conn.execute("GET binary").fetchone()[0])

conn.execute("::text")
print(conn.execute("GET name").fetchone()[0])

# Output:
# b'Tom'
# b'\x00\x01\x02hello\xff'
# Tom
```

--------------------------------

### Run Pogocache Server

Source: https://github.com/tidwall/pogocache/blob/main/README.md

Starts the Pogocache server on localhost port 9401. To bind to an accessible host address, use the '-h' flag.

```shell
./pogocache

```

```shell
./pogocache -h 172.30.2.84

```

--------------------------------

### Start Pogocache with TLS

Source: https://github.com/tidwall/pogocache/blob/main/README.md

Starts the Pogocache server with TLS enabled. It configures the TLS port, certificate, key, and CA certificate. The plain-text port is disabled by setting '-p 0'.

```shell
pogocache -p 0 \
   --tlsport 9401 \
   --tlscert pogocache.crt \
   --tlskey pogocache.key \
   --tlscacert ca.crt
```

--------------------------------

### Example Pogocache File Header

Source: https://github.com/tidwall/pogocache/blob/main/CONTRIBUTING.md

This is an example of the standard header comment for files within the Pogocache project. It specifies copyright, project affiliation, and licensing terms.

```text
// Copyright 2025 Polypoint Labs, LLC. All rights reserved.
// This file is part of the Pogocache project.
// Use of this source code is governed by the MIT that can be found in
// the LICENSE file.
```

--------------------------------

### Shell Example: Generating TLS Certificates for Pogocache

Source: https://github.com/tidwall/pogocache/blob/main/README.md

Provides OpenSSL commands to generate a Certificate Authority (CA) certificate, a server certificate, and a server private key, which are necessary for enabling TLS/HTTPS with Pogocache.

```sh
# Generate CA key and cert
openssl req -x509 -newkey rsa:4096 -sha256 -days 365 -nodes \
  -keyout ca.key -out ca.crt -subj "/CN=My Pogocache CA"

# Generate server key and CSR
openssl req -newkey rsa:4096 -nodes -keyout pogocache.key -out pogocache.csr -subj "/CN=localhost"

# Sign server cert with CA
openssl x509 -req -sha256 -days 365 -in pogocache.csr -CA ca.crt -CAkey ca.key -CAcreateserial -out pogocache.crt
```

--------------------------------

### Configure Pogocache with an Auth Password

Source: https://github.com/tidwall/pogocache/blob/main/README.md

Starts Pogocache with an optional authentication password. This password must then be provided for all subsequent client connections.

```shell
pogocache --auth mypass
```

--------------------------------

### Example Contributor-Owned File Header

Source: https://github.com/tidwall/pogocache/blob/main/CONTRIBUTING.md

An example of a header comment that a contributor can use to retain ownership of their work within Pogocache. It includes copyright and license information.

```text
// Copyright (c) 2025 Your Name
// License: MIT
```

--------------------------------

### Memcache Text Protocol - Basic Commands

Source: https://context7.com/tidwall/pogocache/llms.txt

Demonstrates basic commands using the Memcache text protocol, including SET, GET, ADD, REPLACE, DELETE, INCR, DECR, APPEND, PREPEND, FLUSH_ALL, VERSION, and STATS.

```APIDOC
## Memcache Text Protocol - Basic Commands

### Description
Interact with Pogocache using the standard Memcache text protocol. This allows compatibility with standard Memcache clients and tools like telnet.

### Method
Any (via Memcache client or telnet)

### Endpoint
`telnet localhost 9401`

### Commands
#### SET
- **Description**: Stores a key-value pair. If the key already exists, its value is updated.
- **Syntax**: `set <key> <flags> <exptime> <bytes>`
- **Example**: `set mykey 0 0 5\nhello\nSTORED`

#### GET
- **Description**: Retrieves the value associated with a key.
- **Syntax**: `get <key>`
- **Example**: `get mykey\nVALUE mykey 0 5\nhello\nEND`

#### GETS
- **Description**: Retrieves a key and its unique CAS (Check-And-Set) token.
- **Syntax**: `gets <key>`
- **Example**: `gets mykey\nVALUE mykey 0 5 12345\nhello\nEND`

#### ADD
- **Description**: Adds a new key-value pair only if the key does not already exist.
- **Syntax**: `add <key> <flags> <exptime> <bytes>`
- **Example**: `add newkey 0 0 5\nworld\nSTORED`

#### REPLACE
- **Description**: Replaces the value of an existing key. If the key does not exist, the operation fails.
- **Syntax**: `replace <key> <flags> <exptime> <bytes>`
- **Example**: `replace mykey 0 60 7\nupdated\nSTORED`

#### DELETE
- **Description**: Deletes a key and its associated value.
- **Syntax**: `delete <key>`
- **Example**: `delete mykey\nDELETED`

#### INCR/DECR
- **Description**: Atomically increments or decrements the value of a key (treated as an integer).
- **Syntax**: `incr <key> <value>` or `decr <key> <value>`
- **Example**: `incr counter 10\n110`

#### APPEND/PREPEND
- **Description**: Appends or prepends data to the value of an existing key.
- **Syntax**: `append <key> <flags> <exptime> <bytes>` or `prepend <key> <flags> <exptime> <bytes>`
- **Example**: `append data 0 0 6\n world\nSTORED`

#### FLUSH_ALL
- **Description**: Invalidates all existing items in all Memcache instances.
- **Syntax**: `flush_all`
- **Example**: `flush_all\nOK`

#### VERSION
- **Description**: Returns the version of the Memcache server.
- **Syntax**: `version`
- **Example**: `version\nVERSION 1.x.x`

#### STATS
- **Description**: Returns a list of statistics for the Memcache server.
- **Syntax**: `stats`
- **Example**: `stats\nSTAT pid 12345\nSTAT uptime 3600\n...\nEND`
```

--------------------------------

### Postgres Wire Protocol - Basic Commands

Source: https://context7.com/tidwall/pogocache/llms.txt

Demonstrates basic commands using the Postgres wire protocol, including SET, GET, and DEL.

```APIDOC
## Postgres Wire Protocol - Basic Commands

### Description
Interact with Pogocache using standard PostgreSQL commands via its wire protocol. This includes setting, retrieving, and deleting key-value pairs.

### Method
Any (via Postgres client)

### Endpoint
`psql -h localhost -p 9401`

### Commands
#### SET
- **Description**: Stores a key-value pair.
- **Syntax**: `SET <key> <value>`
- **Example**: `SET user:1001:first 'Tom'`

#### GET
- **Description**: Retrieves the value associated with a key.
- **Syntax**: `GET <key>`
- **Example**: `GET user:1001:first`

#### DEL
- **Description**: Deletes a key and its associated value.
- **Syntax**: `DEL <key>`
- **Example**: `DEL user:1001:first`

#### MGET
- **Description**: Retrieves multiple values by their keys.
- **Syntax**: `MGET <key1> <key2> ...`
- **Example**: `MGET user:1001:first user:1001:last user:1001:age`

### Response Example (GET)
```
 value
-------
 Tom
(1 row)
```

### Response Example (DEL)
```
DEL 1
```

### Response Example (MGET)
```
     key      |   value
--------------+-----------
 user:1001:first | Tom
 user:1001:last  | Anderson
 user:1001:age   | 37
(3 rows)
```
```

--------------------------------

### Go with pgx (Postgres Client)

Source: https://context7.com/tidwall/pogocache/llms.txt

Example of using the Go pgx library to interact with Pogocache via the Postgres protocol.

```APIDOC
## Go with pgx (Postgres Client)

### Description
This snippet shows how to use the popular `jackc/pgx` Go library to connect to Pogocache and execute commands using parameterized queries.

### Method
Any (via Go program)

### Endpoint
`postgres://127.0.0.1:9401`

### Code Example
```go
package main

import (
    "context"
    "fmt"
    "os"

    "github.com/jackc/pgx/v5"
)

func main() {
    // Connect to Pogocache
    url := "postgres://127.0.0.1:9401"
    conn, err := pgx.Connect(context.Background(), url)
    if err != nil {
        fmt.Fprintf(os.Stderr, "Unable to connect: %v\n", err)
        os.Exit(1)
    }
    defer conn.Close(context.Background())

    // Store with parameterized query
    userID := "1287"
    conn.Exec(context.Background(), "SET user:$1:first $2", userID, "Tom")
    conn.Exec(context.Background(), "SET user:$1:last $2", userID, "Anderson")
    conn.Exec(context.Background(), "SET user:$1:age $2", userID, "37")

    // Retrieve values
    var first, last, age string
    conn.QueryRow(context.Background(), "GET user:$1:first", userID).Scan(&first)
    conn.QueryRow(context.Background(), "GET user:$1:last", userID).Scan(&last)
    conn.QueryRow(context.Background(), "GET user:$1:age", userID).Scan(&age)

    fmt.Println(first, last, age)
    // Output: Tom Anderson 37
}
```
```

--------------------------------

### HTTP API - Get Entry

Source: https://context7.com/tidwall/pogocache/llms.txt

Retrieve a value by its key using an HTTP GET request. Supports authentication.

```APIDOC
## HTTP API - Get Entry

Retrieve a value by key using HTTP GET request.

### Method
GET

### Endpoint
`/[key]`

### Query Parameters
- **auth** (string) - Optional - Authentication password.

### Request Example

#### Get existing key
```bash
curl "http://localhost:9401/mykey"
# Output: my value
```

#### Get non-existent key
```bash
curl "http://localhost:9401/nonexistent"
# Output: Not Found (HTTP 404)
```

#### Get with authentication (query parameter)
```bash
curl "http://localhost:9401/protected?auth=mypassword"
# Output: secure data
```

#### Get with authentication (Authorization header)
```bash
curl -H "Authorization: Bearer mypassword" "http://localhost:9401/protected"
# Output: secure data
```

### Response
#### Success Response (200)
- **value** (string) - The value associated with the key.

#### Error Response (404 Not Found)
- **error** (string) - "Not Found"

### Response Example
```json
{
  "value": "my value"
}
```
```

--------------------------------

### Interact with Pogocache using curl (HTTP)

Source: https://github.com/tidwall/pogocache/blob/main/README.md

Demonstrates storing, retrieving, and deleting entries using the HTTP protocol with curl. It shows basic PUT, GET, and DELETE operations.

```shell
$ curl -X PUT -d "my value" http://localhost:9401/mykey
Stored

$ curl http://localhost:9401/mykey
my value

$ curl -X DELETE http://localhost:9401/mykey
Deleted

```

--------------------------------

### Interact with Pogocache using Memcache Text Protocol

Source: https://context7.com/tidwall/pogocache/llms.txt

Communicate with Pogocache using the Memcache text protocol via telnet or compatible clients. Supports set, get, gets (with CAS), add, replace, delete, incr/decr, append/prepend, flush_all, version, and stats commands.

```bash
# Connect via telnet
telnet localhost 9401

# set <key> <flags> <exptime> <bytes>
set mykey 0 0 5
hello
STORED

# get <key>
get mykey
VALUE mykey 0 5
hello
END

# gets <key> (with CAS)
gets mykey
VALUE mykey 0 5 12345
hello
END

# add (only if not exists)
add newkey 0 0 5
world
STORED

# replace (only if exists)
replace mykey 0 60 7
updated
STORED

# delete
delete mykey
DELETED

# incr/decr
set counter 0 0 3
100
STORED
incr counter 10
110
decrement counter 5
105

# append/prepend
set data 0 0 5
hello
STORED
append data 0 0 6
 world
STORED
get data
VALUE data 0 11
hello world
END

# flush_all
flush_all
OK

# version
version
VERSION 1.x.x

# stats
stats
STAT pid 12345
STAT uptime 3600
...
END

```

--------------------------------

### Pogocache Cache Management Commands

Source: https://context7.com/tidwall/pogocache/llms.txt

This section lists and explains various administrative commands for managing and monitoring the Pogocache server using `valkey-cli`. Commands covered include flushing all data (with options for async and delay), sweeping expired entries (with options for fast and async), purging freed memory, getting database size and server statistics, retrieving the server version, and monitoring all commands in real-time.

```bash
valkey-cli -p 9401

# Flush all data
> FLUSHALL
OK
> FLUSHALL ASYNC
OK
> FLUSHALL DELAY 60
OK

# Sweep expired entries
> SWEEP
OK
> SWEEP FAST
OK
> SWEEP ASYNC
OK

# Purge freed memory back to OS
> PURGE
OK
> PURGE ASYNC
OK

# Get database size
> DBSIZE
(integer) 1000000

# Get server stats
> STATS
...

# Get version
> VERSION
"1.x.x"

# Monitor all commands in real-time
> MONITOR
OK
1234567890.123456 [0 127.0.0.1:12345] "SET" "foo" "bar"
1234567890.234567 [0 127.0.0.1:12345] "GET" "foo"

```

--------------------------------

### Python with psycopg (Postgres Client)

Source: https://context7.com/tidwall/pogocache/llms.txt

Example of using the Python psycopg library to interact with Pogocache via the Postgres protocol.

```APIDOC
## Python with psycopg (Postgres Client)

### Description
This snippet demonstrates how to connect to Pogocache using the `psycopg` Python library and execute commands similar to the Postgres wire protocol.

### Method
Any (via Python script)

### Endpoint
`host=localhost port=9401`

### Code Example
```python
import psycopg

# Connect to Pogocache
conn = psycopg.connect("host=localhost port=9401")

# Insert values
conn.execute("SET user:1391:name Tom")
conn.execute("SET user:1391:last Anderson")
conn.execute("SET user:1391:age 37")
conn.execute("SET user:1391:city %s", ["Phoenix"])

# Retrieve single values
name = conn.execute("GET user:1391:name").fetchone()[0]
print(name)  # Output: Tom

# Retrieve with parameter
city = conn.execute("GET %s", ["user:1391:city"]).fetchone()[0]
print(city)  # Output: Phoenix

# Retrieve multiple values
for row in conn.execute("MGET user:1391:name user:1391:last user:1391:city"):
    print(row[0], row[1])
# Output:
# user:1391:name Tom
# user:1391:last Anderson
# user:1391:city Phoenix

# Binary data handling
conn.execute("SET binary_data %s", [b'\x00\x01\x02hello\xff'])
conn.execute("::bytea")  # Switch to binary mode
binary = conn.execute("GET binary_data").fetchone()[0]
print(binary)  # Output: b'\x00\x01\x02hello\xff'
conn.execute("::text")   # Switch back to text mode

conn.close()
```
```

--------------------------------

### STATS - Get server statistics

Source: https://context7.com/tidwall/pogocache/llms.txt

Retrieves server statistics such as process ID and uptime.

```APIDOC
## STATS /api/stats

### Description
Retrieves server statistics including the process ID and uptime.

### Method
GET

### Endpoint
/api/stats

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **pid** (string) - The process ID of the server.
- **uptime** (string) - The uptime of the server in seconds.

#### Response Example
```json
{
  "pid": "12345",
  "uptime": "3600"
}
```
```

--------------------------------

### Interact with Pogocache using Postgres Wire Protocol via psql

Source: https://context7.com/tidwall/pogocache/llms.txt

Connect to Pogocache using the psql client and execute commands similar to RESP. Supports setting, getting, deleting, and multi-get operations for key-value pairs.

```bash
# Connect using psql
psql -h localhost -p 9401

# Store values
=> SET user:1001:first 'Tom';
=> SET user:1001:last 'Anderson';
=> SET user:1001:age 37;

# Retrieve values
=> GET user:1001:first;
 value
-------
 Tom
(1 row)

# Delete values
=> DEL user:1001:first;
DEL 1

# Multiple key retrieval
=> MGET user:1001:first user:1001:last user:1001:age;
     key      |   value
--------------+-----------
 user:1001:first | Tom
 user:1001:last  | Anderson
 user:1001:age   | 37
(3 rows)

```

--------------------------------

### Configure TLS/HTTPS for Pogocache Server

Source: https://context7.com/tidwall/pogocache/llms.txt

This section details how to set up TLS/HTTPS encryption for secure communication with the Pogocache server. It includes steps for generating necessary certificates (CA, server key, CSR, and signed certificate) using OpenSSL and then starting the Pogocache server with TLS enabled, disabling the plain-text port. It also shows how to connect securely using `valkey-cli` and `curl`.

```bash
# Generate CA and server certificates
openssl req -x509 -newkey rsa:4096 -sha256 -days 365 -nodes \
  -keyout ca.key -out ca.crt -subj "/CN=My Pogocache CA"

openssl req -newkey rsa:4096 -nodes \
  -keyout pogocache.key -out pogocache.csr -subj "/CN=localhost"

openssl x509 -req -sha256 -days 365 \
  -in pogocache.csr -CA ca.crt -CAkey ca.key \
  -CAcreateserial -out pogocache.crt

# Start Pogocache with TLS (disable plain-text port)
./pogocache -p 0 \
   --tlsport 9401 \
   --tlscert pogocache.crt \
   --tlskey pogocache.key \
   --tlscacert ca.crt

# Connect with TLS using valkey-cli
valkey-cli --tls \
    --cert pogocache.crt \
    --key pogocache.key \
    --cacert ca.crt \
    -h localhost -p 9401

# Connect with TLS using curl (HTTPS)
curl "https://localhost:9401/mykey" \
  --cert pogocache.crt \
  --key pogocache.key \
  --cacert ca.crt

```

--------------------------------

### HTTP Interface

Source: https://github.com/tidwall/pogocache/blob/main/README.md

Pogocache supports HTTP methods PUT, GET, and DELETE for storing, retrieving, and deleting entries. This section details the endpoints and parameters for these operations.

```APIDOC
## HTTP Interface

### Description

Pogocache uses HTTP methods PUT, GET, DELETE to store, retrieve, and delete entries.

### Store Entry

#### Method
PUT

#### Endpoint
`/:key`

#### Parameters

##### Query Parameters

- **key** (string) - Required - Key of entry
- **ttl** (integer) - Optional - Time to live in seconds
- **nx** (boolean) - Optional - Only store if it does not already exist.
- **xx** (boolean) - Optional - Only store if it already exists.
- **auth** (string) - Optional - Auth password

#### Request Body

The value to be stored for the given key.

#### Response

- `200 OK` with the response "Stored"

#### Request Example

```sh
curl -X PUT -d "my value" "http://localhost:9401/mykey"
curl -X PUT -d "my value" "http://localhost:9401/mykey?ttl=15"
```

### Get Entry

#### Method
GET

#### Endpoint
`/:key`

#### Parameters

##### Query Parameters

- **key** (string) - Required - Key of entry
- **auth** (string) - Optional - Auth password

#### Response

- `200 OK` and the value in the body
- `404 Not Found` and the value "Not Found"

### Delete Entry

#### Method
DELETE

#### Endpoint
`/:key`

#### Parameters

##### Query Parameters

- **key** (string) - Required - Key of entry
- **auth** (string) - Optional - Auth password

#### Response

- `200 OK` with the response "Deleted"
- `404 Not Found` and the value "Not Found"

#### Request Example

```sh
curl -X DELETE http://localhost:9401/mykey
```
```

--------------------------------

### Pogocache Program Options Help

Source: https://github.com/tidwall/pogocache/blob/main/README.md

Displays the help menu for Pogocache, listing all available command-line options for configuration.

```shell
./pogocache --help

```

--------------------------------

### Run Pogocache with Docker

Source: https://github.com/tidwall/pogocache/blob/main/README.md

Launches the Pogocache server using the latest Docker image.

```shell
docker run pogocache/pogocache

```

--------------------------------

### Pogocache Server Options

Source: https://github.com/tidwall/pogocache/blob/main/README.md

This section details the various command-line options available for running the Pogocache server, including basic, additional, security, and advanced configurations.

```APIDOC
## Pogocache Server Options

### Description

This section details the various command-line options available for running the Pogocache server, including basic, additional, security, and advanced configurations.

### Running the Server

To start the server on the default host (localhost) and port (9401):
```bash
./pogocache
```

To specify a listening host:
```bash
./pogocache -h 172.30.2.84
```

To run using Docker:
```bash
docker run pogocache/pogocache
```

### Program Options

#### Basic Options

- **-h** (string) - Listening host. Default: `127.0.0.1`
- **-p** (integer) - Listening port. Default: `9401`
- **-s** (string) - Unix socket file. Default: `none`
- **-v, -vv, -vvv** - Verbose logging level.

#### Additional Options

- **--threads** (integer) - Number of threads. Default: `32`
- **--maxmemory** (value) - Set max memory usage. Default: `80%`
- **--evict** (yes/no) - Evict keys at maxmemory. Default: `yes`
- **--persist** (path) - Persistence file. Default: `none`
- **--maxconns** (integer) - Maximum connections. Default: `1024`

#### Security Options

- **--auth** (string) - Auth token or password. Default: `none`
- **--tlsport** (integer) - Enable TLS on port. Default: `none`
- **--tlscert** (file) - TLS certificate file. Default: `none`
- **--tlskey** (file) - TLS key file. Default: `none`
- **--tlscacert** (file) - TLS CA certificate file. Default: `none`

#### Advanced Options

- **--shards** (integer) - Number of shards. Default: `4096`
- **--backlog** (integer) - Accept backlog. Default: `1024`
- **--queuesize** (integer) - Event queue size. Default: `128`
- **--reuseport** (yes/no) - Reuseport for TCP. Default: `no`
- **--tcpnodelay** (yes/no) - Disable Nagle's algorithm. Default: `yes`
- **--quickack** (yes/no) - Use quickack (Linux). Default: `no`
- **--uring** (yes/no) - Use io_uring (Linux). Default: `yes`
- **--loadfactor** (percent) - Hashmap load factor. Default: `75`
- **--autosweep** (yes/no) - Automatic eviction sweeps. Default: `yes`
- **--keysixpack** (yes/no) - Sixpack compress keys. Default: `yes`
- **--cas** (yes/no) - Use compare and swap. Default: `no`
```

--------------------------------

### Connect to Pogocache with Auth Password using valkey-cli

Source: https://github.com/tidwall/pogocache/blob/main/README.md

Connects to Pogocache using valkey-cli, providing the authentication password. The password can be supplied using the '-a' flag.

```shell
valkey-cli -p 9401 -a mypass
```

--------------------------------

### Connect to Pogocache with TLS using valkey-cli

Source: https://github.com/tidwall/pogocache/blob/main/README.md

Connects to a Pogocache server using the valkey-cli with TLS enabled. Requires specifying the client certificate, key, and CA certificate, along with the host and TLS port.

```shell
valkey-cli --tls \
    --cert pogocache.crt \
    --key pogocache.key \
    --cacert ca.crt \
    -h localhost -p 9401
```

--------------------------------

### Embed Pogocache Library in C Application

Source: https://github.com/tidwall/pogocache/blob/main/README.md

Demonstrates how to use the Pogocache C library within a standalone C program. It includes creating a cache instance, storing values, and retrieving them using a callback function.

```c
// prog.c
#include <stdio.h>
#include "pogocache.h"

static void load_callback(int shard, int64_t time, const void *key,
    size_t keylen, const void *value, size_t valuelen, int64_t expires, 
    uint32_t flags, uint64_t cas, struct pogocache_update **update, 
    void *udata)
{
    printf("%.*s\n", (int)valuelen, (char*)value);
}

int main(void) {
    // Create a Pogocache instance
    struct pogocache *cache = pogocache_new(0);

    // Store some values
    pogocache_store(cache, "user:1391:name", 14, "Tom", 3, 0);
    pogocache_store(cache, "user:1391:last", 14, "Anderson", 8, 0);
    pogocache_store(cache, "user:1391:age", 13, "37", 2, 0);

    // Read the values back
    struct pogocache_load_opts lopts = { .entry = load_callback };
    pogocache_load(cache, "user:1391:name", 14, &lopts);
    pogocache_load(cache, "user:1391:last", 14, &lopts);
    pogocache_load(cache, "user:1391:age", 13, &lopts);
    return 0;
}
// Tom
// Anderson
// 37

```

--------------------------------

### Compile and Run Embedded Pogocache C Application

Source: https://github.com/tidwall/pogocache/blob/main/README.md

Compiles a C program that uses the Pogocache library and then runs the executable. This assumes the pogocache.c file is available in the same directory.

```shell
cc prog.c pogocache.c
./a.out
```

--------------------------------

### Interact with Pogocache using Go with pgx

Source: https://context7.com/tidwall/pogocache/llms.txt

Utilize the jackc/pgx library in Go to connect to Pogocache and perform key-value operations using parameterized queries. Supports setting and retrieving values.

```go
package main

import (
    "context"
    "fmt"
    "os"

    "github.com/jackc/pgx/v5"
)

func main() {
    // Connect to Pogocache
    url := "postgres://127.0.0.1:9401"
    conn, err := pgx.Connect(context.Background(), url)
    if err != nil {
        fmt.Fprintf(os.Stderr, "Unable to connect: %v\n", err)
        os.Exit(1)
    }
    defer conn.Close(context.Background())

    // Store with parameterized query
    userID := "1287"
    conn.Exec(context.Background(), "SET user:$1:first $2", userID, "Tom")
    conn.Exec(context.Background(), "SET user:$1:last $2", userID, "Anderson")
    conn.Exec(context.Background(), "SET user:$1:age $2", userID, "37")

    // Retrieve values
    var first, last, age string
    conn.QueryRow(context.Background(), "GET user:$1:first", userID).Scan(&first)
    conn.QueryRow(context.Background(), "GET user:$1:last", userID).Scan(&last)
    conn.QueryRow(context.Background(), "GET user:$1:age", userID).Scan(&age)

    fmt.Println(first, last, age)
    // Output: Tom Anderson 37
}

```

--------------------------------

### Pogocache HTTP API - Store Entry

Source: https://context7.com/tidwall/pogocache/llms.txt

Shows how to store key-value pairs using HTTP PUT requests. Covers basic storage, setting TTL, conditional storage (NX/XX), and authentication.

```bash
# Basic store
curl -X PUT -d "my value" "http://localhost:9401/mykey"
# Output: Stored

# Store with 15 second TTL
curl -X PUT -d "temporary data" "http://localhost:9401/session:123?ttl=15"
# Output: Stored

# Store only if key does not exist (NX)
curl -X PUT -d "first value" "http://localhost:9401/unique-key?nx=1"
# Output: Stored (or 404 Not Found if exists)

# Store only if key already exists (XX)
curl -X PUT -d "updated value" "http://localhost:9401/existing-key?xx=1"
# Output: Stored (or 404 Not Found if not exists)

# Store with authentication
curl -X PUT -d "secure data" "http://localhost:9401/protected?auth=mypassword"
# Output: Stored
```

--------------------------------

### Embed Pogocache C Library API

Source: https://context7.com/tidwall/pogocache/llms.txt

Demonstrates how to integrate and use the Pogocache C library directly within C applications. It covers creating a cache instance, storing entries with and without TTL, loading entries, deleting entries, retrieving statistics, iterating through all entries, sweeping expired entries, clearing the cache, and freeing resources. This approach offers maximum performance by avoiding network overhead.

```c
// prog.c
#include <stdio.h>
#include "pogocache.h"

// Callback for reading entries
static void load_callback(int shard, int64_t time, const void *key,
    size_t keylen, const void *value, size_t valuelen, int64_t expires,
    uint32_t flags, uint64_t cas, struct pogocache_update **update,
    void *udata)
{
    printf("Key: %.*s = %.*s\n", (int)keylen, (char*)key,
           (int)valuelen, (char*)value);
}

int main(void) {
    // Create cache with custom options
    struct pogocache_opts opts = {
        .nshards = 1024,
        .loadfactor = 75,
        .usecas = false,
    };
    struct pogocache *cache = pogocache_new(&opts);
    if (!cache) {
        perror("pogocache_new");
        return 1;
    }

    // Store entries (with optional TTL)
    struct pogocache_store_opts sopts = {
        .time = pogocache_now(),
        .ttl = 60 * POGOCACHE_SECOND,  // 60 second TTL
    };
    pogocache_store(cache, "user:1:name", 11, "Alice", 5, &sopts);
    pogocache_store(cache, "user:1:email", 12, "alice@example.com", 17, &sopts);

    // Store without TTL
    pogocache_store(cache, "config:version", 14, "1.0.0", 5, NULL);

    // Load entries
    struct pogocache_load_opts lopts = {
        .time = pogocache_now(),
        .entry = load_callback,
    };
    int status = pogocache_load(cache, "user:1:name", 11, &lopts);
    if (status == POGOCACHE_FOUND) {
        printf("Entry found\n");
    } else if (status == POGOCACHE_NOTFOUND) {
        printf("Entry not found\n");
    }

    // Delete entry
    struct pogocache_delete_opts dopts = { .time = pogocache_now() };
    pogocache_delete(cache, "user:1:email", 12, &dopts);

    // Get statistics
    size_t count = pogocache_count(cache, NULL);
    size_t size = pogocache_size(cache, NULL);
    printf("Entries: %zu, Size: %zu bytes\n", count, size);

    // Iterate all entries
    struct pogocache_iter_opts iopts = {
        .time = pogocache_now(),
        .entry = iter_callback,  // returns POGOCACHE_ITER_CONTINUE or STOP
    };
    pogocache_iter(cache, &iopts);

    // Sweep expired entries
    size_t swept, kept;
    pogocache_sweep(cache, &swept, &kept, NULL);
    printf("Swept: %zu, Kept: %zu\n", swept, kept);

    // Clear all entries
    pogocache_clear(cache, NULL);

    // Cleanup
    pogocache_free(cache);
    return 0;
}
// Compile: cc prog.c pogocache.c -o prog
// Run: ./prog

```