fresco 0.0.1

data/lib/fresco/runtime/db_postgres.rb

@@ -0,0 +1,403 @@
+# Fresco Postgres adapter. Copied verbatim to generated/db_adapter.rb
+# by `fresco build` when config/database.rb declares `Fresco.database
+# :postgres`. Always loaded between runtime.rb and config/app.rb —
+# boot order in lib/fresco/runtime/boot.rb.
+#
+# Same Ruby surface as db_sqlite.rb — `Fresco::Db::Postgres` exposes
+# open/close/exec/prepare/bind_str/bind_int/step/col_str/col_int/
+# col_count/finalize/reset/last_rowid + the first_str/first_int
+# helpers. Generated code (M3+) writes against `Fresco::Db::Active`
+# so swapping adapters is a config edit, not an action edit.
+#
+# Placeholder syntax differs from SQLite: libpq uses `$1, $2, ...` not
+# `?`. User-written SQL has to use the adapter's native syntax; M3+
+# codegen will paper over this when emitting prepared statements.
+#
+# Build dependency: generated/runtime/postgres.c (copied from the
+# fresco gem at build time) needs libpq's headers (`libpq-fe.h`) and
+# library (`-lpq`). `fresco release` auto-detects Homebrew/Postgres.app
+# layouts and exports CPATH/LIBRARY_PATH accordingly. On Linux:
+# `apt-get install libpq-dev`.
+# `Pg` (not `Postgres`) so the FFI module name doesn't collide with
+# `Fresco::Db::Postgres`. Matches the `fresco_pg_*` C-side prefix and
+# mirrors the `Sqlite` (FFI) vs `SQLite` (wrapper) split.
+module Pg
+  ffi_cflags "generated/runtime/postgres.c"
+  ffi_lib    "pq"
+
+  ffi_func :fresco_pg_open,              [:str],             :int
+  ffi_func :fresco_pg_close,             [:int],             :int
+  ffi_func :fresco_pg_exec,              [:int, :str],       :int
+  ffi_func :fresco_pg_prepare,           [:int, :str],       :int
+  ffi_func :fresco_pg_bind_str,          [:int, :int, :str], :int
+  ffi_func :fresco_pg_bind_int,          [:int, :int, :int], :int
+  ffi_func :fresco_pg_step,              [:int],             :int
+  ffi_func :fresco_pg_col_str,           [:int, :int],       :str
+  ffi_func :fresco_pg_col_int,           [:int, :int],       :int
+  ffi_func :fresco_pg_col_count,         [:int],             :int
+  ffi_func :fresco_pg_finalize,          [:int],             :int
+  ffi_func :fresco_pg_reset,             [:int],             :int
+  ffi_func :fresco_pg_last_insert_rowid, [:int],             :int
+end
+
+module Fresco
+  module Db
+    # Thin Ruby cover over the Postgres FFI module. Same shape as
+    # Fresco::Db::SQLite — identical method names, identical return
+    # conventions (0/-1 status, 1/0/-1 step, Int/Str cols, etc.).
+    #
+    # Differences worth knowing per-adapter:
+    #   - URL-based open instead of file path. Pass a libpq conninfo
+    #     string ("postgres://user@host/db" or "host=... user=...").
+    #   - last_rowid runs `SELECT lastval()` — only valid when the
+    #     prior statement triggered a sequence. For predictable INSERT
+    #     id reads, use `INSERT ... RETURNING id` + step + col_int(0).
+    #   - Placeholders are `$1, $2, ...` not `?`.
+    class Postgres
+      attr_accessor :dbh
+
+      def initialize
+        @dbh = -1
+      end
+
+      # Returns true on success, false on failure. URL accepts any libpq
+      # conninfo string. Calling #open twice on the same instance leaks
+      # the prior handle — close first.
+      def open(url = "")
+        h = Pg.fresco_pg_open(url)
+        return false if h < 0
+        @dbh = h
+        true
+      end
+
+      def close
+        if @dbh >= 0
+          Pg.fresco_pg_close(@dbh)
+          @dbh = -1
+        end
+        0
+      end
+
+      # Run a no-bind statement (DDL, BEGIN/COMMIT, queries with literal
+      # constants). Returns true on success. For any user-supplied value
+      # always use prepare + bind + step + finalize.
+      def exec(sql = "")
+        return false if @dbh < 0
+        Pg.fresco_pg_exec(@dbh, sql) == 0
+      end
+
+      # Open a cursor on a parameterised statement. Returns an Int
+      # cursor id (>= 1) on success, -1 on failure. The query doesn't
+      # actually hit Postgres until the first #step — bind_str/bind_int
+      # calls between prepare and step accumulate the values that will
+      # be passed to PQexecParams.
+      def prepare(sql = "")
+        return -1 if @dbh < 0
+        Pg.fresco_pg_prepare(@dbh, sql)
+      end
+
+      def bind_str(cid = 0, idx = 0, value = "")
+        Pg.fresco_pg_bind_str(cid, idx, value)
+      end
+
+      def bind_int(cid = 0, idx = 0, value = 0)
+        Pg.fresco_pg_bind_int(cid, idx, value)
+      end
+
+      # 1 -> row available, 0 -> done, -1 -> error or invalid cursor.
+      # The first call fires PQexecParams with accumulated binds;
+      # subsequent calls walk the result one row at a time.
+      def step(cid = 0);             Pg.fresco_pg_step(cid);            end
+      def col_str(cid = 0, idx = 0); Pg.fresco_pg_col_str(cid, idx);    end
+      def col_int(cid = 0, idx = 0); Pg.fresco_pg_col_int(cid, idx);    end
+      def col_count(cid = 0);        Pg.fresco_pg_col_count(cid);       end
+      def finalize(cid = 0);         Pg.fresco_pg_finalize(cid);        end
+      def reset(cid = 0);            Pg.fresco_pg_reset(cid);           end
+
+      def last_rowid
+        return -1 if @dbh < 0
+        Pg.fresco_pg_last_insert_rowid(@dbh)
+      end
+
+      # Single-row single-column convenience. Same semantics as
+      # Fresco::Db::SQLite#first_str — pass `""` for no bind. Always
+      # finalises the cursor before returning.
+      def first_str(sql = "", p1 = "")
+        return "" if @dbh < 0
+        cid = Pg.fresco_pg_prepare(@dbh, sql)
+        return "" if cid < 0
+        if p1.length > 0
+          Pg.fresco_pg_bind_str(cid, 1, p1)
+        end
+        result = ""
+        if Pg.fresco_pg_step(cid) == 1
+          result = Pg.fresco_pg_col_str(cid, 0)
+        end
+        Pg.fresco_pg_finalize(cid)
+        result
+      end
+
+      def first_int(sql = "", p1 = "")
+        return 0 if @dbh < 0
+        cid = Pg.fresco_pg_prepare(@dbh, sql)
+        return 0 if cid < 0
+        if p1.length > 0
+          Pg.fresco_pg_bind_str(cid, 1, p1)
+        end
+        result = 0
+        if Pg.fresco_pg_step(cid) == 1
+          result = Pg.fresco_pg_col_int(cid, 0)
+        end
+        Pg.fresco_pg_finalize(cid)
+        result
+      end
+    end
+
+    # Alias the chosen adapter so generated code (M3+) and user actions
+    # can refer to one name regardless of which is linked.
+    #
+    # Don't call `Fresco::Db::Active.new` directly from action code:
+    # Spinel's analyzer doesn't chase constant aliases through Active,
+    # treats the receiver as int, and emits 0 for every subsequent
+    # method call on the returned object. Use `Fresco::Db.new_instance`
+    # below instead — the typed factory gives Spinel a concrete class
+    # to bind dispatch against.
+    Active = Postgres
+
+    # Adapter-agnostic factory. Returns a fresh unopened Postgres (or
+    # SQLite, in the other template) instance. Action code that wants
+    # to be DB-agnostic calls this; Spinel's analyzer sees the concrete
+    # return type per-build and dispatches correctly.
+    def self.new_instance
+      Postgres.new
+    end
+
+    # Lazy connection handle for the generated model layer. See the
+    # SQLite-template version for design notes — same pattern, same
+    # int-default-pinning rationale.
+    @conn_dbh = -1
+
+    def self.ensure_connection_dbh!
+      if @conn_dbh < 0
+        h = Pg.fresco_pg_open(Fresco.database_url)
+        @conn_dbh = h if h > 0
+      end
+      @conn_dbh
+    end
+
+    # SQL query logging. See db_sqlite.rb for full design notes — same
+    # FRESCO_LOG_SQL env gate, same in-request buffer, same `[db]` /
+    # `[db cached]` line format, same verb-driven color palette via
+    # `color_sql` in runtime.rb, same per-bind value capture for the
+    # trailing `[$1=..., $2=...]` annotation.
+    def self.log_sql?
+      ENV.fetch("FRESCO_LOG_SQL", "") != ""
+    end
+
+    @in_request = false
+    @log_buffer = [""]
+    @log_buffer.delete_at(0)
+
+    # See db_sqlite.rb for design notes on `@has_pending` vs
+    # `@pending_sql`: the former is the timing-state flag (always
+    # tracked), the latter is set only when FRESCO_LOG_SQL is on.
+    # Per-request totals live on `Fresco` (in runtime.rb) — same
+    # workaround for Spinel cross-file value-return collapse.
+    @has_pending    = false
+    @pending_t0     = 0
+    @pending_sql    = ""
+    @pending_label  = ""
+    @pending_binds  = ""
+
+    def self.begin_request!
+      @in_request = true
+      Fresco.reset_db_sql_stats!
+    end
+
+    # See db_sqlite.rb for the in-place-clear rationale — repeated
+    # `@log_buffer = [""]` reassignment crashes under Spinel after a
+    # few hundred requests (orphaned-array bus error).
+    def self.flush_log!
+      flush_pending!
+      i = 0
+      while i < @log_buffer.length
+        puts @log_buffer[i]
+        i += 1
+      end
+      while @log_buffer.length > 0
+        @log_buffer.delete_at(@log_buffer.length - 1)
+      end
+      @in_request = false
+    end
+
+    def self.flush_pending!
+      return unless @has_pending
+      dt = Sock.sphttp_elapsed_micros - @pending_t0
+      Fresco.add_sql_micros!(dt)
+      if @pending_sql != ""
+        line = @pending_label + Color.dim("(" + fmt_micros(dt) + ") ") + color_sql(@pending_sql)
+        if @pending_binds != ""
+          line += Color.dim("  [" + @pending_binds + "]")
+        end
+        emit(line)
+      end
+      @has_pending   = false
+      @pending_t0    = 0
+      @pending_sql   = ""
+      @pending_label = ""
+      @pending_binds = ""
+    end
+
+    def self.emit(line = "")
+      if @in_request
+        @log_buffer.push(line)
+      else
+        puts line
+      end
+    end
+
+    def self.record_bind_int(idx = 0, value = 0, name = "")
+      return if @pending_sql == ""
+      sep   = @pending_binds == "" ? "" : ", "
+      label = name == "" ? "$" + idx.to_s : name
+      @pending_binds = @pending_binds + sep + label + "=" + value.to_s
+    end
+
+    def self.record_bind_str(idx = 0, value = "", name = "")
+      return if @pending_sql == ""
+      sep   = @pending_binds == "" ? "" : ", "
+      label = name == "" ? "$" + idx.to_s : name
+      @pending_binds = @pending_binds + sep + label + "=\"" + value + "\""
+    end
+
+    # Adapter-agnostic surface for the model codegen. See db_sqlite.rb
+    # for design notes — same method names, same return conventions;
+    # only the underlying FFI delegate differs.
+    def self.exec(sql = "")
+      h = ensure_connection_dbh!
+      return false if h < 0
+      flush_pending! if @has_pending
+      t0 = Sock.sphttp_elapsed_micros
+      result = Pg.fresco_pg_exec(h, sql) == 0
+      dt = Sock.sphttp_elapsed_micros - t0
+      Fresco.add_sql_micros!(dt)
+      if log_sql?
+        emit(Color.dim("  [db] (" + fmt_micros(dt) + ") ") + color_sql(sql))
+      end
+      result
+    end
+
+    def self.prepare(sql = "")
+      h = ensure_connection_dbh!
+      return -1 if h < 0
+      flush_pending! if @has_pending
+      @pending_t0  = Sock.sphttp_elapsed_micros
+      @has_pending = true
+      if log_sql?
+        @pending_sql   = sql
+        @pending_label = Color.dim("  [db] ")
+        @pending_binds = ""
+      end
+      Pg.fresco_pg_prepare(h, sql)
+    end
+
+    # Prepared-statement cache. See db_sqlite.rb for design notes —
+    # same shape, same StrIntHash pinning, same cursor-lifetime
+    # contract. For Postgres the reset clears the cached PGresult
+    # so the next step re-fires PQexecParams with whatever binds
+    # the caller sets between cached_prepare and step.
+    @stmt_cache = { "__t" => 0 }
+    @stmt_cache.delete("__t")
+
+    def self.cached_prepare(sql = "")
+      if @stmt_cache.key?(sql)
+        cid = @stmt_cache[sql]
+        Pg.fresco_pg_reset(cid)
+        flush_pending! if @has_pending
+        @pending_t0  = Sock.sphttp_elapsed_micros
+        @has_pending = true
+        if log_sql?
+          @pending_sql   = sql
+          @pending_label = Color.dim("  [db cached] ")
+          @pending_binds = ""
+        end
+        return cid
+      end
+      cid = prepare(sql)
+      @stmt_cache[sql] = cid if cid > 0
+      cid
+    end
+
+    # The trailing `name = ""` is the column-name annotation for log
+    # output — see db_sqlite.rb for design notes.
+    def self.bind_str(cid = 0, idx = 0, value = "", name = "")
+      record_bind_str(idx, value, name) if log_sql?
+      Pg.fresco_pg_bind_str(cid, idx, value)
+    end
+
+    def self.bind_int(cid = 0, idx = 0, value = 0, name = "")
+      record_bind_int(idx, value, name) if log_sql?
+      Pg.fresco_pg_bind_int(cid, idx, value)
+    end
+
+    # See db_sqlite.rb for design notes on the two timing paths.
+    def self.step(cid = 0)
+      if @has_pending
+        result = Pg.fresco_pg_step(cid)
+        flush_pending!
+        return result
+      end
+      t0 = Sock.sphttp_elapsed_micros
+      result = Pg.fresco_pg_step(cid)
+      Fresco.add_sql_micros!(Sock.sphttp_elapsed_micros - t0)
+      result
+    end
+
+    def self.col_str(cid = 0, idx = 0); Pg.fresco_pg_col_str(cid, idx); end
+    def self.col_int(cid = 0, idx = 0); Pg.fresco_pg_col_int(cid, idx); end
+    def self.finalize(cid = 0);         Pg.fresco_pg_finalize(cid);     end
+    def self.reset(cid = 0);            Pg.fresco_pg_reset(cid);        end
+
+    def self.last_rowid
+      h = ensure_connection_dbh!
+      return -1 if h < 0
+      Pg.fresco_pg_last_insert_rowid(h)
+    end
+
+    # Eager-open the connection. Called once from Fresco::App#run at
+    # startup. Same rationale as the SQLite-template version —
+    # surface a bad DSN at process start instead of inside the first
+    # request.
+    def self.boot!
+      ensure_connection_dbh!
+    end
+
+    @tx_rollback_requested = false
+
+    def self.rollback!
+      @tx_rollback_requested = true
+    end
+
+    # Transaction support. Same shape as the SQLite-template version
+    # — explicit `Fresco::Db.rollback!` instead of rescue-on-raise
+    # because Spinel's rescue handling across FFI boundaries is iffy.
+    # Transaction primitives. See db_sqlite.rb for design notes —
+    # Spinel doesn't lower `&block` cleanly so we expose explicit
+    # begin/commit/rollback instead of a block-yielding transaction.
+    def self.begin_tx
+      exec("BEGIN")
+      @tx_rollback_requested = false
+      true
+    end
+
+    def self.commit_tx
+      if @tx_rollback_requested
+        exec("ROLLBACK")
+        @tx_rollback_requested = false
+        return false
+      end
+      exec("COMMIT")
+      true
+    end
+  end
+end