NpgsqlRest

Appearance

Comments
Written with Claude
IMPORTANT

As you may notice, this page and pretty much the entire website were obviously created with the help of AI. I wonder how you could tell? Was it a big "Written With Claude" badge on every page? I moved it to the top now (with the help of AI of course) to make it even more obvious. There are a few blogposts that were written by me manually, the old-fashioned way, I hope there will be more in the future, and those have a similar "Human Written" badge. This project (not the website), on the other hand, is a very, very different story. It took me more than two years of painstaking and unpaid work in my own free time. A story that, hopefully, I will tell someday. But meanwhile, what would you like me to do? To create a complex documentation website with a bunch of highly technical articles with the help of AI and fake it, to give you an illusion that I also did that manually? Like the half of itnernet is doing at this point? How does that makes any sense? Is that even fair to you? Or maybe to create this website manually, the old-fashioned way, just for you? While working a paid job for a salary, most of you wouldn't even get up in the morning. Would you like me to sing you a song while we're at it? For your personal entertainment? Seriously, get a grip. Do you find this information less valuable because of the way this website was created? I give my best to fix it to keep the information as accurate as possible, and I think it is very accurate at this point. If you find some mistakes, inaccurancies or problems, there is a comment section at the bottom of every page, which I also made with the help of the AI. And I woould very much appreciate if you leave your feedback there. Look, I'm just a guy who likes SQL, that's all. If you don't approve of how this website was constructed and the use of AI tools, I suggest closing this page and never wever coming back. And good riddance. And I would ban your access if I could know how. Thank you for your attention to this matter.

INTERNAL ​

Also known as

internal, internal_only (with or without @ prefix)

Mark an endpoint as internal-only — accessible via self-referencing calls (proxy annotations and HTTP client types with relative paths) but not exposed as a public HTTP route.

Direct HTTP calls to an internal endpoint return 404. Internal calls via proxy or HTTP client types work normally.

Syntax ​

code
@internal
@internal_only
internal
internal_only

All forms are equivalent.

Example: Internal Helper with Proxy ​

sql
sql
-- Internal helper: returns data but is NOT callable from outside
create function get_cached_rates()
returns json language sql as $$
    select rates from exchange_rates order by fetched_at desc limit 1
$$;
comment on function get_cached_rates() is 'HTTP GET
@internal';

-- Public endpoint that proxies the internal one
create function convert_currency(_amount numeric, _from text, _to text)
returns json language plpgsql as $$
...
$$;
comment on function convert_currency(numeric, text, text) is 'HTTP GET
proxy GET /api/get-cached-rates';
  • GET /api/get-cached-rates → 404 Not Found
  • GET /api/convert-currency?amount=100&from=USD&to=EUR → works (proxies internally)

Example: Internal Helper with HTTP Client Types ​

sql
sql
-- Internal data source
create function get_users()
returns json language sql as $$
    select json_agg(row_to_json(u)) from users u
$$;
comment on function get_users() is 'HTTP GET
@internal';

-- HTTP client type pointing to internal endpoint
create type api_users as (body text);
comment on type api_users is 'GET /api/get-users';

-- Public endpoint composing internal calls
create function get_dashboard(_users api_users)
returns json language plpgsql as $$
begin
    return json_build_object('users', (_users).body::json);
end;
$$;

SQL File Endpoints ​

Works on all endpoint sources — functions, procedures, tables/views (CRUD), and SQL files:

sql
sql
-- sql/internal_helper.sql
-- HTTP GET
-- @internal
select * from cached_data;

Comments