z_db (zotonic_core v1.0.0-rc.11)

Interface to database, uses database definition from Context

Link to this section Summary

Functions

Check if a name is a valid SQL table name. Crashes when invalid
Return property lists of the results of a query on the database in the Context
Check if a column exists in a table.
Return a list with the column names of a table. The names are sorted.
Return a property list with all columns of the table. (example: [{id,int4,modifier},...])
Ensure that a table with the given columns exists, alter any existing table to add, modify or drop columns. The 'id' (with type serial) column _must_ be defined when creating the table.
Return the version of the database. Returns {postgres, Major, Minor} for the database being used.
Return the version of the database. This is the long string describing the database version. Returns the empty string if there is no database.
Delete a row from a table, the row must have a column with the name 'id'
Make sure that a table is dropped, only when the table exists
Estimate the number of rows matching a query. This uses the PostgreSQL query planner to return an estimate of the number of rows.
Flush all cached information about the database.
Check if we have database connection up and runnng
Insert a new row in a table, use only default values.
Insert a row, setting the fields to the props. Unknown columns are serialized in the props column. When the table has an 'id' column then the new id is returned.
Check if all cols are valid columns in the target table, move unknown properties to the props column (if exists).
Create database and schema if they do not yet exist
Check whether schema exists
Read a row from a table, the row must have a column with the name 'id'. The props column contents is merged with the other properties returned.
Check the information schema if a certain table exists in the context database.
Convert a value so that it is compatible with the column type
Perform a function inside a transaction, do a rollback on exceptions
Perform a transaction with extra options. Default retry on deadlock
Clear any transaction in the context, useful when starting a thread with this context.
Update a row in a table, merging the props list with any new props values
Update the sequence of the ids in the table. They will be renumbered according to their position in the id list.

Link to this section Types

Link to this type

column_name/0

-type column_name() :: atom() | string() | binary().
Link to this type

database_server/0

-type database_server() :: postgresql.
-type id() :: pos_integer().
-type parameter() ::
    tuple() |
    calendar:datetime() |
    atom() |
    string() |
    binary() |
    integer() |
    boolean() |
    float() |
    list().
Link to this type

parameters/0

-type parameters() :: [parameter()].
-type prop_key() :: binary() | atom().
-type props() :: proplists:proplist() | props_map().
-type props_map() :: #{prop_key() => term()}.
Link to this type

qmap_option/0

-type qmap_option() :: {keys, binary | atom} | {timeout, non_neg_integer()}.
Link to this type

qmap_options/0

-type qmap_options() :: [qmap_option()].
Link to this type

query_error/0

-type query_error() :: nodb | enoent | epgsql:query_error() | term().
Link to this type

query_result/0

-type query_result() ::
    {ok, Columns :: list(), Rows :: list()} |
    {ok, Count :: non_neg_integer(), Columns :: list(), Rows :: list()} |
    {ok, Count :: non_neg_integer()} |
    {error, term()}.
Link to this type

query_timeout/0

-type query_timeout() :: integer().
Link to this type

schema_name/0

-type schema_name() :: default | atom() | string() | binary().
-type sql() :: string() | iodata().
Link to this type

table_name/0

-type table_name() :: atom() | string() | binary().
Link to this type

transaction_fun/0

-type transaction_fun() :: fun((z:context()) -> term()).

Link to this section Functions

Link to this function

assert_table_name(A)

-spec assert_table_name(table_name()) -> true.
Check if a name is a valid SQL table name. Crashes when invalid
Link to this function

assoc(Sql, Context)

-spec assoc(sql(), z:context()) -> [proplists:proplist()].
Return property lists of the results of a query on the database in the Context
Link to this function

assoc(Sql, Parameters, Context)

-spec assoc(sql(), list(), z:context()) -> [proplists:proplist()].
Link to this function

assoc(Sql, Parameters, Context, Timeout)

-spec assoc(sql(), list(), z:context(), integer()) -> [proplists:proplist()].
Link to this function

assoc_props(Sql, Context)

-spec assoc_props(sql(), z:context()) -> [proplists:proplist()].
Link to this function

assoc_props(Sql, Parameters, Context)

-spec assoc_props(sql(), list(), z:context()) -> [proplists:proplist()].
Link to this function

assoc_props(Sql, Parameters, Context, Timeout)

-spec assoc_props(sql(), list(), z:context(), integer()) -> [proplists:proplist()].
Link to this function

assoc_props_row(Sql, Context)

-spec assoc_props_row(sql(), z:context()) -> proplists:proplist() | undefined.
Link to this function

