Salam
Online editor

Standard library · Database

db/postgres

Connecting to PostgreSQL.

import db.postgres
On this page
  1. Types
  2. Functions

This package implements the Postgres protocol directly and needs no outside library; the example needs a running Postgres server, so it is checked and not run. Every row of a result is fetched from the server at once, so RowCount is known before you read any of them.

Types

Database

struct Database
One PostgreSQL connection.
NameTypeDescription
handlevoid*The library pointer.
affectedi64 = 0The number of rows changed by the last statement.
db-postgres-Client.salam
import db
import db.postgres

func main:
    if not postgres.Available():
        println "the Postgres client is not available"
        ret
    end
    println postgres.ClientVersion()
    d := postgres.Open("host=127.0.0.1 port=5432 dbname=shop user=app password=s3cret")
    if not postgres.Ok(d):
        println postgres.Error(d)
        ret
    end
    println postgres.ServerVersion(d), postgres.DatabaseName(d), postgres.UserName(d), postgres.HostName(d), postgres.Port(d)
    println postgres.Ping(d)
    _ := postgres.Exec(d, "CREATE TABLE IF NOT EXISTS items (id SERIAL PRIMARY KEY, name TEXT, price NUMERIC)")
    _ := postgres.Exec(d, "INSERT INTO items (name, price) VALUES (" + postgres.Quote(d, "tea") + ", 12.5)")
    println postgres.ExecCount(d, "UPDATE items SET price = price * 1.1")

    rows := postgres.Query(d, "SELECT id, name, price FROM items ORDER BY id")
    println rows.Ok(), rows.ColumnCount(), rows.RowCount(), rows.ColumnName(1)
    until rows.Next():
        println rows.Int(0), rows.Text(1), rows.Float(2), rows.Int64(0), rows.IsNull(2), rows.ColumnType(1)
    end
    _ := rows.Close()
    println postgres.QueryInt(d, "SELECT COUNT(*) FROM items"), postgres.QueryText(d, "SELECT version()")

    c := postgres.Conn(d)
    tx := c.Begin()
    _ := tx.Exec("DELETE FROM items")
    _ := tx.Rollback()
    println db.QueryInt(c, "SELECT COUNT(*) FROM items"), d.Kind()
    postgres.Reset(d)
    _ := postgres.Close(d)
    _ := postgres.OpenFull("db.example.com", 5432, "app", "s3cret", "shop")
end

Kind

func Kind(): str
The name of the database engine.

The example for this item is shown with the ones above: db-postgres-Client.salam

Ok

func Ok(): bool
It is healthy.

The example for this item is shown with the ones above: db-postgres-Client.salam

Ping

func Ping(): bool
The connection is alive.

The example for this item is shown with the ones above: db-postgres-Client.salam

Exec

func Exec(sql: str): int
Runs one statement; zero means success.

The example for this item is shown with the ones above: db-postgres-Client.salam

Query

func Query(sql: str): dyn db.Rows
Runs a query and returns the rows.

The example for this item is shown with the ones above: db-postgres-Client.salam

Begin

func Begin(): dyn db.Tx
Starts a transaction.

The example for this item is shown with the ones above: db-postgres-Client.salam

LastInsertId

func LastInsertId(): i64
The id of the last inserted row.

The example for this item is shown with the ones above: db-postgres-Client.salam

Changes

func Changes(): i64
The number of rows the last statement changed.

The example for this item is shown with the ones above: db-postgres-Client.salam

Error

func Error(): str
The last error message.

The example for this item is shown with the ones above: db-postgres-Client.salam

Quote

func Quote(s: str): str
Returns the string quoted and escaped, safe for SQL.

The example for this item is shown with the ones above: db-postgres-Client.salam

Close

func Close(): int
Closes and frees it.

The example for this item is shown with the ones above: db-postgres-Client.salam

Rows

struct Rows
The result of one query.
NameTypeDescription
handlevoid*The result pointer.
rowint = -1The index of the current row.
countint = 0The number of rows.

The example for this item is shown with the ones above: db-postgres-Client.salam

Ok

func Ok(): bool
It is healthy.

The example for this item is shown with the ones above: db-postgres-Client.salam

Next

func Next(): bool
Moves to the next row; false when no row is left.

The example for this item is shown with the ones above: db-postgres-Client.salam

ColumnCount

func ColumnCount(): int
The number of columns.

The example for this item is shown with the ones above: db-postgres-Client.salam

RowCount

func RowCount(): int
The number of rows in the result.

The example for this item is shown with the ones above: db-postgres-Client.salam

ColumnName

func ColumnName(col: int): str
The column name.

The example for this item is shown with the ones above: db-postgres-Client.salam

ColumnType

