@an5/adapters 0.2.5 → 0.2.9

package/dotnet/Sqlite/SqliteEngine.cs

@@ -0,0 +1,214 @@
+using System;
+using System.Collections.Generic;
+using System.Data;
+using System.Reflection;
+
+namespace An5Orm
+{
+    // ─── SQLite Engine ──────────────────────────────────────────────────────────
+    //
+    // Microsoft.Data.Sqlite is a different type family from the other two
+    // providers (SqliteConnection/SqliteCommand, not DbConnection subclasses you
+    // can reuse), so it gets its own engine rather than a shared abstraction.
+    //
+    // Notable differences from MSSQL, all handled by the SQL builder in
+    // An5Adapter rather than here: no WITH (NOLOCK) table hint, no SELECT TOP,
+    // LIMIT/OFFSET instead of OFFSET/FETCH NEXT, and no stored procedures.
+
+    internal class SqliteEngine : IQueryEngine
+    {
+        public Dialect Dialect => Dialect.Sqlite;
+        private readonly string _connectionString;
+        private readonly int _commandTimeout;
+
+        public SqliteEngine(string connectionString, int commandTimeout)
+        {
+            _connectionString = SqliteConnectionString.Normalize(connectionString);
+            _commandTimeout = commandTimeout;
+        }
+
+        // Set while a transaction is open; statements then join it instead of
+        // opening a second connection, which SQLite would refuse.
+        private Microsoft.Data.Sqlite.SqliteConnection _txnConn;
+
+        private Microsoft.Data.Sqlite.SqliteConnection OpenNewConnection()
+        {
+            var conn = new Microsoft.Data.Sqlite.SqliteConnection(_connectionString);
+            conn.Open();
+            // WAL keeps readers from blocking the writer, and foreign keys are
+            // off by default in SQLite even when the schema declares them.
+            using var pragma = conn.CreateCommand();
+            pragma.CommandText = "PRAGMA journal_mode=WAL; PRAGMA foreign_keys=ON;";
+            pragma.ExecuteNonQuery();
+            return conn;
+        }
+
+        private ConnectionScope<Microsoft.Data.Sqlite.SqliteConnection> Acquire()
+            => _txnConn != null
+                ? new ConnectionScope<Microsoft.Data.Sqlite.SqliteConnection>(_txnConn, owned: false)
+                : new ConnectionScope<Microsoft.Data.Sqlite.SqliteConnection>(OpenNewConnection(), owned: true);
+
+        private Microsoft.Data.Sqlite.SqliteCommand BuildCommand(
+            Microsoft.Data.Sqlite.SqliteConnection conn, string sql, Dictionary<string, object> parameters)
+        {
+            var cmd = conn.CreateCommand();
+            cmd.CommandText = sql;
+            cmd.CommandTimeout = _commandTimeout;
+            if (parameters != null)
+            {
+                foreach (var kv in parameters)
+                {
+                    // SqliteParameter names must not carry the prefix; the SQL
+                    // keeps @name and the parameter is registered as name.
+                    var paramName = kv.Key.TrimStart('@');
+                    var value = kv.Value ?? DBNull.Value;
+
+                    var param = cmd.CreateParameter();
+                    param.ParameterName = paramName;
+                    // A JSON vector or a bool needs a type SQLite will store in a
+                    // column rather than coerce to an integer.
+                    if (value is bool flag) param.Value = flag ? 1 : 0;
+                    else param.Value = value;
+                    cmd.Parameters.Add(param);
+                }
+            }
+            return cmd;
+        }
+
+        public List<Dictionary<string, object>> QueryRaw(string sql, Dictionary<string, object> parameters)
+        {
+            var results = new List<Dictionary<string, object>>();
+            using var scope = Acquire();
+            using var cmd = BuildCommand(scope.Connection, sql, parameters);
+            using var reader = cmd.ExecuteReader();
+            while (reader.Read())
+            {
+                var row = new Dictionary<string, object>(StringComparer.OrdinalIgnoreCase);
+                for (int i = 0; i < reader.FieldCount; i++)
+                {
+                    row[reader.GetName(i)] = reader.IsDBNull(i) ? null : reader.GetValue(i);
+                }
+                results.Add(row);
+            }
+            return results;
+        }
+
+        public List<T> QueryRaw<T>(string sql, Dictionary<string, object> parameters) where T : new()
+        {
+            var results = new List<T>();
+            using var scope = Acquire();
+            using var cmd = BuildCommand(scope.Connection, sql, parameters);
+            using var reader = cmd.ExecuteReader();
+            var props = typeof(T).GetProperties(BindingFlags.Public | BindingFlags.Instance);
+            while (reader.Read())
+            {
+                var item = new T();
+                foreach (var prop in props)
+                {
+                    if (!HasColumn(reader, prop.Name)) continue;
+                    var val = reader[prop.Name];
+                    if (val == DBNull.Value) continue;
+                    try { prop.SetValue(item, Convert.ChangeType(val, prop.PropertyType)); } catch { }
+                }
+                results.Add(item);
+            }
+            return results;
+        }
+
+        public int ExecuteRaw(string sql, Dictionary<string, object> parameters)
+        {
+            using var scope = Acquire();
+            using var cmd = BuildCommand(scope.Connection, sql, parameters);
+            return cmd.ExecuteNonQuery();
+        }
+
+        private static bool HasColumn(Microsoft.Data.Sqlite.SqliteDataReader reader, string name)
+        {
+            for (int i = 0; i < reader.FieldCount; i++)
+                if (reader.GetName(i).Equals(name, StringComparison.OrdinalIgnoreCase)) return true;
+            return false;
+        }
+
+        /// <summary>Detaches the transaction connection, so later statements open their own.</summary>
+        internal void ReleaseTransactionConnection() => _txnConn = null;
+
+        public An5TransactionBase BeginTransaction()
+        {
+            if (_txnConn != null)
+                throw new InvalidOperationException("A transaction is already open on this adapter.");
+            var conn = OpenNewConnection();
+            var tx = conn.BeginTransaction();
+            _txnConn = conn;
+            return new SqliteTransaction(this, conn, tx);
+        }
+    }
+
+    internal class SqliteTransaction : An5TransactionBase
+    {
+        private readonly SqliteEngine _engine;
+        private readonly Microsoft.Data.Sqlite.SqliteConnection _conn;
+        private readonly Microsoft.Data.Sqlite.SqliteTransaction _tx;
+
+        public SqliteTransaction(SqliteEngine engine, Microsoft.Data.Sqlite.SqliteConnection conn, Microsoft.Data.Sqlite.SqliteTransaction tx)
+        {
+            _engine = engine;
+            _conn = conn;
+            _tx = tx;
+        }
+
+        public override void Commit() { _tx.Commit(); }
+
+        public override void Rollback() { _tx.Rollback(); }
+
+        public override void Dispose()
+        {
+            _engine.ReleaseTransactionConnection();
+            _tx.Dispose();
+            _conn.Dispose();
+        }
+    }
+
+    // ─── Connection string normalisation ──────────────────────────────────────
+
+    internal static class SqliteConnectionString
+    {
+        /// <summary>
+        /// Turns the accepted spellings into a Data Source string.
+        ///
+        /// Microsoft.Data.Sqlite only understands `Data Source=`, so the bare
+        /// paths and `sqlite:` URLs the rest of the ORM accepts have to be
+        /// rewritten. An in-memory database has to stay open for the life of the
+        /// connection, which is why callers keep one connection per operation
+        /// open only for the duration of a statement.
+        /// </summary>
+        public static string Normalize(string connectionString)
+        {
+            var cs = (connectionString ?? "").Trim();
+            if (cs.Length == 0) return "Data Source=:memory:";
+
+            // Already a Microsoft.Data.Sqlite connection string.
+            if (cs.IndexOf("Data Source", StringComparison.OrdinalIgnoreCase) >= 0
+                || cs.IndexOf("DataSource", StringComparison.OrdinalIgnoreCase) >= 0
+                || cs.IndexOf("Mode", StringComparison.OrdinalIgnoreCase) >= 0)
+                return cs;
+
+            if (cs == ":memory:")
+                return "Data Source=:memory:";
+
+            if (cs.StartsWith("sqlite://", StringComparison.OrdinalIgnoreCase))
+                return "Data Source=" + cs.Substring("sqlite://".Length);
+
+            if (cs.StartsWith("sqlite:", StringComparison.OrdinalIgnoreCase))
+            {
+                // `sqlite:app.db` and `sqlite::memory:`
+                return "Data Source=" + cs.Substring("sqlite:".Length);
+            }
+
+            if (cs.StartsWith("file:", StringComparison.OrdinalIgnoreCase))
+                return cs; // SQLite URI, understood as-is.
+
+            // A bare path.
+            return "Data Source=" + cs;
+        }
+    }
+}

