Orientation

Six short lessons before any building. You see what SkySutra does, check what you need from Turnout, learn just enough astronomy and Vedic sky lore to follow every later part, and get your workspace and an empty app ready.

How Part 0 works

SkySutra is the second Kathuko APEX course. It assumes you've built Turnout, or that you already know APEX basics, and it doesn't teach those again. What's new here is the data: in Turnout people typed everything in, while in SkySutra most data arrives by itself, from star catalogs, web services and calculations.

You build one app, part by part. Each part's downloads are the SQL scripts and files its lessons use. There's no app export per part, as there was in Turnout. There's one export of the finished app, at the end of Part 12, to compare with yours.

Two colors carry meaning all through the app and these notes. Blue is astronomy: measured, checkable, the same for everyone. Saffron is tradition: names, stories and the calendar of the Vedic sky. Every saffron panel says so, and SkySutra never mixes the two up.

Lesson 0.1 — A tour of SkySutra

Outcome: say what SkySutra does in four words, and name the data behind each one.

The idea. SkySutra shows the real night sky over wherever you are. Next to the astronomy it shows the astronomy inside the Vedic tradition: the 27 nakshatras as real stars, the lunar day as an angle you can measure. Sutra means thread: the app's motif is the line that joins stars into a pattern. The tagline: The threads between the stars.

It does four things.

Here is Tonight for Wesley Chapel, Florida, SkySutra's default place, on Friday, October 23, 2026, at 8:30 pm. Every number came out of the packages you'll write in Part 3:

The last row is saffron: names and counting from the Vedic calendar, all worked out from the same Sun and Moon positions as the blue rows above it. Lesson 0.4 explains each one.

Who uses it.

All three are in the sample data you'll load in Part 1.

Try it. Step outside tonight, or look out of a window, and note one thing you can see in the sky and roughly where (low in the east, high overhead). Keep the note: you'll find it in SkySutra in Part 5.

Lesson 0.2 — What you need from Turnout

Outcome: check that you know the APEX skills SkySutra builds on, and know where to look each one up.

The idea. SkySutra moves fast through things Turnout taught slowly. When a lesson says "create a PL/SQL package" or "add an authorization scheme", it won't repeat the clicks. Use this table to find them in Turnout.

What SkySutra adds is listed in each part's table, marked New. Among them: REST Data Sources and synchronization, Data Load Definitions, Template Components, a region plugin, Faceted Search, the Map region with Spatial queries, workflows and human tasks, push notifications, vector search, JSON duality views and PDF output.

Try it. Go down the table and tick each row you could do without looking. For any row you can't, open that Turnout lesson now and skim it: ten minutes here saves an hour later.

Lesson 0.3 — The sky in ten minutes

Outcome: read any position SkySutra shows, and know why the sky turns.

The idea. You need five ideas, no more. Each one becomes a column or a function later.

1. Altitude and azimuth: where to look

Altitude is the angle above the horizon: 0° on the horizon, 90° straight overhead. Below 0° the object is set. Azimuth is the compass direction, measured from north through east: 0° north, 90° east, 180° south, 270° west.

So "Vega, altitude 57°, azimuth about 290°" means: face west-northwest, and look a bit more than halfway up. A fist held at arm's length covers about 10°, so that's between five and six fists above the horizon.

Altitude and azimuth depend on where you are and when you look. That's why SkySutra computes them every time and never stores them as facts about a star (Lesson 1.6).

2. Right ascension and declination: where it is on the sky

Stars need an address that doesn't change from place to place. Picture Earth's equator and poles projected out onto the sky. Declination (Dec) is like latitude: degrees north (+) or south (−) of that sky equator. Right ascension (RA) is like longitude, measured eastward from the point where the Sun crosses the equator in March.

Star atlases write RA in hours, from 0h to 24h, because the sky turns once a day: 1 hour of RA is 15°. SkySutra stores both as decimal degrees: Aldebaran is RA 68.98°, Dec +16.51°. The catalog in Part 2 lists all 9,096 stars this way.

The address drifts very slowly, because Earth's axis wobbles in a 26,000-year circle (precession). Catalogs give positions for a fixed date, the year 2000, and SkySutra corrects them to today.

3. Why the sky turns

Earth spins once in 23 hours 56 minutes measured against the stars: a sidereal day. That's 4 minutes shorter than the 24-hour solar day, because Earth also moves along its orbit. So every star rises about 4 minutes earlier each night, and the evening sky shifts with the seasons.

Sidereal time is the sky's own clock: it tells you which RA is due south right now. Turning RA and Dec into altitude and azimuth takes your latitude, your longitude and the sidereal time. That's one PL/SQL function, written in Lesson 3.3.

One star barely moves. Polaris sits almost exactly at the north celestial pole, so it stays put while everything circles it, at an altitude equal to your latitude: about 28° from Wesley Chapel.

