zyn.Database#

/// A framework-managed PostgreSQL database handle.
pub const Database = struct {
    /// Pagination for typed single-table lists.
    pub const ListOptions = struct {
        /// Maximum rows returned; must be nonzero.
        limit: usize,
        /// Rows skipped after primary-key ordering.
        offset: usize = 0,
    };

    /// A scoped PostgreSQL transaction backed by one pinned connection.
    pub const Transaction = struct {
        /// Enqueues jobs on this transaction's pinned PostgreSQL connection.
        jobs: Transaction.Jobs,
        /// Persists notifications in the surrounding transaction.
        notifications: Transaction.Notifications,
        /// Performs blob lifecycle changes on this transaction's pinned connection.
        storage: Storage.Transaction,

        /// A transaction-scoped background-job enqueue capability.
        pub const Jobs = struct {
            /// Persists one typed background job in the surrounding transaction.
            pub fn enqueue(
                self: *@This(),
                comptime selected_job: []const u8,
                args: anytype,
                options: JobEnqueueOptions,
            ) !void;
        };

        /// A transaction-scoped notification enqueue capability.
        pub const Notifications = struct {
            /// Persists one notification and its worker job atomically.
            pub fn deliver_later(
                self: *@This(),
                comptime selected_notification: []const u8,
                args: anytype,
            ) !void;
        };

        /// Encrypts a field for a raw SQL parameter; cast its placeholder to `bytea`.
        /// Identity contains exactly the complete primary key. The column must be
        /// encrypted; nullable columns accept null. Identity values must match the
        /// actual SQL row. Returned slices have the same allocator and lifetime
        /// as database query results.
        pub fn encrypt_field(
            self: *Transaction,
            comptime Table: type,
            comptime column: []const u8,
            identity: anytype,
            value: @FieldType(Table, column),
        ) !@FieldType(Table, column);

        /// Authenticates and decrypts a raw SQL field result.
        /// Identity contains exactly the complete primary key. The column must be
        /// encrypted; nullable columns accept null. Identity values must match the
        /// actual SQL row. Returned slices have the same allocator and lifetime
        /// as database query results.
        pub fn decrypt_field(
            self: *Transaction,
            comptime Table: type,
            comptime column: []const u8,
            identity: anytype,
            value: @FieldType(Table, column),
        ) !@FieldType(Table, column);

        /// Executes interpolated SQL in the transaction.
        pub fn exec(self: *Transaction, sql: []const u8, values: anytype) !void;

        /// Executes interpolated SQL and returns its optional row-change count.
        pub fn exec_count(
            self: *Transaction,
            sql: []const u8,
            values: anytype,
        ) !?i64;

        /// Maps the first transaction query row to `T`, or returns `null`.
        pub fn one(
            self: *Transaction,
            comptime T: type,
            sql: []const u8,
            values: anytype,
        ) !?T;

        /// Maps every transaction query row to `T`.
        pub fn many(
            self: *Transaction,
            comptime T: type,
            sql: []const u8,
            values: anytype,
        ) ![]T;

        /// Inserts one row using generated table metadata.
        pub fn insert(self: *Transaction, comptime T: type, values: anytype) !void;

        /// Finds one row using a primary or supported unique equality selector.
        pub fn find(self: *Transaction, comptime T: type, filters: anytype) !?T;

        /// Lists bounded rows matching equality filters in primary-key order.
        pub fn list(
            self: *Transaction,
            comptime T: type,
            filters: anytype,
            options: ListOptions,
        ) ![]T;

        /// Updates one row using a primary or supported unique equality selector.
        pub fn update(
            self: *Transaction,
            comptime T: type,
            filters: anytype,
            values: anytype,
        ) !bool;

        /// Deletes one row using a primary or supported unique equality selector.
        pub fn delete(self: *Transaction, comptime T: type, filters: anytype) !bool;

        /// Commits the transaction and releases its pinned connection.
        pub fn commit(self: *Transaction) !void;

        /// Best-effort rolls back an active transaction and releases its connection.
        pub fn cancel(self: *Transaction) void;
    };

    /// Starts a scoped transaction on one pinned PostgreSQL connection.
    pub fn begin(self: *Database) !Transaction;

    /// Inserts one row using generated table metadata.
    pub fn insert(self: *Database, comptime T: type, values: anytype) !void;

    /// Finds one row using a primary or supported unique equality selector.
    pub fn find(self: *Database, comptime T: type, filters: anytype) !?T;

    /// Lists bounded rows matching equality filters in primary-key order.
    pub fn list(
        self: *Database,
        comptime T: type,
        filters: anytype,
        options: ListOptions,
    ) ![]T;

    /// Updates one row using a primary or supported unique equality selector.
    pub fn update(
        self: *Database,
        comptime T: type,
        filters: anytype,
        values: anytype,
    ) !bool;

    /// Deletes one row using a primary or supported unique equality selector.
    pub fn delete(self: *Database, comptime T: type, filters: anytype) !bool;

    /// Encrypts a field for a raw SQL parameter; cast its placeholder to `bytea`.
    /// Identity contains exactly the complete primary key. The column must be
    /// encrypted; nullable columns accept null. Identity values must match the
    /// actual SQL row. Returned slices have the same allocator and lifetime
    /// as database query results.
    pub fn encrypt_field(
        self: *Database,
        comptime Table: type,
        comptime column: []const u8,
        identity: anytype,
        value: @FieldType(Table, column),
    ) !@FieldType(Table, column);

    /// Authenticates and decrypts a raw SQL field result.
    /// Identity contains exactly the complete primary key. The column must be
    /// encrypted; nullable columns accept null. Identity values must match the
    /// actual SQL row. Returned slices have the same allocator and lifetime
    /// as database query results.
    pub fn decrypt_field(
        self: *Database,
        comptime Table: type,
        comptime column: []const u8,
        identity: anytype,
        value: @FieldType(Table, column),
    ) !@FieldType(Table, column);

    /// Executes interpolated SQL.
    pub fn exec(self: *Database, sql: []const u8, values: anytype) !void;

    /// Executes interpolated SQL and returns its optional row-change count.
    pub fn exec_count(self: *Database, sql: []const u8, values: anytype) !?i64;

    /// Maps the first query row to `T`, or returns `null` when there are no rows.
    pub fn one(
        self: *Database,
        comptime T: type,
        sql: []const u8,
        values: anytype,
    ) !?T;

    /// Maps every query row to `T`.
    pub fn many(
        self: *Database,
        comptime T: type,
        sql: []const u8,
        values: anytype,
    ) ![]T;
};