@an5/adapters 0.2.11 → 0.2.14

package/java/src/main/java/an5/adapters/An5Adapter.java

@@ -0,0 +1,374 @@
+package an5.adapters;
+
+import an5.adapters.base.Dialect;
+import an5.adapters.base.JdbcUrls;
+import java.sql.Connection;
+import java.sql.DriverManager;
+import java.sql.PreparedStatement;
+import java.sql.ResultSet;
+import java.sql.ResultSetMetaData;
+import java.sql.SQLException;
+import java.sql.Types;
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.Properties;
+
+/**
+ * The AN5 runtime adapter for Java: a connection holder plus raw SQL execution.
+ *
+ * <p>Model knowledge lives in {@link an5.adapters.base.Metadata}, which the generated
+ * client fills in at start-up. Queries go through {@link #table(String)}; this class is
+ * only the layer underneath that needs to know about connections and dialect.
+ *
+ * <p>Instances are not thread-safe, exactly like the other AN5 adapters: the transaction
+ * slot below holds one open connection that every statement has to share.
+ */
+public class An5Adapter implements AutoCloseable {
+
+  /** The unit of work a {@link #transaction} runs. */
+  public interface TransactionWork<T> {
+    T run(An5Adapter adapter) throws SQLException;
+  }
+
+  private final Dialect dialect;
+  private final String connectionString;
+
+  /**
+   * Pins one SQLite vector strategy instead of probing for the fastest one available:
+   * {@code sqlite-vec}, {@code udf}, {@code sql} or {@code memory}. Empty probes.
+   */
+  private String vectorStrategy = "";
+
+  /**
+   * What this SQLite connection can do, probed once with cheap {@code SELECT}s.
+   *
+   * <p>JDBC has no API for registering a user function or loading an extension, so a stock
+   * adapter normally reports only JSON1. That is enough to rank with {@code json_each}; the
+   * sqlite-vec and UDF strategies need a driver built for them (the Xerial driver, for
+   * instance, loads an extension through a {@code _load_extension} connection property).
+   */
+  private an5.adapters.base.SqliteVectors.Capabilities sqliteCapabilities;
+
+  /** The SQLite vector strategy to pin, or {@code null} to probe. */
+  public String vectorStrategy() {
+    return vectorStrategy;
+  }
+
+  /** Pins one SQLite vector strategy instead of probing. */
+  public void setVectorStrategy(String strategy) {
+    this.vectorStrategy = strategy == null ? "" : strategy;
+  }
+
+  /** What this SQLite connection can do for vector search. */
+  public an5.adapters.base.SqliteVectors.Capabilities sqliteVectorCapabilities() {
+    if (dialect != Dialect.SQLITE) {
+      return new an5.adapters.base.SqliteVectors.Capabilities(false, false, false);
+    }
+    if (sqliteCapabilities == null) {
+      sqliteCapabilities =
+          new an5.adapters.base.SqliteVectors.Capabilities(
+              probe("SELECT vec_version()"),
+              // The probe has to reach a real distance: a driver that only knows the name
+              // would still fail on the arguments.
+              probe("SELECT an5_vec_cosine(zeroblob(4), zeroblob(4))"),
+              probe("SELECT json_valid('[1]')"));
+    }
+    return sqliteCapabilities;
+  }
+
+  /** A vector column's declared DDL type, or {@code null} when it cannot be read. */
+  public String sqliteColumnType(String table, String column) {
+    try {
+      List<Map<String, Object>> rows =
+          exec(
+              "SELECT type FROM pragma_table_info(?) WHERE name = ?",
+              java.util.Arrays.<Object>asList(table, column));
+      if (!rows.isEmpty()) {
+        Object type = rows.get(0).get("type");
+        if (type != null) {
+          return String.valueOf(type);
+        }
+      }
+    } catch (SQLException ignored) {
+      // An older SQLite without table-valued pragmas just means no declared type, and the
+      // caller then keeps every strategy in the plan.
+    }
+    return null;
+  }
+
+  /** True when a probe statement ran, whatever it returned. */
+  private boolean probe(String sql) {
+    try {
+      exec(sql);
+      return true;
+    } catch (SQLException ignored) {
+      return false;
+    }
+  }
+
+  /**
+   * The open connection of {@link #transaction}, when there is one. Every statement in the
+   * callback has to use this very connection, otherwise a rollback returns to a different,
+   * already committed connection — that is "the error was raised but the data is still there".
+   */
+  private Connection transactionConnection;
+
+  /** Long-lived connection for in-memory databases, where closing loses the data. */
+  private Connection sharedConnection;
+
+  public An5Adapter(String connectionString) {
+    this.connectionString = connectionString;
+    this.dialect = Dialect.detect(connectionString);
+  }
+
+  public Dialect dialect() {
+    return dialect;
+  }
+
+  /** Opens and returns a fresh connection; the caller closes it. */
+  public Connection connect() throws SQLException {
+    String url = JdbcUrls.url(connectionString);
+    String[] credentials = JdbcUrls.credentials(connectionString);
+    Properties properties = JdbcUrls.properties(credentials[0], credentials[1]);
+    Connection connection = DriverManager.getConnection(url, properties);
+    if (dialect == Dialect.SQLITE) {
+      // SQLite defaults foreign keys OFF, unlike every other dialect, so a schema that
+      // relies on them would silently accept rows nothing points at.
+      try {
+        connection.createStatement().execute("PRAGMA foreign_keys = ON");
+      } catch (SQLException ignored) {
+        // A driver without PRAGMA support is not a reason to fail the connection.
+      }
+    }
+    return connection;
+  }
+
+  /**
+   * The connection a statement runs on, and whether this call opened it.
+   *
+   * <p>An in-memory SQLite database is gone once every connection is closed, so
+   * {@link #sharedConnection} is kept open for its whole lifetime.
+   */
+  private Connection acquire(boolean[] owned) throws SQLException {
+    if (transactionConnection != null) {
+      owned[0] = false;
+      return transactionConnection;
+    }
+    if (dialect == Dialect.SQLITE && JdbcUrls.isMemory(connectionString)) {
+      if (sharedConnection == null) {
+        sharedConnection = connect();
+      }
+      owned[0] = false;
+      return sharedConnection;
+    }
+    owned[0] = true;
+    return connect();
+  }
+
+  @Override
+  public void close() {
+    if (sharedConnection != null) {
+      try {
+        sharedConnection.close();
+      } catch (SQLException ignored) {
+        // Closing is best effort; the pool owner reports real failures.
+      }
+      sharedConnection = null;
+    }
+  }
+
+  /** Runs a query and returns its rows as ordered maps keyed by column label. */
+  public List<Map<String, Object>> exec(String query) throws SQLException {
+    return exec(query, Collections.<Object>emptyList());
+  }
+
+  public List<Map<String, Object>> exec(String query, List<Object> params) throws SQLException {
+    boolean[] owned = new boolean[1];
+    Connection connection = acquire(owned);
+    try {
+      PreparedStatement statement = prepare(connection, query, params);
+      try {
+        ResultSet results = statement.executeQuery();
+        try {
+          return readRows(results);
+        } finally {
+          results.close();
+        }
+      } finally {
+        statement.close();
+      }
+    } finally {
+      if (owned[0]) {
+        connection.close();
+      }
+    }
+  }
+
+  /** Runs a statement that returns no rows and gives back the affected row count. */
+  public int execute(String query) throws SQLException {
+    return execute(query, Collections.<Object>emptyList());
+  }
+
+  public int execute(String query, List<Object> params) throws SQLException {
+    boolean[] owned = new boolean[1];
+    Connection connection = acquire(owned);
+    try {
+      PreparedStatement statement = prepare(connection, query, params);
+      try {
+        return statement.executeUpdate();
+      } finally {
+        statement.close();
+      }
+    } finally {
+      if (owned[0]) {
+        connection.close();
+      }
+    }
+  }
+
+  public List<Map<String, Object>> queryRaw(String query, Object... params) throws SQLException {
+    return exec(query, toList(params));
+  }
+
+  public int executeRaw(String query, Object... params) throws SQLException {
+    return execute(query, toList(params));
+  }
+
+  /** The table client for a model, or for a view name on {@link #view(String)}. */
+  public An5TableClient table(String modelName) {
+    return new An5TableClient(this, modelName);
+  }
+
+  /** A read-only client for a database view. */
+  public An5ViewClient view(String viewName) {
+    return new An5ViewClient(this, viewName);
+  }
+
+  /**
+   * Runs work inside a transaction, committing on return and rolling back on failure.
+   *
+   * <p>Nesting is rejected rather than flattened: an inner commit would make the outer
+   * rollback a partial save, which is the opposite of what the caller asked for.
+   */
+  public <T> T transaction(TransactionWork<T> work) throws SQLException {
+    if (transactionConnection != null) {
+      throw new IllegalStateException("Nested transaction() is not supported");
+    }
+    boolean[] owned = new boolean[1];
+    Connection connection = acquire(owned);
+    boolean previousAutoCommit = connection.getAutoCommit();
+    connection.setAutoCommit(false);
+    transactionConnection = connection;
+    try {
+      T result = work.run(this);
+      connection.commit();
+      return result;
+    } catch (SQLException error) {
+      connection.rollback();
+      throw error;
+    } catch (RuntimeException error) {
+      connection.rollback();
+      throw error;
+    } catch (Error error) {
+      connection.rollback();
+      throw error;
+    } finally {
+      transactionConnection = null;
+      connection.setAutoCommit(previousAutoCommit);
+      if (owned[0]) {
+        connection.close();
+      }
+    }
+  }
+
+  public List<Map<String, Object>> queryProc(String procName, List<Object> params) throws SQLException {
+    return exec(callStatement(procName, params, false), params);
+  }
+
+  public int executeProc(String procName, List<Object> params) throws SQLException {
+    return execute(callStatement(procName, params, true), params);
+  }
+
+  /**
+   * SQLite has no stored procedures.
+   *
+   * <p>This used to fall through to the MSSQL branch and emit {@code EXEC ...}, which is not
+   * valid SQL anywhere; the error only surfaced at the call. Saying so beats sending wrong SQL.
+   */
+  private String callStatement(String procName, List<Object> params, boolean forExecute) {
+    if (dialect == Dialect.SQLITE) {
+      throw new UnsupportedOperationException(
+          "SQLite has no stored procedures. Use the generated table client "
+              + "(db.table(\"Model\").findMany()) or db.exec() with a parameterised query.");
+    }
+    int count = params == null ? 0 : params.size();
+    List<String> placeholders = new ArrayList<String>();
+    for (int i = 0; i < count; i++) {
+      placeholders.add(dialect.placeholder());
+    }
+    String joined = placeholders.isEmpty() ? "" : join(placeholders, ", ");
+    if (dialect == Dialect.POSTGRES) {
+      return joined.isEmpty()
+          ? "CALL " + procName + "()"
+          : "CALL " + procName + "(" + joined + ")";
+    }
+    return joined.isEmpty() ? "EXEC " + procName : "EXEC " + procName + " " + joined;
+  }
+
+  private PreparedStatement prepare(Connection connection, String query, List<Object> params)
+      throws SQLException {
+    PreparedStatement statement = connection.prepareStatement(query);
+    if (params != null) {
+      for (int i = 0; i < params.size(); i++) {
+        Object value = params.get(i);
+        if (value == null) {
+          statement.setNull(i + 1, Types.NULL);
+        } else {
+          statement.setObject(i + 1, value);
+        }
+      }
+    }
+    return statement;
+  }
+
+  private static List<Map<String, Object>> readRows(ResultSet results) throws SQLException {
+    List<Map<String, Object>> rows = new ArrayList<Map<String, Object>>();
+    ResultSetMetaData meta = results.getMetaData();
+    int columns = meta.getColumnCount();
+    while (results.next()) {
+      // LinkedHashMap so a row keeps the column order of the SELECT, which is what makes a
+      // serialised row read the same way every time.
+      Map<String, Object> row = new LinkedHashMap<String, Object>();
+      for (int i = 1; i <= columns; i++) {
+        row.put(meta.getColumnLabel(i), results.getObject(i));
+      }
+      rows.add(row);
+    }
+    return rows;
+  }
+
+  private static List<Object> toList(Object[] params) {
+    if (params == null || params.length == 0) {
+      return Collections.emptyList();
+    }
+    List<Object> list = new ArrayList<Object>(params.length);
+    for (Object param : params) {
+      list.add(param);
+    }
+    return list;
+  }
+
+  private static String join(List<String> parts, String separator) {
+    StringBuilder out = new StringBuilder();
+    for (int i = 0; i < parts.size(); i++) {
+      if (i > 0) {
+        out.append(separator);
+      }
+      out.append(parts.get(i));
+    }
+    return out.toString();
+  }
+}