4. Magnitude: how bright

Astronomers measure brightness on a backwards scale: smaller is brighter. Each step is about 2.5 times brighter, so five steps make a factor of 100.

The catalog stops at about magnitude 6.5, everything a person can see without a telescope. A filter in Part 6 lets you hide stars too faint for your sky.

5. UTC: one clock for the sky

Astronomical events happen at one instant everywhere, so SkySutra stores every time in UTC (Coordinated Universal Time) and shows local time only on the screen. 8:30 pm in Wesley Chapel in October (EDT, UTC−4) is 00:30 UTC the next day. When the clocks change on November 1, the stored times don't move at all; only what's displayed shifts. Lesson 1.5 builds the tables this way.

Try it. Tonight, find Polaris. Face north (a phone compass helps) and look about three fists up from Florida, more if you live farther north: it's the moderately bright star sitting on its own there. Estimate its altitude with your fists. You should get close to your latitude.

Lesson 0.4 — Vedic sky, in plain English

Outcome: explain the four Vedic ideas SkySutra shows, and what the app will never do with them.

The idea. The Vedic tradition watched the same sky, with its own names and its own way of counting. Everything SkySutra shows from it can be measured, so it fits next to the astronomy, in saffron.

Nakshatras: the Moon's 27 stations

The Moon goes round the sky against the stars in about 27.3 days. The tradition divides its path, the band of sky the Sun and Moon move along (the ecliptic), into 27 equal slices of 13°20′ each: the nakshatras, or lunar mansions. Roughly one for each night of the Moon's circuit.

Each nakshatra has a junction star (yogatara), a real star you can find. A few you may already know:

In Part 1 each nakshatra becomes a row with its slice of the ecliptic and a link to its star in the catalog.

Tithi: the lunar day

A tithi is a lunar day. It counts how far the Moon has pulled ahead of the Sun. At new Moon they're together; every 12° the Moon gains starts a new tithi. 360° ÷ 12° = 30 tithis in a lunar month:

• tithis 1 to 15, the waxing half, Shukla: from Pratipada (the first) to Purnima (full Moon)
• tithis 16 to 30, the waning half, Krishna: back to Amavasya (new Moon)

On October 23, 2026, the Moon was about 152° ahead of the Sun: 152 ÷ 12 is 12 and a bit, so it was the 13th tithi, Shukla Trayodashi. Because the Moon's speed varies, a tithi lasts anywhere from about 19 to 26 hours, so it rarely lines up with a calendar day. Calendars name the day by the tithi at sunrise; SkySutra shows the tithi in force right now.

Sidereal and tropical: two zeros

Measuring along the ecliptic needs a zero point. Western astronomy and astrology use the tropical zero: where the Sun crosses the equator in March. The Vedic tradition uses a sidereal zero, fixed against the stars.

They used to agree. But precession (Lesson 0.3) slides the March point backward against the stars, about 1° every 72 years. Today the gap is about 24°. That's why, in early October, the Sun is "in Libra" on a Western calendar but in Kanya (Virgo) on a Vedic one: the same Sun, measured from two different zeros.

The ayanamsa: the gap, as a number

The gap between the two zeros is the ayanamsa. SkySutra uses the Lahiri ayanamsa, the one India's Calendar Reform Committee chose in the 1950s, which puts the star Spica (Chitra) at exactly 180° sidereal. It was 23°51′ at the start of 2000 and grows by about 50″ a year: 24°13′39″ on October 23, 2026, by SkySutra's count, within half a minute of arc of published tables.

Because it changes, the ayanamsa is stored as a dated value in a table, not a constant in code (Lesson 1.7). Sidereal longitude = tropical longitude − ayanamsa. The Moon's nakshatra is its sidereal longitude divided into 13°20′ slices.

What "no predictions" means

SkySutra shows the sky and the tradition's names and counting. It never tells anyone what the sky means for them.

It's a design rule, not a judgment on anyone's beliefs. Every number SkySutra shows can be checked against an observatory or a published table; a prediction can't. It is also why the "Today in the sky" card has four items and not a full almanac (panchang): the other almanac items are mainly used for choosing auspicious times. The AI in Part 11 follows the same rule and says so when someone asks for a prediction.

Try it. Look up today's tithi in any published Hindu calendar. Then work it out: find the Sun–Moon angle (a sky app or the Naval Observatory will give both longitudes), divide by 12, round down, add 1. After Part 3, SkySutra does this for you.

Lesson 0.5 — Set up your workspace

Outcome: a workspace that's ready for SkySutra, and an empty SkySutra app with its icon, dark from the first page.

The idea. Before anything else, check the three things SkySutra leans on: APEX 26.2, a database that can reach web services, and the AI service you set up in Turnout. Then create the app as an almost empty shell, for the same reason as Turnout (Lesson 4.1): you add each page on purpose. The tables come in Part 1.

