proxysql/doc/agents/project-conventions.md

# ProxySQL Project Conventions for Agents

## Build System

```bash
make build_deps -j4    # Build dependencies (first time only)
make build_lib -j4     # Build libproxysql.a
make build_tap_tests   # Build all tests (includes unit tests)
make -j4               # Full build (deps + lib + binary)
```

Always verify `make build_lib -j4` compiles successfully before submitting changes to `lib/` or `include/`.

## Directory Layout

| Directory | Purpose | When to modify |
|-----------|---------|---------------|
| `include/` | All headers (.h/.hpp) | When adding new declarations |
| `lib/` | Core library sources → compiled into `libproxysql.a` | When adding/modifying implementations |
| `src/` | Entry point (`main.cpp`) and daemon code | Rarely — avoid unless necessary |
| `test/tap/tests/unit/` | Unit tests (no infrastructure needed) | When adding unit tests |
| `test/tap/tests/` | E2E TAP tests (need running ProxySQL + backends) | When adding integration tests |
| `test/tap/test_helpers/` | Unit test harness (`test_globals`, `test_init`) | When extending test infrastructure |
| `doc/` | Documentation | When documenting features |

## Unit Test Conventions

### File placement
- Unit tests go in `test/tap/tests/unit/`, NOT in `test/tap/tests/`
- File naming: `<descriptive_name>_unit-t.cpp` or `<descriptive_name>-t.cpp`

### Test harness (MUST use)
Every unit test MUST use the existing harness:

```cpp
#include "tap.h"
#include "test_globals.h"
#include "test_init.h"

#include "proxysql.h"
// ... other headers for types you need

int main() {
    plan(<number_of_tests>);
    test_init_minimal();   // Always call first

    // ... test functions with ok(), is(), etc.

    test_cleanup_minimal(); // Always call last
    return exit_status();
}
```

The harness provides:
- All `Glo*` global stubs (defined in `test_globals.cpp`)
- TAP noise symbols (`noise_failures`, `stop_noise_tools`, etc.)
- Component init helpers: `test_init_auth()`, `test_init_query_cache()`, `test_init_query_processor()`
- Cleanup functions for each

### Makefile registration
Edit `test/tap/tests/unit/Makefile`:
1. Append test name to `UNIT_TESTS :=` line
2. Add build rule:
```makefile
my_test-t: my_test-t.cpp $(TEST_HELPERS_OBJ) $(LIBPROXYSQLAR)
	$(CXX) $< $(TEST_HELPERS_OBJ) $(IDIRS) $(LDIRS) $(OPT) \
		$(LIBPROXYSQLAR_FULL) $(STATIC_LIBS) $(MYLIBS) \
		$(ALLOW_MULTI_DEF) -o $@
```

### What the unit test Makefile does
- Compiles `tap.o` directly from source (no `cpp-dotenv` dependency)
- Links test binary against `libproxysql.a` + `test_globals.o` + `test_init.o`
- This means tests call the REAL production functions, not copies

### Reference files
- `test/tap/tests/unit/connection_pool_unit-t.cpp` — good example of a unit test
- `test/tap/tests/unit/rule_matching_unit-t.cpp` — good example with regex testing
- `test/tap/test_helpers/test_globals.cpp` — what symbols are already stubbed
- `include/ConnectionPoolDecision.h` — good example of a standalone extracted header

## Header Conventions

### Include guards
Use `#ifndef HEADER_NAME_H` / `#define HEADER_NAME_H` / `#endif`.

### Avoiding circular dependencies
The ProxySQL include chain has circular dependencies:
```
proxysql.h → proxysql_structs.h → proxysql_glovars.hpp
cpp.h → MySQL_Thread.h → MySQL_Session.h → proxysql.h (circular)
cpp.h → MySQL_HostGroups_Manager.h → Base_HostGroups_Manager.h → proxysql.h (circular)
```

When extracting functions from tightly-coupled classes, create a **standalone header** in `include/` with its own include guard and no ProxySQL dependencies. Example: `include/ConnectionPoolDecision.h`.

### Naming
- Class headers: `PascalCase` matching the class name
- Standalone function headers: `PascalCase` describing the feature

## Git Workflow

### Branch model
- `v3.0` — main stable branch (DO NOT target PRs here for unit test work)
- `v3.0-5473` — unit test feature branch (target PRs here for test-related changes)
- Feature branches: `v3.0-<issue_number>` (e.g., `v3.0-5491`)

### Creating a feature branch
```bash
git checkout -b v3.0-<issue_number> v3.0-5473
```

### Incorporating upstream changes
Use `git rebase`, NOT `git merge`:
```bash
git fetch origin v3.0-5473
git rebase origin/v3.0-5473
# Resolve conflicts if any
git push --force-with-lease
```

### Commit messages
- Descriptive subject line (what changed and why)
- Reference issue numbers: `(#5491)`
- Separate production code changes from test changes in different commits

## Coding Conventions

- C++17 required
- Class names: `PascalCase` with protocol prefixes (`MySQL_`, `PgSQL_`, `ProxySQL_`)
- Member variables: `snake_case`
- Constants/macros: `UPPER_SNAKE_CASE`
- Doxygen documentation on all public functions: `@brief`, `@param`, `@return`
- `(char *)` casts on string literals are acceptable (codebase convention)

## Dual Protocol

ProxySQL supports both MySQL and PostgreSQL. When modifying one protocol's code, check if the same change is needed for the other:

| MySQL | PostgreSQL |
|-------|-----------|
| `MySQL_Session` | `PgSQL_Session` |
| `MySQL_Thread` | `PgSQL_Thread` |
| `MySQL_HostGroups_Manager` | `PgSQL_HostGroups_Manager` |
| `MySQL_Monitor` | `PgSQL_Monitor` |
| `MySQL_Query_Processor` | `PgSQL_Query_Processor` |
| `MySrvConnList` | `PgSQL_SrvConnList` |

Some components share a template base (`Base_Session`, `Base_HostGroups_Manager`, `Query_Processor<T>`). Changes to the template cover both protocols.