package/java/src/main/java/an5/adapters/An5Aggregate.java

@@ -0,0 +1,116 @@
+package an5.adapters;
+
+import an5.adapters.base.Dialect;
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+
+/**
+ * Which aggregates a query computes.
+ *
+ * <p>Each list names columns to apply the aggregate to; the first list added wins for a
+ * given metric, so calling {@link #sum} twice widens the first call rather than replacing it.
+ */
+public class An5Aggregate {
+
+  private boolean count;
+  private List<String> sum = new ArrayList<String>();
+  private List<String> avg = new ArrayList<String>();
+  private List<String> min = new ArrayList<String>();
+  private List<String> max = new ArrayList<String>();
+  private Map<String, Object> where;
+
+  /** Adds {@code COUNT(*)}. */
+  public An5Aggregate count() {
+    this.count = true;
+    return this;
+  }
+
+  public An5Aggregate sum(String... columns) {
+    this.sum.addAll(Arrays.asList(columns));
+    return this;
+  }
+
+  public An5Aggregate avg(String... columns) {
+    this.avg.addAll(Arrays.asList(columns));
+    return this;
+  }
+
+  public An5Aggregate min(String... columns) {
+    this.min.addAll(Arrays.asList(columns));
+    return this;
+  }
+
+  public An5Aggregate max(String... columns) {
+    this.max.addAll(Arrays.asList(columns));
+    return this;
+  }
+
+  /** Restricts the rows the aggregate runs over. */
+  public An5Aggregate where(Map<String, Object> where) {
+    this.where = where;
+    return this;
+  }
+
+  public boolean countEnabled() {
+    return count;
+  }
+
+  public List<String> sumFields() {
+    return sum;
+  }
+
+  public List<String> avgFields() {
+    return avg;
+  }
+
+  public List<String> minFields() {
+    return min;
+  }
+
+  public List<String> maxFields() {
+    return max;
+  }
+
+  public Map<String, Object> whereMap() {
+    return where;
+  }
+
+  /**
+   * The {@code SELECT} list for this aggregate, in a stable order.
+   *
+   * <p>Order is fixed so the same aggregate always produces the same SQL, which is what
+   * makes the generated query comparable between runs and cacheable.
+   */
+  public List<String> selectExpressions(Dialect dialect) {
+    List<String> expressions = new ArrayList<String>();
+    if (count) {
+      expressions.add("COUNT(*) AS _count");
+    }
+    addFor(expressions, "SUM", sumFields(), dialect);
+    addFor(expressions, "AVG", avgFields(), dialect);
+    addFor(expressions, "MIN", minFields(), dialect);
+    addFor(expressions, "MAX", maxFields(), dialect);
+    return expressions;
+  }
+
+  private static void addFor(
+      List<String> expressions, String function, List<String> fields, Dialect dialect) {
+    for (String field : fields) {
+      expressions.add(function + "(" + dialect.quoteIdentifier(field) + ") AS _" + lower(function) + "_" + field);
+    }
+  }
+
+  private static String lower(String value) {
+    return value.toLowerCase(java.util.Locale.ROOT);
+  }
+
+  /** Convenience for the one-map-per-column form used by several adapters' {@code orderBy}. */
+  public static Map<String, Object> orderEntry(String column, String direction) {
+    Map<String, Object> entry = new LinkedHashMap<String, Object>();
+    entry.put(column, direction);
+    return entry;
+  }
+}