assoc_props_row(Sql, Parameters, Context)

-spec assoc_props_row(sql(), list(), z:context()) -> proplists:proplist() | undefined.
Link to this function

assoc_row(Sql, Context)

-spec assoc_row(sql(), z:context()) -> proplists:proplist().
Link to this function

assoc_row(Sql, Parameters, Context)

-spec assoc_row(sql(), parameters(), z:context()) -> proplists:proplist() | undefined.
Link to this function

column(Table, Column, Context)

-spec column(table_name(), column_name(), z:context()) -> {ok, #column_def{}} | {error, enoent}.
Link to this function

column_exists(Table, Column, Context)

-spec column_exists(table_name(), column_name(), z:context()) -> boolean().
Check if a column exists in a table.
Link to this function

column_names(Table, Context)

-spec column_names(table_name(), z:context()) -> [atom()].
Return a list with the column names of a table. The names are sorted.
Link to this function

column_names_bin(Table, Context)

-spec column_names_bin(table_name(), z:context()) -> [binary()].
Link to this function

columns(Table, Context)

-spec columns(table_name(), z:context()) -> [#column_def{}].
Return a property list with all columns of the table. (example: [{id,int4,modifier},...])
Link to this function

columns(Schema, Table, Context)

-spec columns(schema_name(), table_name(), z:context()) -> [#column_def{}].
Link to this function

constraint_exists(Table, Constraint, Context)

-spec constraint_exists(table_name(), binary() | string() | atom(), z:context()) -> boolean().
Link to this function

create_table(Table, Cols, Context)

-spec create_table(table_name(), list(), z:context()) -> ok.
Ensure that a table with the given columns exists, alter any existing table to add, modify or drop columns. The 'id' (with type serial) column _must_ be defined when creating the table.
Link to this function

database_version(Context)

-spec database_version(z:context()) ->
                    {ok, {database_server(), non_neg_integer(), non_neg_integer()}} |
                    {error, no_database_connection}.
Return the version of the database. Returns {postgres, Major, Minor} for the database being used.
Link to this function

database_version_string(Context)

-spec database_version_string(z:context()) -> binary().
Return the version of the database. This is the long string describing the database version. Returns the empty string if there is no database.
Link to this function

delete(Table, Id, Context)

-spec delete(Table :: table_name(), Id :: integer(), z:context()) ->
          {ok, RowsDeleted :: non_neg_integer()} | {error, term()}.
Delete a row from a table, the row must have a column with the name 'id'
Link to this function

drop_schema(Context)

Link to this function

drop_table(Table, Context)

-spec drop_table(table_name(), z:context()) -> ok.
Make sure that a table is dropped, only when the table exists
Link to this function

ensure_database(Site, Options)

Link to this function

ensure_schema(Site, Options)

Link to this function

equery(Sql, Context)

Link to this function

equery(Sql, Parameters, Context)

Link to this function

equery(Sql, Parameters, Context, Timeout)

-spec equery(sql(), parameters(), z:context(), integer()) -> query_result().
Link to this function

estimate_rows(Query, Args, Context)

-spec estimate_rows(Query, Args, Context) -> {ok, Rows} | {error, term()}
                 when
                     Query :: string() | binary(),
                     Args :: list(),
                     Context :: z:context(),
                     Rows :: non_neg_integer().
Estimate the number of rows matching a query. This uses the PostgreSQL query planner to return an estimate of the number of rows.
Flush all cached information about the database.
Link to this function

get_current_props(Table, Id, Context)

Link to this function

has_connection(Site)

-spec has_connection(z:context() | atom()) -> boolean().
Check if we have database connection up and runnng
Link to this function

insert(Table, Context)

-spec insert(table_name(), z:context()) -> {ok, pos_integer() | undefined} | {error, term()}.
Insert a new row in a table, use only default values.
Link to this function

insert(Table, Parameters, Context)

-spec insert(table_name(), props(), z:context()) -> {ok, integer() | undefined} | {error, term()}.
Insert a row, setting the fields to the props. Unknown columns are serialized in the props column. When the table has an 'id' column then the new id is returned.
Link to this function

key_exists(Table, Key, Context)

-spec key_exists(table_name(), binary() | string() | atom(), z:context()) -> boolean().
Link to this function

prepare_cols(Cols, Props)

Check if all cols are valid columns in the target table, move unknown properties to the props column (if exists).
Link to this function

prepare_database(Context)

-spec prepare_database(z:context()) -> ok | {error, term()}.
Create database and schema if they do not yet exist
Link to this function

q1(Sql, Context)

Link to this function

q1(Sql, Parameters, Context)

Link to this function

q1(Sql, Parameters, Context, Timeout)

-spec q1(sql(), parameters(), #context{}, pos_integer()) -> term() | undefined.
Link to this function

q(Sql, Context)

Link to this function

q(Sql, Parameters, Context)

Link to this function

q(Sql, Parameters, Context, Timeout)

Link to this function

q_row(Sql, Context)

Link to this function

q_row(Sql, Args, Context)

Link to this function

qmap(Sql, Context)

-spec qmap(sql(), z:context()) -> {ok, [map()]} | {error, query_error()}.
Link to this function

qmap(Sql, Args, Context)

-spec qmap(sql(), parameters(), z:context()) -> {ok, [map()]} | {error, query_error()}.
Link to this function

qmap(Sql, Args, Options, Context)

-spec qmap(sql(), parameters(), qmap_options(), z:context()) -> {ok, [map()]} | {error, query_error()}.
Link to this function

qmap_props(Sql, Context)

-spec qmap_props(sql(), z:context()) -> {ok, [map()]} | {error, query_error()}.
Link to this function

qmap_props(Sql, Args, Context)

-spec qmap_props(sql(), parameters(), z:context()) -> {ok, [map()]} | {error, query_error()}.
Link to this function

qmap_props(Sql, Args, Options, Context)

-spec qmap_props(sql(), parameters(), list(), z:context()) -> {ok, [map()]} | {error, query_error()}.
Link to this function

qmap_props_row(Sql, Context)

-spec qmap_props_row(sql(), z:context()) -> {ok, map()} | {error, query_error()}.
Link to this function

qmap_props_row(Sql, Args, Context)

-spec qmap_props_row(sql(), parameters(), z:context()) -> {ok, map()} | {error, query_error()}.
Link to this function

qmap_props_row(Sql, Args, Options, Context)

-spec qmap_props_row(sql(), parameters(), qmap_options(), z:context()) ->
                  {ok, map()} | {error, query_error()}.
Link to this function

qmap_row(Sql, Context)

-spec qmap_row(sql(), z:context()) -> {ok, map()} | {error, query_error()}.
Link to this function

qmap_row(Sql, Args, Context)

-spec qmap_row(sql(), parameters(), z:context()) -> {ok, map()} | {error, query_error()}.
Link to this function

qmap_row(Sql, Args, Options, Context)

-spec qmap_row(sql(), parameters(), qmap_options(), z:context()) -> {ok, map()} | {error, query_error()}.
Link to this function

quoted_table_name(TableName)

-spec quoted_table_name(table_name()) -> {default | string(), string(), string()}.
Link to this function

schema_exists_conn(Connection, Schema)

-spec schema_exists_conn(epgsql:connection(), string()) -> boolean().
Check whether schema exists
Link to this function

select(Table, Id, Context)

-spec select(table_name(), any(), z:context()) -> {ok, Row :: map()} | {error, term()}.
Read a row from a table, the row must have a column with the name 'id'. The props column contents is merged with the other properties returned.
Link to this function

squery(Sql, Context)

Link to this function

squery(Sql, Context, Timeout)

Link to this function

table_exists(Table, Context)

-spec table_exists(table_name(), z:context()) -> boolean().
Check the information schema if a certain table exists in the context database.
Link to this function

to_column_value(Table, Column, Value, Context)

-spec to_column_value(table_name(), column_name(), term(), z:context()) ->
                   {ok, term()} | {error, term()}.
Convert a value so that it is compatible with the column type
Link to this function

transaction(Function, Context)

-spec transaction(transaction_fun(), z:context()) -> any() | {error, term()}.
Perform a function inside a transaction, do a rollback on exceptions
Link to this function

transaction(Function, Options, Context)

-spec transaction(transaction_fun(), list(), z:context()) -> any() | {error, term()}.
Perform a transaction with extra options. Default retry on deadlock
Link to this function

transaction_clear(Context)

Clear any transaction in the context, useful when starting a thread with this context.
Link to this function

update(Table, Id, Parameters, Context)

-spec update(table_name(), id(), props(), z:context()) ->
          {ok, RowsUpdated :: integer()} | {error, term()}.
Update a row in a table, merging the props list with any new props values
Link to this function

update_sequence(Table, Ids, Context)

-spec update_sequence(table_name(), [integer()], z:context()) -> any().
Update the sequence of the ids in the table. They will be renumbered according to their position in the id list.