diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 0000000..4823f55 --- /dev/null +++ b/.github/workflows/ci.yml @@ -0,0 +1,43 @@ +name: CI Database + +on: + push: + branches: [ main ] + pull_request: + branches: [ main ] + +jobs: + test: + runs-on: ubuntu-latest + steps: + - name: Checkout repository + uses: actions/checkout@v5 + + - name: Set up Go + uses: actions/setup-go@v6 + with: + go-version: stable + + - name: Run tests with coverage + run: | + go test ./... -covermode=atomic -coverprofile=coverage.out + + - name: Show coverage % + run: | + echo "Total coverage:" + go tool cover -func=coverage.out | grep total + + - name: Enforce minimum 80% coverage + run: | + pct=$(go tool cover -func=coverage.out | grep total | awk '{print substr($3, 1, length($3)-1)}') + echo "Coverage: $pct%" + awk -v p="$pct" 'BEGIN {exit !(p >= 80)}' + + - name: Upload coverage report + if: success() + uses: codecov/codecov-action@v5 + with: + files: ./coverage.out + flags: common + token: ${{ secrets.CODECOV_TOKEN }} + fail_ci_if_error: true diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..68665e6 --- /dev/null +++ b/.gitignore @@ -0,0 +1,60 @@ +# IDEs +.vscode/ +.idea/ +*.iml +*.sublime-project +*.sublime-workspace + +# Editor artifacts +*~ +*.swp +*.swo +*.bak +*.tmp + +# Dependency directories (if vendored) +vendor/ + +# Git metadata +*.orig + +# OS-specific +.DS_Store +.AppleDouble +.LSOverride +Icon? +._* +.Spotlight-V100 +.Trashes +Thumbs.db +ehthumbs.db +Desktop.ini + +# Binaries for programs and plugins +bin/ +*.exe +*.exe~ +*.dll +*.so +*.dylib +*.test +coverage.* +*.coverprofile + +# Dependency directories (remove the comment below to include it) +# vendor/ + +# Logs +logs/ +*.log +*.out + +# local +/docs/CHANGELOG.md +/docs/releases/ +docs/_site/ +docs/public/ +public/ + +# env file +.env diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..dcc63e0 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,61 @@ +# Changelog + +All notable changes to this project will be documented in this file. + +The format is based on [Keep a Changelog](https://keepachangelog.com/) +and this project adheres to [Semantic Versioning](https://semver.org/). + +--- + +## [v1.0.0] - 2025-09-19 + +### Added + +- **Builders** + - `SelectBuilder` with structured condition handling and consistent `Build() (string, []any, error)` signature. + - Planned: `InsertBuilder`, `UpdateBuilder`, `DeleteBuilder`, and `UpsertBuilder` (to include full clause ordering + and validation rules in future versions). + - Support for conditions: + - `Where`, `WhereAnd`, and `WhereOr` with validation and normalization. + - Support for grouping and having clauses: + - `GroupBy`, `ThenGroupBy`. + - `Having`, `AndHaving`, `OrHaving`. + - Support for ordering and pagination: + - `OrderBy`, `ThenOrderBy`. + - Pagination with `Take` and `Skip`. +- **Tokens** + - `Condition`: semantic-aware constructor with validation and dialect-aware rendering. + - `Field`: deterministic constructors (`New`, `NewWithTable`), aliased support, encapsulated token type. + - `Table`: constructors and helpers to define tables, aliases, and raw inputs with validation. + - `Join`: support for INNER, LEFT, RIGHT, CROSS, and NATURAL joins. +- **Contracts** + - `BaseToken`: core identity and validation for all tokens. + - `Errorable`: tokens can mark themselves errored after construction. + - `Kindable`, `Identifiable`, `Aliasable`: unify token identity handling. + - `Rawable`, `Renderable`, `Stringable`, `Validable`: standardized behaviors for token rendering, debugging, and + validation. + - `Token`: aggregate contract for ownership and auditability. + - Currently implemented by **Field**, **Table**, **Join**, and **Condition** tokens. + - Future adoption planned for **Having**, **GroupBy**, and **OrderBy** tokens. +- **Dialect Support** + - Introduced **generic dialect** (implemented) with `?` placeholder strategy. + - Other dialects are **planned** for future releases, including Postgres, MySQL, MariaDB, SQLite, MSSQL, Oracle, + DB2, Firebird, Informix, CockroachDB, TiDB, HANA, Snowflake, Redshift, Teradata, and ClickHouse. + +### Changed + +- Renamed `Column` โ†’ `Field`. +- `SelectBuilder` constructor renamed from `NewSelect` โ†’ `New`. +- Refactored `Field` into dedicated subpackage `db/token/field`. +- Normalized resolver helpers (`ResolveExpression`, `ResolveCondition`, `IsValidSlice`). + +### Documentation + +- Comprehensive `doc.go` and `README.md` across builders, tokens, and contracts. +- Dialect guide and developer best practices. +- Runnable examples in `example_test.go` for every major component. + +### Tests & Coverage + +- 100% unit test coverage across builders, tokens, dialects, and helpers. +- Extensive diagnostics for invalid fields, nil receivers, and missing sources. diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..0131d97 --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2025 Isidro Lopez + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/README.md b/README.md index 75bde29..072da92 100644 --- a/README.md +++ b/README.md @@ -8,16 +8,16 @@ Entiqon/db is a modular SQL query engine for Go, designed for composable, type-s ## ๐Ÿ›  Capabilities -| Module | Feature | Purpose | Status | -|------------------------|------------------------|----------------------------------------------------------------------------|-------------| -| [builder](./builder) | [insert](./builder) | High-level SQL builder for INSERT statements | ๐Ÿ“ Planned | -| | [select](./builder) | High-level SQL builder for SELECT statements (stable and production-ready) | โœ… Stable | -| | [update](./builder) | High-level SQL builder for UPDATE statements | ๐Ÿ“ Planned | -| | [delete](./builder) | High-level SQL builder for DELETE statements | ๐Ÿ“ Planned | -| | [upsert](./builder) | High-level SQL builder for UPSERT / MERGE statements | ๐Ÿ“ Planned | -| [token](./token) | [field](./token/field) | Dialect-agnostic representation of SQL fields/expressions | โœ… Stable | +| Module | Feature | Purpose | Status | +|------------------------|------------------------|----------------------------------------------------------------------------|------------| +| [builder](./builder) | [insert](./builder) | High-level SQL builder for INSERT statements | ๐Ÿ“ Planned | +| | [select](./builder) | High-level SQL builder for SELECT statements (stable and production-ready) | โœ… Stable | +| | [update](./builder) | High-level SQL builder for UPDATE statements | ๐Ÿ“ Planned | +| | [delete](./builder) | High-level SQL builder for DELETE statements | ๐Ÿ“ Planned | +| | [upsert](./builder) | High-level SQL builder for UPSERT / MERGE statements | ๐Ÿ“ Planned | +| [token](./token) | [field](./token/field) | Dialect-agnostic representation of SQL fields/expressions | โœ… Stable | | | [table](./token/table) | Dialect-agnostic representation of SQL tables/sources | โœ… Stable | -| | [join](./token/join) | Dialect-agnostic representation of SQL join clauses | ๐Ÿšง Ongoing | +| | [join](./token/join) | Dialect-agnostic representation of SQL join clauses | ๐Ÿšง Ongoing | | [contract](./contract) | BaseToken | Common base for tokens (shared identity, ownership, validity checks) | โœ… Stable | | | Clonable | Ensures semantic cloning of tokens without mutation | โœ… Stable | | | Debuggable | Provides developer-facing diagnostics (`Debug()`) | โœ… Stable | diff --git a/go.mod b/go.mod index 25ee473..26150b9 100644 --- a/go.mod +++ b/go.mod @@ -1,3 +1,5 @@ module github.com/entiqon/db go 1.24.2 + +require github.com/entiqon/common v1.0.0 diff --git a/go.sum b/go.sum new file mode 100644 index 0000000..2f09d9a --- /dev/null +++ b/go.sum @@ -0,0 +1,2 @@ +github.com/entiqon/common v1.0.0 h1:qoEJbcD1cjqxvlsMC6ow6CQUDMDO7wL3+a9H7CAFCQs= +github.com/entiqon/common v1.0.0/go.mod h1:5AbyVPtxT/1impg3ljBvHd3y9/LTI63andE3CcMtHpk= diff --git a/releases/release-notes-v1.0.0.md b/releases/release-notes-v1.0.0.md new file mode 100644 index 0000000..f321375 --- /dev/null +++ b/releases/release-notes-v1.0.0.md @@ -0,0 +1,66 @@ +# Release Notes โ€” db v1.0.0 (2025-09-19) + +This is the **first stable release** of the `entiqon/db` package. +It provides a robust SQL builder and token framework with strict validation, test coverage, and extensibility. + +--- + +## โœจ Added + +### Builders +- **SelectBuilder**: + - Structured condition handling with consistent `Build() (string, []any, error)` signature. + - Supports: + - Conditions: `Where`, `WhereAnd`, `WhereOr`. + - Grouping: `GroupBy`, `ThenGroupBy`. + - Having: `Having`, `AndHaving`, `OrHaving`. + - Ordering: `OrderBy`, `ThenOrderBy`. + - Pagination: `Take`, `Skip`. +- **Planned**: `InsertBuilder`, `UpdateBuilder`, `DeleteBuilder`, and `UpsertBuilder` (to be included in future versions). + +### Tokens +- **Condition**: semantic-aware constructor with validation and dialect-aware rendering. +- **Field**: deterministic constructors (`New`, `NewWithTable`), aliased support, encapsulated token type. +- **Table**: constructors and helpers to define tables, aliases, and raw inputs with validation. +- **Join**: support for INNER, LEFT, RIGHT, CROSS, and NATURAL joins. + +### Contracts +- **BaseToken**: core identity and validation for all tokens. +- **Errorable**: tokens can mark themselves errored after construction. +- **Kindable**, **Identifiable**, **Aliasable**: unify token identity handling. +- **Token**: aggregate contract for ownership and auditability. + - Currently implemented by Field, Table, Join, and Condition tokens. + - Future adoption planned for Having, GroupBy, and OrderBy tokens. +- **Rawable**, **Renderable**, **Stringable**, **Validable**: standardized behaviors for token rendering, debugging, and validation. + +### Dialect Support +- Introduced **generic dialect** (implemented) using `?` placeholder strategy. +- Other dialects are planned for future releases, including Postgres, MySQL, MariaDB, SQLite, MSSQL, Oracle, DB2, Firebird, Informix, CockroachDB, TiDB, HANA, Snowflake, Redshift, Teradata, and ClickHouse. + +--- + +## ๐Ÿ”„ Changed +- Renamed `Column` โ†’ `Field`. +- `SelectBuilder` constructor renamed from `NewSelect` โ†’ `New`. +- Refactored Field into dedicated subpackage `db/token/field`. +- Normalized resolver helpers (`ResolveExpression`, `ResolveCondition`, `IsValidSlice`). + +--- + +## ๐Ÿ“š Documentation +- Comprehensive `doc.go` and `README.md` across builders, tokens, and contracts. +- Dialect guide and developer best practices. +- Runnable examples in `example_test.go` for every major component. + +--- + +## ๐Ÿงช Tests & Coverage +- 100% unit test coverage across builders, tokens, dialects, and helpers. +- Extensive diagnostics for invalid fields, nil receivers, and missing sources. + +--- + +## ๐Ÿ“ฆ Availability +```bash +go get github.com/entiqon/db@v1.0.0 +```