package/java/src/main/java/an5/adapters/An5GroupBy.java

@@ -0,0 +1,97 @@
+package an5.adapters;
+
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.List;
+
+/**
+ * A grouped aggregate: the {@code GROUP BY} columns plus the aggregates over each group.
+ *
+ * <p>Extends {@link An5Aggregate} so the same {@code sum}/{@code avg} calls describe both a
+ * flat aggregate and a grouped one.
+ */
+public class An5GroupBy extends An5Aggregate {
+
+  private List<String> by = new ArrayList<String>();
+  private Object orderBy;
+  private int skip;
+  private Integer take;
+
+  /** The columns to group on. At least one is required. */
+  public An5GroupBy by(String... columns) {
+    this.by.addAll(Arrays.asList(columns));
+    return this;
+  }
+
+  @Override
+  public An5GroupBy count() {
+    super.count();
+    return this;
+  }
+
+  @Override
+  public An5GroupBy sum(String... columns) {
+    super.sum(columns);
+    return this;
+  }
+
+  @Override
+  public An5GroupBy avg(String... columns) {
+    super.avg(columns);
+    return this;
+  }
+
+  @Override
+  public An5GroupBy min(String... columns) {
+    super.min(columns);
+    return this;
+  }
+
+  @Override
+  public An5GroupBy max(String... columns) {
+    super.max(columns);
+    return this;
+  }
+
+  @Override
+  public An5GroupBy where(java.util.Map<String, Object> where) {
+    super.where(where);
+    return this;
+  }
+
+  public An5GroupBy orderBy(String column, String direction) {
+    this.orderBy = An5Aggregate.orderEntry(column, direction);
+    return this;
+  }
+
+  public An5GroupBy orderBy(Object orderBy) {
+    this.orderBy = orderBy;
+    return this;
+  }
+
+  public An5GroupBy skip(int skip) {
+    this.skip = Math.max(0, skip);
+    return this;
+  }
+
+  public An5GroupBy take(Integer take) {
+    this.take = take;
+    return this;
+  }
+
+  public List<String> byFields() {
+    return by;
+  }
+
+  public Object orderByValue() {
+    return orderBy;
+  }
+
+  public int skipValue() {
+    return skip;
+  }
+
+  public Integer takeValue() {
+    return take;
+  }
+}