Which workspace?

Your Turnout workspace is fine. Every SkySutra table and package starts with SS_, so nothing clashes with Turnout's TO_ objects, and you can reuse the web credentials and the AI service you already made. If you'd rather keep the two apart, request a second free workspace the same way as Turnout Part 0.

1. Check the version

SQL Workshop › SQL Commands. Run:

select version_no from apex_release;

It should say 26.2.0 or higher.

2. Check that the database can reach the web

SkySutra gets live data from CelesTrak (satellite orbits) and NOAA's Space Weather Prediction Center. Run each of these; both should return the start of a JSON reply:

select substr(apex_web_service.make_rest_request(
         p_url => 'https://services.swpc.noaa.gov/products/noaa-planetary-k-index.json',
         p_http_method => 'GET'), 1, 300) space_weather
  from dual;

select substr(apex_web_service.make_rest_request(
         p_url => 'https://celestrak.org/NORAD/elements/gp.php?CATNR=25544&FORMAT=json',
         p_http_method => 'GET'), 1, 300) iss
  from dual;

The first is the last week of the Kp index, how stirred up the Earth's magnetic field is (Part 4 turns it into an aurora chance); the second is the ISS's orbit. If either fails with a network or certificate error, note it: Lesson 4.5 covers what to do when a service can't be reached.

3. Check your AI service

In the SkySutra app you'll create in step 4, or in Turnout, open Shared Components › AI Services: it lists the workspace's Generative AI Services. You should see the service from Turnout Lesson 11.4, such as Turnout AI. AI services belong to the workspace, so SkySutra can use it as it is. No service yet? You don't need one until Part 11; Lesson 11.2 points back to Turnout 11.4 when you do.

4. Create the app

1. Download the app icon, skysutra-icon-maskable-512.png, from this course's downloads. It's the square version: APEX rounds the corners itself.
2. App Builder › Create. On the Create an Application page, click Use Create App Wizard (not the big Create Application button, which skips the settings).
3. Click the icon square left of Name. In Choose Application Icon, click Upload your own icon and pick skysutra-icon-maskable-512.png. Leave the crop as it is and click Save Icon.
4. Name: SkySutra.
5. Click Appearance. Pick Vita - Dark under Theme Style and Top Menu under Navigation. Save Changes.
6. Leave Pages as the single Home page, and every Feature unchecked. Under Settings, check that Authentication is Oracle APEX Accounts.
7. Click Create Application. APEX builds pages 0 (Global Page), 1 Home and 9999 Login Page.

5. Finish the settings

1. Make sure it's dark. On our run, the wizard kept the default Iris style even though Appearance said Vita - Dark. Open Shared Components › Themes, click Universal Theme - 42, set Current Theme Style to Vita - Dark, and Apply Changes. (Part 5 replaces it with SkySutra's own three styles.)

2. Check the URL settings. Shared Components › Application Definition: Application Alias should already be SKYSUTRA and Friendly URLs on. In 26.2 the wizard sets both, so there's nothing to change, unlike Turnout's Lesson 4.1.

3. Rename the first menu entry. Shared Components › Navigation Menu, the list Navigation Menu, then the Home entry. Set List Entry Label to Tonight and Icon to fa-moon-o. Apply Changes. Page 1 becomes the Tonight page in Part 5.

4. Say hello on page 1. Without this, signing in lands on a page with nothing on it, which looks broken. Open page 1 in Page Designer and click its only region, SkySutra (a Hero region showing the app icon). Set Title to SkySutra and Source › HTML Code to:

   <p>The threads between the stars.</p>
   <p>You are signed in as <strong>&APP_USER.</strong>. Tonight's sky arrives in Part 5.</p>
   

   Save. &APP_USER. is replaced by whoever is signed in.

Check: run the app. The sign-in page is dark, with the SkySutra icon above the form. Sign in with your workspace username and you land on the SkySutra welcome with your username in it and Tonight in the top menu, at an address ending in /r/<your workspace>/skysutra/home.

Lesson 0.6 — Signing in

Outcome: people sign in to SkySutra with an APEX account or with Google, and one of them is a Moderator.

The idea. Turnout built its own sign-in with email codes (Part 5). SkySutra keeps it simpler, because its sign-in isn't what the course is about:

Moderators are a site-wide role, like Turnout's site admins, so they use APEX's Access Control, just as Turnout Lesson 6.5 did.

1. Test people as APEX accounts

Administration (the person-and-wrench icon at the bottom left) › Manage Users and Groups › Create User. For each of the three sample people:

Click Create and Create Another for the first two, Create User for the last. They're end users: they can sign in to apps in this workspace, and can't touch App Builder. APEX stores usernames in capitals, so they sign in as ASHA.RAO@EXAMPLE.COM, whatever case they type.

