README

PDO wrapper for Phel. Talk to relational databases from Phel without dropping into PHP interop.

Install

composer require phel-lang/phel-pdo

Requires PHP >=8.4 and phel-lang/phel-lang ^0.41.

Quick start

(require phel.pdo)

(def conn (pdo/connect "sqlite::memory:"))
(pdo/exec conn "create table t1 (id integer primary key autoincrement, name varchar(10))")
(pdo/exec conn "insert into t1 (name) values ('phel'), ('php')")

;; Raw query
(-> (pdo/query conn "select * from t1 where id = 1")
    (pdo/fetch))
;; => {:id 1, :name "phel"}

;; Prepared statement
(-> (pdo/prepare conn "select * from t1 where id = :id")
    (pdo/execute {:id 1})
    (pdo/fetch))
;; => {:id 1, :name "phel"}

;; Insert a row from a map
(pdo/insert conn :t1 {:name "lisp"})
;; => "3"   ; new last-insert-id (string, as PDO reports it)

pdo/fetch returns the row as a map keyed by column keyword, or nil when no rows remain.

With phel-sql

phel-sql is an optional data-driven SQL DSL. It returns [sql params] you feed straight into pdo/prepare + pdo/execute:

(let [[query params] (sql/format {:select [:id :name], :from [:users], :where [:= :id 1]})]
  (-> (pdo/prepare conn query)
      (pdo/execute params)
      (pdo/fetch)))
;; => {:id 1, :name "phel"}

API

All functions live in the phel.pdo namespace.

Connection

Function	Signature	Description
`connect`	`(connect dsn & [username password options])`	Open a connection. Throws `PDOException` on failure. Sets `ERRMODE_EXCEPTION` by default.
`from-connection`	`(from-connection pdo & [options])`	Wrap an already-open `\PDO` (e.g. a framework/DBAL connection) as-is. `{:apply-defaults true}` sets `ERRMODE_EXCEPTION`.
`exec`	`(exec conn sql)`	Execute SQL, return number of affected rows.
`query`	`(query conn sql & [fetch-mode])`	Run SQL without placeholders, return a statement.
`prepare`	`(prepare conn sql & [options])`	Prepare a statement for later `execute`.
`insert`	`(insert conn table row)`	Insert a non-empty `row` map into `table` via a prepared statement and return the new `last-insert-id` (string). Identifiers must match `[A-Za-z_][A-Za-z0-9_]*`.
`quote`	`(quote conn string & [type])`	Quote a string for safe embedding in SQL.
`last-insert-id`	`(last-insert-id conn)`	ID of the last inserted row, as a string (as PDO reports it).
`begin` / `commit` / `rollback`	`(begin conn)` …	Transaction control.
`in-transaction`	`(in-transaction conn)`	`true` if a transaction is active.
`with-transaction`	`(with-transaction conn & body)`	Run `body` in a transaction: commit + return last value, or rollback + re-throw. Runs inline if already in a transaction.
`get-attribute` / `set-attribute`	`(get-attribute handle attr)` / `(set-attribute handle attr value)`	PDO attribute access; `handle` is a connection or a statement.
`get-available-drivers`	`(get-available-drivers)`	Vector of installed PDO drivers (static; no connection needed).
`error-code`	`(error-code handle)`	SQLSTATE string of the last operation; `handle` is a connection or a statement.
`error-info`	`(error-info handle)`	`[sqlstate driver-code driver-message]`; `handle` is a connection or a statement.

Statement

Returned by pdo/query and pdo/prepare.

Function	Signature	Description
`execute`	`(execute stmt & [params])`	Run a prepared statement. Returns the statement so it threads through `->` / `let`.
`fetch`	`(fetch stmt)`	Next row as a map, or `nil` if exhausted.
`fetch-all`	`(fetch-all stmt)`	Remaining rows as a vector of maps.
`fetch-column`	`(fetch-column stmt & [column])`	Single column from the next row.
`fetch-object`	`(fetch-object stmt & [class-name ctor-args])`	Next row as an object (`stdClass` by default, or an instance of `class-name`), or `nil` if exhausted.
`statement-seq`	`(statement-seq stmt)`	Lazy seq of the remaining rows as maps, fetched one at a time.
`bind-value`	`(bind-value stmt column value & [type])`	Bind a value to a placeholder. Returns the statement.
`bind-param`	`(bind-param stmt column value & [type])`	Bind a parameter, applied at execution time. Returns the statement.
`column-count`	`(column-count stmt)`	Number of columns in the result set.
`row-count`	`(row-count stmt)`	Rows affected by the last DML.
`column-meta`	`(column-meta stmt column)`	Metadata map for a 0-indexed column, or `nil` if unavailable.
`close-cursor`	`(close-cursor stmt)`	Free the cursor so the statement can be re-executed. Returns the statement.
`set-fetch-mode`	`(set-fetch-mode stmt mode & args)`	Set the statement's default fetch mode (extra args match the mode). Returns the statement.
`next-rowset`	`(next-rowset stmt)`	Advance to the next rowset of a multi-rowset statement; `false` when none remain.
`debug-dump-params`	`(debug-dump-params stmt)`	Dump prepared statement info as a string.

Note

Unlike PDOStatement::execute() (returns bool), pdo/execute returns the statement itself so it composes with ->.

Development

composer install
vendor/bin/phel test

Docs

Deeper docs live in docs/:

Getting started - install, first query, run tests.
Architecture - connection / statement design and conventions.
Recipes - transactions, prepared statements, bind types, phel-sql.
Troubleshooting - common errors and fixes.
Contributing - adding wrappers, commits, PRs, releases.

smeghead / phel-pdo

Maintainers

Package info

Fund package maintenance!

Statistics

Security