README
¶
Quark ORM Examples
This directory contains real-world examples of Quark ORM usage with different database engines.
Prerequisites
To run the PostgreSQL and MySQL examples, you need to have the test databases running via Docker:
# From the project root
docker compose -f docker-compose.test.yml up -d
Running Examples
1. SQLite Example
The SQLite example is self-contained and creates a local example.db file.
go run ./examples/sqlite/main.go
2. PostgreSQL (Multi-Tenant RLS)
Demonstrates Row Level Security (RLS) isolation and automatic tenant ID injection.
go run ./examples/postgres/main.go
3. MySQL (Transactions & Streaming)
Demonstrates transactional operations and memory-efficient result streaming using Iter().
go run ./examples/mysql/main.go
4. MSSQL (Pagination & Builders)
Demonstrates pagination using the OFFSET/FETCH syntax required by SQL Server.
go run ./examples/mssql/main.go
5. Oracle (Godror Support)
Demonstrates Godror setup. Note that the Godror driver requires CGO enabled for Oracle compilation.
go run ./examples/oracle/main.go
6. Sharding (ShardRouter)
Self-contained (no Docker): partitions data across two SQLite shards by shard
key via ShardRouter, proving per-shard disjoint storage and the keyless-query
rejection. See the Sharding guide.
go run ./examples/sharding/main.go
Cleaning Up
docker compose -f docker-compose.test.yml down
Directories
¶
| Path | Synopsis |
|---|---|
|
Command migrations is a minimal example of using the `quarkmigrate` package to wire a plan/verify/apply CLI workflow for a Quark-managed schema.
|
Command migrations is a minimal example of using the `quarkmigrate` package to wire a plan/verify/apply CLI workflow for a Quark-managed schema. |
|
Sharding example (F6-7, ADR-0016).
|
Sharding example (F6-7, ADR-0016). |
|
superapp
|
|
|
cli
Package cli es el área de cobertura del BINARIO `cmd/quark` dentro del arnés de aceptación (superapp S9).
|
Package cli es el área de cobertura del BINARIO `cmd/quark` dentro del arnés de aceptación (superapp S9). |
|
cmd/gen-apisurface
command
Command gen-apisurface genera apisurface.json: el DENOMINADOR del gate de cobertura del superapp — todo símbolo exportado de la superficie pública de Quark (el paquete raíz + los subpaquetes públicos).
|
Command gen-apisurface genera apisurface.json: el DENOMINADOR del gate de cobertura del superapp — todo símbolo exportado de la superficie pública de Quark (el paquete raíz + los subpaquetes públicos). |
|
cmd/workload
command
Command workload ejerce el dominio de la superapp a alto volumen y emite un informe ejecutivo, métricas y el log de la aplicación, para contrastar cómo corre Quark con datos relacionados, consultas, transacciones y caché.
|
Command workload ejerce el dominio de la superapp a alto volumen y emite un informe ejecutivo, métricas y el log de la aplicación, para contrastar cómo corre Quark con datos relacionados, consultas, transacciones y caché. |
|
control
Package control implementa la maquinaria de cobertura, paridad y gating de la superapp de aceptación: el manifiesto de superficie pública, el reconciliador invocado-vs-manifiesto, la matriz de capacidad por motor y el reporte/gate.
|
Package control implementa la maquinaria de cobertura, paridad y gating de la superapp de aceptación: el manifiesto de superficie pública, el reconciliador invocado-vs-manifiesto, la matriz de capacidad por motor y el reporte/gate. |
|
domain
Package domain define el modelo de la superapp.
|
Package domain define el modelo de la superapp. |
|
engine
Package engine arranca y teardownea los 6 motores para el arnés del superapp, y verifica que no haya fugas (goroutines, conexiones del pool) tras cerrar.
|
Package engine arranca y teardownea los 6 motores para el arnés del superapp, y verifica que no haya fugas (goroutines, conexiones del pool) tras cerrar. |
|
exercise
Package exercise ejerce la superficie pública de Quark contra cada motor, marcando los símbolos que invoca (para el gate de cobertura del manifiesto) y asertando el resultado funcional.
|
Package exercise ejerce la superficie pública de Quark contra cada motor, marcando los símbolos que invoca (para el gate de cobertura del manifiesto) y asertando el resultado funcional. |
|
recorder
Package recorder instrumenta un Client de Quark para la superapp de aceptación: observa cada statement SQL y lo atribuye al símbolo de la API pública que lo originó, alimentando dos mecanismos del arnés:
|
Package recorder instrumenta un Client de Quark para la superapp de aceptación: observa cada statement SQL y lo atribuye al símbolo de la API pública que lo originó, alimentando dos mecanismos del arnés: |
|
workload
Package workload ejerce el dominio de la superapp a ALTO VOLUMEN —datos relacionados, consultas, transacciones y caché— y recolecta métricas para un informe ejecutivo.
|
Package workload ejerce el dominio de la superapp a ALTO VOLUMEN —datos relacionados, consultas, transacciones y caché— y recolecta métricas para un informe ejecutivo. |
|
Example: quark tenant install-rls-policies — minimal embedding of the quarktenant library into a user-owned binary that can be run from CI / Makefile to install PostgreSQL row-level security policies for every model registered on the quark.Client.
|
Example: quark tenant install-rls-policies — minimal embedding of the quarktenant library into a user-owned binary that can be run from CI / Makefile to install PostgreSQL row-level security policies for every model registered on the quark.Client. |
Click to show internal directories.
Click to hide internal directories.