func ColumnType(col: int): int
The type of the column value in the current row, one of the TYPE_... constants in db.

The example for this item is shown with the ones above: db-postgres-Client.salam

IsNull

func IsNull(col: int): bool
The column value is null.

The example for this item is shown with the ones above: db-postgres-Client.salam

Text

func Text(col: int): str
The column value as text.

The example for this item is shown with the ones above: db-postgres-Client.salam

Int

func Int(col: int): int
The column value as an integer.

The example for this item is shown with the ones above: db-postgres-Client.salam

Int64

func Int64(col: int): i64
The column value as a 64 bit integer.

The example for this item is shown with the ones above: db-postgres-Client.salam

Float

func Float(col: int): f64
The column value as a float.

The example for this item is shown with the ones above: db-postgres-Client.salam

Close

func Close(): int
Closes and frees it.

The example for this item is shown with the ones above: db-postgres-Client.salam

Txn

struct Txn
One transaction.
NameTypeDescription
handlevoid*The connection pointer.

The example for this item is shown with the ones above: db-postgres-Client.salam

Ok

func Ok(): bool
It is healthy.

The example for this item is shown with the ones above: db-postgres-Client.salam

Exec

func Exec(sql: str): int
Runs one statement; zero means success.

The example for this item is shown with the ones above: db-postgres-Client.salam

Query

func Query(sql: str): dyn db.Rows
Runs a query and returns the rows.

The example for this item is shown with the ones above: db-postgres-Client.salam

Commit

func Commit(): int
Commits the transaction.

The example for this item is shown with the ones above: db-postgres-Client.salam

Rollback

func Rollback(): int
Rolls the transaction back.

The example for this item is shown with the ones above: db-postgres-Client.salam

Functions

Available

func Available(): bool
The Postgres client is available; since it is inside Salam itself, this is always true.

The example for this item is shown with the ones above: db-postgres-Client.salam

ClientVersion

func ClientVersion(): int
The compatible client version as a number, such as 180000.

The example for this item is shown with the ones above: db-postgres-Client.salam

ServerVersion

func ServerVersion(d: Database): int
The server version as a number.

The example for this item is shown with the ones above: db-postgres-Client.salam

Open

func Open(conninfo: str): Database
Connects with a connection string, such as host=... dbname=..., or a postgresql:// address.

The example for this item is shown with the ones above: db-postgres-Client.salam

OpenFull

func OpenFull(host: str, port: int, user: str, pass: str, dbname: str): Database
Connects with a host, port, user, password and database name.

The example for this item is shown with the ones above: db-postgres-Client.salam

Ok

func Ok(d: Database): bool
The connection is up.

The example for this item is shown with the ones above: db-postgres-Client.salam

Ping

func Ping(d: Database): bool
The connection is alive.

The example for this item is shown with the ones above: db-postgres-Client.salam

Reset

func Reset(d: Database)
Brings a dropped connection back up.

The example for this item is shown with the ones above: db-postgres-Client.salam

Close

func Close(d: Database): int
Closes it.

The example for this item is shown with the ones above: db-postgres-Client.salam

Error

func Error(d: Database): str
The last error message.

The example for this item is shown with the ones above: db-postgres-Client.salam

Exec

func Exec(d: Database, sql: str): int
Runs one statement; zero means success.

The example for this item is shown with the ones above: db-postgres-Client.salam

ExecCount

func ExecCount(d: Database, sql: str): i64
Runs one statement and returns the number of rows changed.

The example for this item is shown with the ones above: db-postgres-Client.salam

Query

func Query(d: Database, sql: str): Rows
Runs a query.

The example for this item is shown with the ones above: db-postgres-Client.salam

Quote

func Quote(d: Database, s: str): str
Returns the string quoted and escaped, safely.

The example for this item is shown with the ones above: db-postgres-Client.salam

DatabaseName

func DatabaseName(d: Database): str
The database name.

The example for this item is shown with the ones above: db-postgres-Client.salam

UserName

func UserName(d: Database): str
The user name.

The example for this item is shown with the ones above: db-postgres-Client.salam

HostName

func HostName(d: Database): str
The host.

The example for this item is shown with the ones above: db-postgres-Client.salam

Port

func Port(d: Database): str
The port.

The example for this item is shown with the ones above: db-postgres-Client.salam

QueryInt

func QueryInt(d: Database, sql: str): int
The first column of the first row as an integer.

The example for this item is shown with the ones above: db-postgres-Client.salam

QueryText

func QueryText(d: Database, sql: str): str
The same, as text.

The example for this item is shown with the ones above: db-postgres-Client.salam

Conn

func Conn(d: Database): dyn db.Connection
Returns the connection as a shared Connection.

The example for this item is shown with the ones above: db-postgres-Client.salam