package/golang/an5_adapter.go

@@ -0,0 +1,314 @@
+// Package an5adapters provides standalone database adapter engines for Go applications.
+package an5adapters
+
+import (
+	"context"
+	"database/sql"
+	"encoding/json"
+	"sort"
+	"strings"
+
+	"an5adapters/base"
+	"an5adapters/mssql"
+	"an5adapters/postgres"
+	"an5adapters/sqlite"
+)
+
+// Re-export core base types and functions for package root convenience.
+type Dialect = base.Dialect
+type AdapterMetadata = base.AdapterMetadata
+type RelationDef = base.RelationDef
+
+const (
+	DialectMssql    = base.DialectMssql
+	DialectPostgres = base.DialectPostgres
+	DialectSqlite   = base.DialectSqlite
+)
+
+func DetectDialect(connStr string) Dialect {
+	return base.DetectDialect(connStr)
+}
+
+func QuoteIdentifier(name string, dialect Dialect) string {
+	return base.QuoteIdentifier(name, dialect)
+}
+
+func QuoteTable(tableName string, dialect Dialect) string {
+	return base.QuoteTable(tableName, dialect)
+}
+
+func CosineSimilarity(v1, v2 []float64) float64 {
+	return base.CosineSimilarity(v1, v2)
+}
+
+func EuclideanDistance(v1, v2 []float64) float64 {
+	return base.EuclideanDistance(v1, v2)
+}
+
+func DotProduct(v1, v2 []float64) float64 {
+	return base.DotProduct(v1, v2)
+}
+
+// SetAdapterMetadata injects model-to-table metadata from the generated client.
+func SetAdapterMetadata(meta AdapterMetadata) {
+	base.SetAdapterMetadata(meta)
+}
+
+// GetModelToTable returns the current model-to-table mapping.
+func GetModelToTable() map[string]string {
+	return base.GetModelToTable()
+}
+
+// GetRelationsForModel returns the relation definitions for the given model name.
+func GetRelationsForModel(modelName string) map[string]RelationDef {
+	return base.GetRelationsForModel(modelName)
+}
+
+// An5Adapter manages runtime database execution for Go applications.
+type An5Adapter struct {
+	DB      *sql.DB
+	Dialect Dialect
+}
+
+// NewAn5Adapter constructs an An5Adapter instance.
+func NewAn5Adapter(db *sql.DB, connStr string) *An5Adapter {
+	return &An5Adapter{
+		DB:      db,
+		Dialect: base.DetectDialect(connStr),
+	}
+}
+
+// Connect validates the database connection (ping).
+func (a *An5Adapter) Connect(ctx context.Context) error {
+	return a.DB.PingContext(ctx)
+}
+
+// Disconnect closes the underlying database connection pool.
+func (a *An5Adapter) Disconnect() error {
+	return a.DB.Close()
+}
+
+// QueryRaw executes a SELECT query and returns rows as maps.
+func (a *An5Adapter) QueryRaw(ctx context.Context, query string, args ...interface{}) ([]map[string]interface{}, error) {
+	rows, err := a.DB.QueryContext(ctx, query, args...)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+
+	cols, err := rows.Columns()
+	if err != nil {
+		return nil, err
+	}
+
+	var results []map[string]interface{}
+	for rows.Next() {
+		columns := make([]interface{}, len(cols))
+		columnPointers := make([]interface{}, len(cols))
+		for i := range columns {
+			columnPointers[i] = &columns[i]
+		}
+
+		if err := rows.Scan(columnPointers...); err != nil {
+			return nil, err
+		}
+
+		m := make(map[string]interface{})
+		for i, colName := range cols {
+			val := columnPointers[i].(*interface{})
+			m[colName] = *val
+		}
+		results = append(results, m)
+	}
+	if err := rows.Err(); err != nil {
+		return nil, err
+	}
+	return results, nil
+}
+
+// ExecuteRaw executes an INSERT, UPDATE, or DELETE query and returns affected rows count.
+func (a *An5Adapter) ExecuteRaw(ctx context.Context, query string, args ...interface{}) (int64, error) {
+	res, err := a.DB.ExecContext(ctx, query, args...)
+	if err != nil {
+		return 0, err
+	}
+	return res.RowsAffected()
+}
+
+// Transaction executes a function within a database transaction.
+func (a *An5Adapter) Transaction(ctx context.Context, fn func(tx *sql.Tx) error) error {
+	tx, err := a.DB.BeginTx(ctx, nil)
+	if err != nil {
+		return err
+	}
+	defer func() {
+		if p := recover(); p != nil {
+			_ = tx.Rollback()
+			panic(p)
+		}
+	}()
+
+	if err := fn(tx); err != nil {
+		_ = tx.Rollback()
+		return err
+	}
+	return tx.Commit()
+}
+
+// VectorSearch ranks rows by vector distance using native SQL execution with in-memory fallback.
+func (a *An5Adapter) VectorSearch(ctx context.Context, tableName string, targetVector []float64, take int, whereClause string, vectorField string, distanceMetric string, args ...interface{}) ([]map[string]interface{}, error) {
+	if vectorField == "" {
+		vectorField = "embedding"
+	}
+	if distanceMetric == "" {
+		distanceMetric = "cosine"
+	}
+	dim := len(targetVector)
+	vecBytes, _ := json.Marshal(targetVector)
+	vecStr := string(vecBytes)
+
+	// 1. Primary path: Native database SQL vector query execution via dialect provider (mssql / postgres / sqlite)
+	var sqlQuery string
+	if a.Dialect == base.DialectPostgres {
+		sqlQuery = postgres.BuildVectorSearchQuery(tableName, vectorField, distanceMetric, dim, take, whereClause)
+	} else if a.Dialect == base.DialectMssql {
+		sqlQuery = mssql.BuildVectorSearchQuery(tableName, vectorField, distanceMetric, dim, take, whereClause)
+	} else if a.Dialect == base.DialectSqlite {
+		sqlQuery = sqlite.BuildVectorSearchQuery(tableName, vectorField, distanceMetric, dim, take, whereClause)
+	}
+
+	if sqlQuery != "" {
+		queryArgs := append([]interface{}{vecStr}, args...)
+		nativeRows, err := a.QueryRaw(ctx, sqlQuery, queryArgs...)
+		if err == nil {
+			return nativeRows, nil
+		}
+	}
+
+	// 2. Secondary fallback: Fetch rows and compute vector distance in-memory if DB lacks native vector extensions
+	fallbackQuery := "SELECT * FROM " + base.QuoteTable(tableName, a.Dialect)
+	if strings.TrimSpace(whereClause) != "" {
+		fallbackQuery += " WHERE " + whereClause
+	}
+
+	rows, err := a.QueryRaw(ctx, fallbackQuery, args...)
+	if err != nil {
+		return nil, err
+	}
+
+	return VectorSearchFallback(rows, targetVector, take, vectorField, distanceMetric), nil
+}
+
+// VectorSearchFallback ranks rows in-memory.
+func VectorSearchFallback(rows []map[string]interface{}, targetVector []float64, take int, vectorField string, distanceMetric string) []map[string]interface{} {
+	type scored struct {
+		row      map[string]interface{}
+		distance float64
+	}
+	var list []scored
+
+	for _, r := range rows {
+		raw, ok := r[vectorField]
+		if !ok || raw == nil {
+			continue
+		}
+
+		var rowVec []float64
+		switch v := raw.(type) {
+		case string:
+			_ = json.Unmarshal([]byte(v), &rowVec)
+		case []byte:
+			_ = json.Unmarshal(v, &rowVec)
+		case []float64:
+			rowVec = v
+		case []interface{}:
+			for _, item := range v {
+				if f, ok := item.(float64); ok {
+					rowVec = append(rowVec, f)
+				}
+			}
+		}
+
+		if len(rowVec) != len(targetVector) {
+			continue
+		}
+
+		var dist float64
+		switch strings.ToLower(distanceMetric) {
+		case "euclidean":
+			dist = base.EuclideanDistance(targetVector, rowVec)
+		case "dot":
+			dist = -base.DotProduct(targetVector, rowVec)
+		default: // cosine
+			dist = 1.0 - base.CosineSimilarity(targetVector, rowVec)
+		}
+
+		rCopy := make(map[string]interface{})
+		for k, val := range r {
+			rCopy[k] = val
+		}
+		rCopy["distance"] = dist
+		list = append(list, scored{row: rCopy, distance: dist})
+	}
+
+	sort.Slice(list, func(i, j int) bool {
+		return list[i].distance < list[j].distance
+	})
+
+	var result []map[string]interface{}
+	limit := take
+	if limit <= 0 || limit > len(list) {
+		limit = len(list)
+	}
+	for i := 0; i < limit; i++ {
+		result = append(result, list[i].row)
+	}
+	return result
+}
+
+// QueryProc executes a stored procedure and returns the result rows.
+func (a *An5Adapter) QueryProc(ctx context.Context, procName string, args ...interface{}) ([]map[string]interface{}, error) {
+	var sql string
+	if a.Dialect == base.DialectPostgres {
+		placeholders := make([]string, len(args))
+		for i := range args {
+			placeholders[i] = placeholder(a.Dialect, i+1)
+		}
+		sql = "CALL " + procName + "(" + strings.Join(placeholders, ", ") + ")"
+	} else {
+		placeholders := make([]string, len(args))
+		for i := range args {
+			placeholders[i] = "?"
+		}
+		if len(placeholders) > 0 {
+			sql = "EXEC " + procName + " " + strings.Join(placeholders, ", ")
+		} else {
+			sql = "EXEC " + procName
+		}
+	}
+	return a.QueryRaw(ctx, sql, args...)
+}
+
+// ExecuteProc executes a stored procedure and returns affected rows.
+func (a *An5Adapter) ExecuteProc(ctx context.Context, procName string, args ...interface{}) (int64, error) {
+	var sql string
+	if a.Dialect == base.DialectPostgres {
+		placeholders := make([]string, len(args))
+		for i := range args {
+			placeholders[i] = placeholder(a.Dialect, i+1)
+		}
+		sql = "CALL " + procName + "(" + strings.Join(placeholders, ", ") + ")"
+	} else {
+		placeholders := make([]string, len(args))
+		for i := range args {
+			placeholders[i] = "?"
+		}
+		if len(placeholders) > 0 {
+			sql = "EXEC " + procName + " " + strings.Join(placeholders, ", ")
+		} else {
+			sql = "EXEC " + procName
+		}
+	}
+	return a.ExecuteRaw(ctx, sql, args...)
+}
+

