.. include:: ../global.rst .. idio:currentmodule:: sqlite3 sqlite3 Functions ----------------- The mappings of :lname:`sqlite3` types to/from :lname:`Idio` types is: .. csv-table:: :lname:`Idio` to :lname:`sqlite3` :widths: auto :align: left fixnum, ``SQLITE_INTEGER`` integer bignum, ``SQLITE_INTEGER`` non-integer bignum, ``SQLITE_FLOAT`` ``C/int``, ``SQLITE_INTEGER`` ``C/double``, ``SQLITE_FLOAT`` ``#n``, ``SQLITE_NULL`` ``libc/int64_t``, ``SQLITE_INTEGER`` octet-string or pathname, ``SQLITE_BLOB`` string, ``SQLITE_TEXT`` .. csv-table:: :lname:`sqlite3` to :lname:`Idio` :widths: auto :align: left ``SQLITE_BLOB``, octet-string ``SQLITE_FLOAT``, bignum ``SQLITE_INTEGER``, integer (fixnum or bignum) ``SQLITE_NULL``, ``#n`` ``SQLITE_TEXT``, string .. _`sqlite3/sqlite3-open`: .. idio:function:: sqlite3/sqlite3-open name [flags] Return the database connection for `name` :param name: database name :type name: string :param flags: database open flags :type flags: C/int :return: database connection :rtype: :ref:`sqlite3-db ` :raises ^rt-libc-format-error: if `name` contains an ASCII NUL :raises ^rt-sqlite3-error: .. note:: On versions of :lname:`sqlite3` prior to v3.5.0, ``sqlite3_open()`` will be called and `flags` is ignored. .. _`sqlite3/sqlite3-close`: .. idio:function:: sqlite3/sqlite3-close db Close the database connection to `db` :param db: database connection :type db: :ref:`sqlite3-db ` :return: sqlite3 return code :rtype: C/int :raises ^rt-sqlite3-error: All of the associated `stmts` will be finalized first. .. note:: On versions of :lname:`sqlite3` prior to v3.7.14, ``sqlite3_close()`` will be called which may report errors such as ``SQLITE_BUSY``. .. _`sqlite3/sqlite3-errmsg`: .. idio:function:: sqlite3/sqlite3-errmsg db Return a description of the current error in `db` :param db: database connection :type db: :ref:`sqlite3-db ` :return: error message :rtype: string :raises ^rt-sqlite3-error: .. _`sqlite3/sqlite3-prepare`: .. idio:function:: sqlite3/sqlite3-prepare db sql Compile `sql` for `db` :param db: database connection :type db: :ref:`sqlite3-db ` :param sql: SQL statement text :type sql: string :return: database stmt :rtype: C/pointer to a :ref:`sqlite3/stmt ` :raises ^rt-libc-format-error: if `sql` contains an ASCII NUL :raises ^rt-sqlite3-error: .. _`sqlite3/sqlite3-finalize`: .. idio:function:: sqlite3/sqlite3-finalize stmt Finalize `stmt` :param stmt: prepared statement :type stmt: :ref:`sqlite3/stmt ` :return: sqlite3 return code :rtype: C/int :raises ^rt-sqlite3-error: .. _`sqlite3/sqlite3-bind-blob`: .. idio:function:: sqlite3/sqlite3-bind-blob stmt i v Replace parameter `i` with blob `v` in `stmt` :param stmt: SQL statement :type stmt: C/pointer to :ref:`sqlite3/stmt ` :param i: parameter index :type i: fixnum :param v: parameter value :type v: octet-string :return: sqlite3 return code :rtype: C/int :raises ^rt-sqlite3-error: .. note:: On versions of :lname:`sqlite3` prior to v3.8.7 ``sqlite3_bind_blob()`` will be called which will limit the valid size of `v` to a C/int. .. _`sqlite3/sqlite3-bind-double`: .. idio:function:: sqlite3/sqlite3-bind-double stmt i v Replace parameter `i` with blob `v` in `stmt` :param stmt: SQL statement :type stmt: C/pointer to :ref:`sqlite3/stmt ` :param i: parameter index :type i: fixnum :param v: parameter value :type v: C/double or bignum :return: sqlite3 return code :rtype: C/int :raises ^rt-sqlite3-error: .. _`sqlite3/sqlite3-bind-int`: .. idio:function:: sqlite3/sqlite3-bind-int stmt i v Replace parameter `i` with blob `v` in `stmt` :param stmt: SQL statement :type stmt: C/pointer to :ref:`sqlite3/stmt ` :param i: parameter index :type i: fixnum :param v: parameter value :type v: C/int|libc/int64_t|fixnum|integer bignum :return: sqlite3 return code :rtype: C/int :raises ^rt-sqlite3-error: .. _`sqlite3/sqlite3-bind-null`: .. idio:function:: sqlite3/sqlite3-bind-null stmt i v Replace parameter `i` with blob `v` in `stmt` :param stmt: SQL statement :type stmt: C/pointer to :ref:`sqlite3/stmt ` :param i: parameter index :type i: fixnum :param v: parameter value :type v: ``#n`` :return: sqlite3 return code :rtype: C/int :raises ^rt-sqlite3-error: .. _`sqlite3/sqlite3-bind-text`: .. idio:function:: sqlite3/sqlite3-bind-text stmt i v Replace parameter `i` with blob `v` in `stmt` :param stmt: SQL statement :type stmt: C/pointer to :ref:`sqlite3/stmt ` :param i: parameter index :type i: fixnum :param v: parameter value :type v: string :return: sqlite3 return code :rtype: C/int :raises ^rt-sqlite3-error: .. note:: On versions of :lname:`sqlite3` prior to v3.8.7 ``sqlite3_bind_text()`` will be called which will limit the valid size of `v` to a C/int. .. _`sqlite3/sqlite3-bind`: .. idio:function:: sqlite3/sqlite3-bind stmt [idx val ...] Replace parameters in `stmt` :param stmt: SQL statement :type stmt: C/pointer to :ref:`sqlite3/stmt ` :return: sqlite3 return code :rtype: C/int :raises ^rt-sqlite3-error: Arguments should be supplied in `idx` `val` tuples. `idx` can be an integer or a (named parameter) string. The sqlite3 *type* will be inferred from `val`'s :lname:`Idio` type. .. tip:: parameters are indexed from 1 .. seealso:: :ref:`sqlite3-bind-blob ` :ref:`sqlite3-bind-double ` :ref:`sqlite3-bind-int ` :ref:`sqlite3-bind-null ` :ref:`sqlite3-bind-text ` .. _`sqlite3/sqlite3-bind-parameter-index`: .. idio:function:: sqlite3/sqlite3-bind-parameter-index stmt key Return the index of parameter `key` in `stmt` :param stmt: SQL statement :type stmt: C/pointer to :ref:`sqlite3/stmt ` :param key: parameter name :type key: string :return: parameter index :rtype: fixnum :raises ^rt-sqlite3-error: .. _`sqlite3/sqlite3-step`: .. idio:function:: sqlite3/sqlite3-step stmt Return the next row for `stmt` :param stmt: SQL statement :type stmt: C/pointer to :ref:`sqlite3/stmt ` :return: list of columns :rtype: list or ``#f`` :raises ^rt-sqlite3-error: .. _`sqlite3/sqlite3-column`: .. idio:function:: sqlite3/sqlite3-column stmt idx Return column `idx` for the current row of `stmt` :param stmt: SQL statement :type stmt: C/pointer to :ref:`sqlite3/stmt ` :param idx: column index :type idx: fixnum :return: column :rtype: based on column type :raises ^rt-sqlite3-error: .. tip:: columns are indexed from 0 .. _`sqlite3/sqlite3-reset`: .. idio:function:: sqlite3/sqlite3-reset stmt Reset `stmt` :param stmt: SQL statement :type stmt: C/pointer to :ref:`sqlite3/stmt ` :return: sqlite3 return code :rtype: C/int :raises ^rt-sqlite3-error: .. _`sqlite3/sqlite3-exec`: .. idio:function:: sqlite3/sqlite3-exec db sql [callback] Execute `sql` against `db` :param db: SQL statement :type db: C/pointer to :ref:`sqlite3-db ` :param sql: SQL statement text :type sql: string :param callback: callback function, defaults to none :type callback: function, optional :return: sqlite3 return code :rtype: C/int :raises ^rt-sqlite3-error: For each row in the results, `callback` will be invoked with two arguments: a list of column values as strings; a list of column names. .. _`sqlite3/sqlite3-version`: .. idio:function:: sqlite3/sqlite3-version Return the sqlite3 version :return: sqlite3 version :rtype: string .. include:: ../commit.rst