package/java/src/main/java/an5/adapters/An5Query.java

@@ -0,0 +1,100 @@
+package an5.adapters;
+
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+
+/**
+ * A query built fluently and handed to a table client.
+ *
+ * <p>Every field is optional, so {@code new An5Query()} means "no filter, no order, no
+ * limit" — the same thing the other adapters read from an omitted argument.
+ */
+public class An5Query {
+
+  private Map<String, Object> where;
+  private Object orderBy;
+  private int skip;
+  private Integer take;
+  private List<String> select;
+  private Map<String, Object> include;
+
+  public An5Query where(Map<String, Object> where) {
+    this.where = where;
+    return this;
+  }
+
+  /**
+   * Orders by a single column, ascending.
+   *
+   * <p>For several columns, or a descending one, pass the map form:
+   * {@code orderBy(Map.of("name", "asc", "createdAt", "desc"))}.
+   */
+  public An5Query orderBy(String column) {
+    Map<String, Object> entry = new LinkedHashMap<String, Object>();
+    entry.put(column, "asc");
+    this.orderBy = entry;
+    return this;
+  }
+
+  public An5Query orderBy(String column, String direction) {
+    Map<String, Object> entry = new LinkedHashMap<String, Object>();
+    entry.put(column, direction);
+    this.orderBy = entry;
+    return this;
+  }
+
+  /** Accepts one entry per column; a {@code List} of them is treated as a multi-column sort. */
+  public An5Query orderBy(Object orderBy) {
+    this.orderBy = orderBy;
+    return this;
+  }
+
+  public An5Query skip(int skip) {
+    this.skip = Math.max(0, skip);
+    return this;
+  }
+
+  /** Caps the number of rows. {@code null} — the default — means no limit. */
+  public An5Query take(Integer take) {
+    this.take = take;
+    return this;
+  }
+
+  /** Restricts the returned columns; relations and {@code _count} are eager-loaded instead. */
+  public An5Query select(String... columns) {
+    this.select = columns == null || columns.length == 0 ? null : java.util.Arrays.asList(columns);
+    return this;
+  }
+
+  /** Eager-loads relations, mirroring the other adapters' {@code include} argument. */
+  public An5Query include(Map<String, Object> include) {
+    this.include = include;
+    return this;
+  }
+
+  public Map<String, Object> whereMap() {
+    return where;
+  }
+
+  public Object orderByValue() {
+    return orderBy;
+  }
+
+  public int skipValue() {
+    return skip;
+  }
+
+  /** The row cap, or {@code null} for no limit. */
+  public Integer takeValue() {
+    return take;
+  }
+
+  public List<String> selectValue() {
+    return select;
+  }
+
+  public Map<String, Object> includeValue() {
+    return include;
+  }
+}