package/golang/base/base.go

@@ -0,0 +1,100 @@
+// Package base provides core dialect types, quoting utilities, and vector math for AN5 Go Adapters.
+package base
+
+import (
+	"math"
+	"strings"
+)
+
+// Dialect represents supported database engines.
+type Dialect string
+
+const (
+	DialectMssql    Dialect = "mssql"
+	DialectPostgres Dialect = "postgres"
+	DialectSqlite   Dialect = "sqlite"
+)
+
+// DetectDialect parses connection string to determine database dialect.
+func DetectDialect(connStr string) Dialect {
+	lower := strings.ToLower(strings.TrimSpace(connStr))
+	if strings.HasPrefix(lower, "postgres://") || strings.HasPrefix(lower, "postgresql://") || strings.Contains(lower, "port=5432") {
+		return DialectPostgres
+	}
+	if strings.HasPrefix(lower, "sqlite://") || strings.HasPrefix(lower, "sqlite:") || strings.HasPrefix(lower, "file:") || strings.HasSuffix(lower, ".db") || strings.HasSuffix(lower, ".sqlite") || strings.HasSuffix(lower, ".sqlite3") || lower == ":memory:" {
+		return DialectSqlite
+	}
+	return DialectMssql
+}
+
+// QuoteIdentifier quotes column or identifier names according to dialect.
+func QuoteIdentifier(name string, dialect Dialect) string {
+	raw := stripWrapping(name, "[", "]")
+	if dialect == DialectPostgres || dialect == DialectSqlite {
+		raw = stripWrapping(raw, `"`, `"`)
+		return `"` + strings.ReplaceAll(raw, `"`, `""`) + `"`
+	}
+	return "[" + strings.ReplaceAll(raw, "]", "]]") + "]"
+}
+
+// QuoteTable quotes schema-qualified table names (e.g. "dbo.users" -> "[dbo].[users]").
+func QuoteTable(tableName string, dialect Dialect) string {
+	if strings.HasPrefix(tableName, "[") || strings.HasPrefix(tableName, `"`) {
+		return tableName
+	}
+	parts := strings.Split(tableName, ".")
+	var quoted []string
+	for _, p := range parts {
+		quoted = append(quoted, QuoteIdentifier(p, dialect))
+	}
+	return strings.Join(quoted, ".")
+}
+
+func stripWrapping(name, left, right string) string {
+	if strings.HasPrefix(name, left) && strings.HasSuffix(name, right) {
+		return strings.TrimSuffix(strings.TrimPrefix(name, left), right)
+	}
+	return name
+}
+
+// CosineSimilarity computes cosine similarity between two float64 vectors.
+func CosineSimilarity(v1, v2 []float64) float64 {
+	if len(v1) != len(v2) || len(v1) == 0 {
+		return 0
+	}
+	var dot, m1, m2 float64
+	for i := 0; i < len(v1); i++ {
+		dot += v1[i] * v2[i]
+		m1 += v1[i] * v1[i]
+		m2 += v2[i] * v2[i]
+	}
+	if m1 == 0 || m2 == 0 {
+		return 0
+	}
+	return dot / (math.Sqrt(m1) * math.Sqrt(m2))
+}
+
+// EuclideanDistance computes L2 distance between two float64 vectors.
+func EuclideanDistance(v1, v2 []float64) float64 {
+	if len(v1) != len(v2) || len(v1) == 0 {
+		return 0
+	}
+	var sum float64
+	for i := 0; i < len(v1); i++ {
+		diff := v1[i] - v2[i]
+		sum += diff * diff
+	}
+	return math.Sqrt(sum)
+}
+
+// DotProduct computes inner product of two float64 vectors.
+func DotProduct(v1, v2 []float64) float64 {
+	if len(v1) != len(v2) || len(v1) == 0 {
+		return 0
+	}
+	var dot float64
+	for i := 0; i < len(v1); i++ {
+		dot += v1[i] * v2[i]
+	}
+	return dot
+}