2. The Moderator role

1. Shared Components › Application Access Control. Under Roles, click Add Role. Name Moderator, Description Approves or returns shared observations before they go public. Create Role.
2. Click the new role to open it. APEX gave it the Static ID moderator, in lower case. Change it to MODERATOR and Apply Changes. Why: apex_acl.has_user_role upper-cases the static ID you pass it, so on our run a lower-case static ID never matched, and every check said "not a moderator". Turnout's ADMINISTRATOR was in capitals, which is why it never bit there.
3. Under User Role Assignments, click Add User Role Assignment. User Name MAYA.LOPEZ@EXAMPLE.COM, tick Moderator, Create Assignment.

Check it in SQL Commands:

begin
    dbms_output.put_line('Maya: ' || case when apex_acl.has_user_role(
        p_application_id  => 199978,              -- your SkySutra app id
        p_user_name       => 'MAYA.LOPEZ@EXAMPLE.COM',
        p_role_static_id  => 'MODERATOR') then 'moderator' else 'not a moderator' end);
end;
/

It should print Maya: moderator. Try Asha: not a moderator.

3. An authorization scheme for pages

Pages ask authorization schemes, not roles. Shared Components › Authorization Schemes › Create. Keep From Scratch, Next.

Create Authorization Scheme. Part 8's moderation inbox uses it.

4. Continue with Google

You need Turnout's Google sign-in web credential (Turnout 5.5). It belongs to the workspace, and the redirect URL you registered with Google, https://oracleapex.com/ords/apex_authentication.callback, is the same for every app on apex.oracle.com, so SkySutra reuses both. Starting fresh? Do Turnout 5.5's steps 1 and 2 first, or skip this section: the button stays hidden until you switch it on.

1. Shared Components › Authentication Schemes › Create. Keep Based on a pre-configured scheme from the gallery, Next.
2. Fill in:

3. Create Authentication Scheme. In 26.2 the new scheme does not become the current one: the list still shows Oracle APEX Accounts as current, which is what you want.
4. Open Google again, set Switch in Session to Enabled, and Apply Changes.

Why upper case: APEX accounts arrive as MAYA.LOPEZ@EXAMPLE.COM. With Google set the same way, someone who uses both arrives as the same APP_USER either way, and one Access Control assignment covers both.

5. Shared Components › Application Settings › Create Setting. Static ID GOOGLE_SIGN_IN, Value N, Valid Values Y, N, On Upgrade Keep Value on. Create Application Setting.
6. Open page 9999 in Page Designer. Right-click the SkySutra region and choose Create Button:

Save. Google after APEX_AUTHENTICATION= is the scheme's Name, exactly as you typed it, capital G included. Not its Static ID: on our run, APEX_AUTHENTICATION=google (the static ID) quietly sent people back to the sign-in page, and Google went straight to Google. The 0 in the session position starts a fresh session for the new scheme.

A failed Google sign-in sticks. If Google shows an error, or you cancel at Google's page, your browser keeps an APEX session that's tied to the Google scheme. Go back to the sign-in page and type a password, and APEX checks it against Google: you get Invalid Login Credentials however right the password is. You can see it in Monitor Activity (or apex_workspace_access_log): the attempts show Google as the authentication method. To put the password sign-in back, open the app with the other scheme's name in the URL: f?p=<your app id>:1:0:APEX_AUTHENTICATION=Oracle%20APEX%20Accounts (%20 is a space; the name must match the scheme's name exactly). APEX switches the session back and shows the sign-in page, and the password works. A private window, or clearing oracleapex.com's cookies, does the same.

To show the button, open Shared Components › Application Settings (under Application Logic), click GOOGLE_SIGN_IN, set Value to Y, and Apply Changes.

What's missing for now: a SkySutra profile row for each person who signs in. Its table, SS_USERS, arrives in Part 1, and Lesson 1.3 adds a post-authentication procedure that creates the row and, as in Turnout 5.5, trusts only an email Google has verified.

Check: run the app and sign in as asha.rao@example.com. You land on Tonight with ASHA.RAO@EXAMPLE.COM in the navigation bar. With GOOGLE_SIGN_IN at Y, sign out, click Continue with Google, and you come back as your own Gmail address, in capitals.

Before you move on

• You can say what Tonight, Explore, Log and Ask each do
• Every row of the Lesson 0.2 table is ticked, or you've skimmed that Turnout lesson
• You can explain altitude, azimuth, RA, Dec and magnitude in a sentence each
• You can work out a tithi from the Sun–Moon angle
• Both web-service checks in Lesson 0.5 returned JSON
• The SkySutra app runs, dark, with Tonight in the menu
• Maya is a moderator and Asha isn't
• The Part 0 quiz below is passed

Troubleshooting

Review questions

Try each one before you open it. The graded quiz is at the end of the page.